# Create customer

Creates a new customer.

Endpoint: POST /customers/create
Version: 2.0.0
Security: bearerAuth

## Request fields (application/json):

  - `body` (object, required) — one of:
    - Individual:
      - `merchant_customer_id` (string)
        Merchant's identifier for the customer.
        Example: "12345"
      - `email` (string, required)
        Customer email.
        Example: "customer@example.com"
      - `first_name` (string)
        Customer first name.
        Example: "John"
      - `last_name` (string)
        Customer last name.
        Example: "Doe"
      - `phone` (string)
        Customer phone number.
        Example: "+1234567890"
      - `address` (object)
        Customer address.
      - `address.city` (string)
        City name.
        Example: "Anytown"
      - `address.country` (string)
        Country according to the ISO-3166 alpha-3 country code.
        Example: "USA"
      - `address.line1` (string)
        Address line 1.
        Example: "123 Main St"
      - `address.line2` (string)
        Address line 2.
        Example: "Suite 456"
      - `address.state` (string)
        State or province.
        Example: "CA"
      - `address.postal_code` (string)
        Postal or ZIP code.
        Example: "12345"
      - `tax` (object)
        Provides customer tax information.
      - `tax.taxability` (string)
        Indicates if the customer is subject to tax.
        Enum: "EXEMPT", "TAXABLE"
      - `tax.registrations` (array)
        Tax registrations associated with the customer.
        Example: [{"scheme":"VAT","id":"DE123456789","country":"DEU"}]
      - `tax.registrations.scheme` (string, required)
        Tax registration scheme.
        Enum: "VAT"
      - `tax.registrations.id` (string, required)
        Tax registration number for the specified scheme.
        Example: "DE123456789"
      - `tax.registrations.country` (string, required)
        ISO 3166-1 alpha-3 country code.
        Example: "DEU"
      - `tax.registrations.validation` (object)
        Validation result for tax registration.
      - `tax.registrations.validation.status` (string, required)
        Validation status.
        Enum: "UNVERIFIED", "VERIFIED"
      - `tax.registrations.validation.validated_at` (string, required)
        Timestamp when validation was performed.
        Example: "2024-01-15T10:30:00Z"
      - `tax.registrations.validation.source` (string, required)
        Method or external system used for validation.
        Enum: "VIES", "MANUAL"
      - `configuration` (object)
        Customer-level configuration settings.
      - `configuration.default_billing_currency` (string)
        ISO 4217 currency code used as default for billing.
        Example: "USD"
      - `configuration.default_payment_instrument_id` (string)
        Unique identifier of the default payment instrument for this customer.
        Example: "pi_01J1Z2X3Y4W5V6U7T8S9R0"
      - `configuration.preferred_locales` (array)
        Ordered list of preferred locales as BCP 47 tags.
        Example: ["en-US","de-DE"]
      - `metadata` (object)
        Arbitrary key-value metadata set by merchant.
        Example: {"internal_ref":"cust-123"}
      - `type` (string)
        Customer type. Immutable after creation.
        Example: "INDIVIDUAL"
    - Business:
      - `merchant_customer_id` (string)
        Merchant's identifier for the customer.
        Example: "12345"
      - `email` (string, required)
        Customer email.
        Example: "customer@example.com"
      - `first_name` (string)
        Customer first name.
        Example: "John"
      - `last_name` (string)
        Customer last name.
        Example: "Doe"
      - `phone` (string)
        Customer phone number.
        Example: "+1234567890"
      - `address` (object)
        Customer address.
      - `address.city` (string)
        City name.
        Example: "Anytown"
      - `address.country` (string)
        Country according to the ISO-3166 alpha-3 country code.
        Example: "USA"
      - `address.line1` (string)
        Address line 1.
        Example: "123 Main St"
      - `address.line2` (string)
        Address line 2.
        Example: "Suite 456"
      - `address.state` (string)
        State or province.
        Example: "CA"
      - `address.postal_code` (string)
        Postal or ZIP code.
        Example: "12345"
      - `tax` (object)
        Provides customer tax information.
      - `tax.taxability` (string)
        Indicates if the customer is subject to tax.
        Enum: same as `tax.taxability` in "Individual" (2 values)
      - `tax.registrations` (array)
        Tax registrations associated with the customer.
        Example: [{"scheme":"VAT","id":"DE123456789","country":"DEU"}]
      - `tax.registrations.scheme` (string, required)
        Tax registration scheme.
        Enum: same as `tax.registrations.scheme` in "Individual" (1 values)
      - `tax.registrations.id` (string, required)
        Tax registration number for the specified scheme.
        Example: "DE123456789"
      - `tax.registrations.country` (string, required)
        ISO 3166-1 alpha-3 country code.
        Example: "DEU"
      - `tax.registrations.validation` (object)
        Validation result for tax registration.
      - `tax.registrations.validation.status` (string, required)
        Validation status.
        Enum: same as `tax.registrations.validation.status` in "Individual" (2 values)
      - `tax.registrations.validation.validated_at` (string, required)
        Timestamp when validation was performed.
        Example: "2024-01-15T10:30:00Z"
      - `tax.registrations.validation.source` (string, required)
        Method or external system used for validation.
        Enum: same as `tax.registrations.validation.source` in "Individual" (2 values)
      - `configuration` (object)
        Customer-level configuration settings.
      - `configuration.default_billing_currency` (string)
        ISO 4217 currency code used as default for billing.
        Example: "USD"
      - `configuration.default_payment_instrument_id` (string)
        Unique identifier of the default payment instrument for this customer.
        Example: "pi_01J1Z2X3Y4W5V6U7T8S9R0"
      - `configuration.preferred_locales` (array)
        Ordered list of preferred locales as BCP 47 tags.
        Example: ["en-US","de-DE"]
      - `metadata` (object)
        Arbitrary key-value metadata set by merchant.
        Example: {"internal_ref":"cust-123"}
      - `type` (string, required)
        Customer type. Immutable after creation.
        Example: "BUSINESS"
      - `business_details` (object)
        Business-specific details for a customer profile.
      - `business_details.name` (string)
        Legal business name.
        Example: "Acme Corporation"
      - `business_details.legal_address` (object) — one of:
        Registered legal address of the business.
        - Address with state:
          - `city` (string, required)
            City name.
            Example: "Anytown"
          - `country` (string, required)
            Country according to the ISO-3166 alpha-3 country code.
            Enum: "AUS", "BRA", "CAN", "CHN", "IND", "KOR", "MEX", "MYS", "NZL", "USA"
          - `line1` (string, required)
            Address line 1.
            Example: "123 Main St"
          - `line2` (string)
            Address line 2.
            Example: "Suite 456"
          - `state` (string, required)
            State or province.
            Example: "CA"
          - `postal_code` (string, required)
            Postal or ZIP code.
            Example: "12345"
        - Address:
          - `city` (string, required)
            City name.
            Example: "Anytown"
          - `country` (string, required)
            Country according to the ISO-3166 alpha-3 country code.
            Example: "DEU"
          - `line1` (string, required)
            Address line 1.
            Example: "123 Main St"
          - `line2` (string)
            Address line 2.
            Example: "Suite 456"
          - `state` (string)
            State or province.
            Example: "CA"
          - `postal_code` (string, required)
            Postal or ZIP code.
            Example: "12345"

## Response 200 fields (application/json):

  - `body` (object) — one of:
    - Individual:
      - `id` (string, required)
        Unique customer identifier.
        Example: "cust_01KMG2ABYPF6XS5DMJQ817C429"
      - `email` (string, required)
        Customer email.
        Example: "customer@example.com"
      - `first_name` (string)
        Customer first name.
        Example: "John"
      - `last_name` (string)
        Customer last name.
        Example: "Doe"
      - `phone` (string)
        Customer phone number.
        Example: "+1234567890"
      - `merchant_customer_id` (string)
        Merchant's identifier for the customer.
        Example: "12345"
      - `address` (object)
        Customer address.
      - `address.city` (string)
        City name.
        Example: "Anytown"
      - `address.country` (string)
        Country according to the ISO-3166 alpha-3 country code.
        Example: "USA"
      - `address.line1` (string)
        Address line 1.
        Example: "123 Main St"
      - `address.line2` (string)
        Address line 2.
        Example: "Suite 456"
      - `address.state` (string)
        State or province.
        Example: "CA"
      - `address.postal_code` (string)
        Postal or ZIP code.
        Example: "12345"
      - `tax` (object, required)
        Provides customer tax information.
      - `tax.taxability` (string, required)
        Indicates if the customer is subject to tax.
        Enum: same as `tax.taxability` in "Individual" (2 values)
      - `tax.registrations` (array)
        Tax registrations associated with the customer.
        Example: [{"scheme":"VAT","id":"DE123456789","country":"DEU"}]
      - `tax.registrations.scheme` (string, required)
        Tax registration scheme.
        Enum: same as `tax.registrations.scheme` in "Individual" (1 values)
      - `tax.registrations.id` (string, required)
        Tax registration number for the specified scheme.
        Example: "DE123456789"
      - `tax.registrations.country` (string, required)
        ISO 3166-1 alpha-3 country code.
        Example: "DEU"
      - `tax.registrations.validation` (object)
        Validation result for tax registration.
      - `tax.registrations.validation.status` (string, required)
        Validation status.
        Enum: same as `tax.registrations.validation.status` in "Individual" (2 values)
      - `tax.registrations.validation.validated_at` (string, required)
        Timestamp when validation was performed.
        Example: "2024-01-15T10:30:00Z"
      - `tax.registrations.validation.source` (string, required)
        Method or external system used for validation.
        Enum: same as `tax.registrations.validation.source` in "Individual" (2 values)
      - `status` (string, required)
        Customer status.
        Enum: "ACTIVE", "INACTIVE"
      - `configuration` (object)
        Customer-level configuration settings.
      - `configuration.default_billing_currency` (string)
        ISO 4217 currency code used as default for billing.
        Example: "USD"
      - `configuration.default_payment_instrument_id` (string)
        Unique identifier of the default payment instrument for this customer.
        Example: "pi_01J1Z2X3Y4W5V6U7T8S9R0"
      - `configuration.preferred_locales` (array)
        Ordered list of preferred locales as BCP 47 tags.
        Example: ["en-US","de-DE"]
      - `metadata` (object)
        Arbitrary key-value metadata set by merchant.
        Example: {"internal_ref":"cust-123","segment":"enterprise"}
      - `created_at` (string, required)
        Date and time when the customer was created.
        Example: "2024-01-01T10:00:00.000000Z"
      - `updated_at` (string, required)
        Date and time when the customer was updated.
        Example: "2024-01-02T15:00:00.000000Z"
      - `type` (string, required)
        Customer type.
        Example: "INDIVIDUAL"
    - Business:
      - `id` (string, required)
        Unique customer identifier.
        Example: "cust_01KMG2ABYPF6XS5DMJQ817C429"
      - `email` (string, required)
        Customer email.
        Example: "customer@example.com"
      - `first_name` (string)
        Customer first name.
        Example: "John"
      - `last_name` (string)
        Customer last name.
        Example: "Doe"
      - `phone` (string)
        Customer phone number.
        Example: "+1234567890"
      - `merchant_customer_id` (string)
        Merchant's identifier for the customer.
        Example: "12345"
      - `address` (object)
        Customer address.
      - `address.city` (string)
        City name.
        Example: "Anytown"
      - `address.country` (string)
        Country according to the ISO-3166 alpha-3 country code.
        Example: "USA"
      - `address.line1` (string)
        Address line 1.
        Example: "123 Main St"
      - `address.line2` (string)
        Address line 2.
        Example: "Suite 456"
      - `address.state` (string)
        State or province.
        Example: "CA"
      - `address.postal_code` (string)
        Postal or ZIP code.
        Example: "12345"
      - `tax` (object, required)
        Provides customer tax information.
      - `tax.taxability` (string, required)
        Indicates if the customer is subject to tax.
        Enum: same as `tax.taxability` in "Individual" (2 values)
      - `tax.registrations` (array)
        Tax registrations associated with the customer.
        Example: [{"scheme":"VAT","id":"DE123456789","country":"DEU"}]
      - `tax.registrations.scheme` (string, required)
        Tax registration scheme.
        Enum: same as `tax.registrations.scheme` in "Individual" (1 values)
      - `tax.registrations.id` (string, required)
        Tax registration number for the specified scheme.
        Example: "DE123456789"
      - `tax.registrations.country` (string, required)
        ISO 3166-1 alpha-3 country code.
        Example: "DEU"
      - `tax.registrations.validation` (object)
        Validation result for tax registration.
      - `tax.registrations.validation.status` (string, required)
        Validation status.
        Enum: same as `tax.registrations.validation.status` in "Individual" (2 values)
      - `tax.registrations.validation.validated_at` (string, required)
        Timestamp when validation was performed.
        Example: "2024-01-15T10:30:00Z"
      - `tax.registrations.validation.source` (string, required)
        Method or external system used for validation.
        Enum: same as `tax.registrations.validation.source` in "Individual" (2 values)
      - `status` (string, required)
        Customer status.
        Enum: same as `status` in "Individual" (2 values)
      - `configuration` (object)
        Customer-level configuration settings.
      - `configuration.default_billing_currency` (string)
        ISO 4217 currency code used as default for billing.
        Example: "USD"
      - `configuration.default_payment_instrument_id` (string)
        Unique identifier of the default payment instrument for this customer.
        Example: "pi_01J1Z2X3Y4W5V6U7T8S9R0"
      - `configuration.preferred_locales` (array)
        Ordered list of preferred locales as BCP 47 tags.
        Example: ["en-US","de-DE"]
      - `metadata` (object)
        Arbitrary key-value metadata set by merchant.
        Example: {"internal_ref":"cust-123","segment":"enterprise"}
      - `created_at` (string, required)
        Date and time when the customer was created.
        Example: "2024-01-01T10:00:00.000000Z"
      - `updated_at` (string, required)
        Date and time when the customer was updated.
        Example: "2024-01-02T15:00:00.000000Z"
      - `type` (string, required)
        Customer type.
        Example: "BUSINESS"
      - `business_details` (object)
        Business-specific details for a customer profile.
      - `business_details.name` (string)
        Legal business name.
        Example: "Acme Corporation"
      - `business_details.legal_address` (object) — one of:
        Registered legal address of the business.
        - Address with state:
          - `city` (string, required)
            City name.
            Example: "Anytown"
          - `country` (string, required)
            Country according to the ISO-3166 alpha-3 country code.
            Enum: same as `country` in "Address with state" (10 values)
          - `line1` (string, required)
            Address line 1.
            Example: "123 Main St"
          - `line2` (string)
            Address line 2.
            Example: "Suite 456"
          - `state` (string, required)
            State or province.
            Example: "CA"
          - `postal_code` (string, required)
            Postal or ZIP code.
            Example: "12345"
        - Address:
          - `city` (string, required)
            City name.
            Example: "Anytown"
          - `country` (string, required)
            Country according to the ISO-3166 alpha-3 country code.
            Example: "DEU"
          - `line1` (string, required)
            Address line 1.
            Example: "123 Main St"
          - `line2` (string)
            Address line 2.
            Example: "Suite 456"
          - `state` (string)
            State or province.
            Example: "CA"
          - `postal_code` (string, required)
            Postal or ZIP code.
            Example: "12345"

## Response 400 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "VALIDATION"

  - `message` (string, required)
    Message describing the error.
    Example: "One or more fields failed validation due to constraints"

  - `context` (object, required)
    Additional context about the validation error, including specific constraints.
    Example: {"constraints":{"email":{"type":"TYPE","message":"The 'email' field must be a valid email address"},"age":{"type":"MIN","message":"The 'age' field must be a number greater than or equal to 18"}}}

  - `context.constraints` (object, required)
    Failed constraints keyed by the field name.
    Example: {"email":{"type":"TYPE","message":"The 'email' field must be a valid email address"},"age":{"type":"MIN","message":"The 'age' field must be a number greater than or equal to 18"}}

## Response 401 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "UNAUTHENTICATED"

  - `message` (string, required)
    Message describing the error.
    Example: "Credentials are invalid or missing"

## Response 403 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "PERMISSION_DENIED"

  - `message` (string, required)
    Message describing the error.
    Example: "Permission denied"

## Response 422 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "INVALID_DEFAULT_PAYMENT_INSTRUMENT", "INVALID_TAX_REGISTRATION_VALIDATION_SOURCE"

  - `message` (string, required)
    Message describing the error.
    Example: "The request conflicts with the current state"

  - `context` (object)
    Additional error context.

## Response 429 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "RATE_LIMIT"

  - `message` (string, required)
    Message describing the error.
    Example: "Rate limit exhausted"

  - `context` (object)
    Additional context about the error.

  - `context.next_try_at` (string)
    Timestamp indicating when to retry the request.
    Example: "2024-12-31T23:59:59.000000Z"