Create customers

POST

/merchants/{merchantCode}/customers

curl --request POST \
  --url https://customer.shopgate.io/v1/merchants/example/customers \
  --header 'Content-Type: application/json' \
  --data '{ "customers": [ { "externalCustomerNumber": "10001", "firstName": "John", "middleName": "Doug", "lastName": "Doe", "emailAddress": "john.doe@shopgate.com", "password": "superSecurePassword", "status": "active", "isAnonymous": false, "taxExempt": false, "taxClass": "example", "contacts": [ { "externalContactCode": "357709b0-9378-470b-976e-1b040e29b97b", "status": "active", "firstName": "John", "middleName": "Doug", "lastName": "Doe", "companyName": "Shopgate Inc", "address1": "12 Somestreet", "address2": "", "address3": "", "address4": "", "city": "Austin", "postalCode": "78732", "region": "TX", "country": "US", "additionalFields": { "dhlPostBoxNumber": "example", "dhlPostNumber": "example" }, "phone": "000-000-0000", "fax": "000-000-0000", "mobile": "000-000-0000", "emailAddress": "somelocation@someRetailer.com", "isDefaultShipping": false, "isDefaultBilling": false, "externalUpdateDate": "2026-04-15T12:00:00Z" } ], "attributes": [ { "code": "tshirtSize", "value": { "code": "l" } }, { "code": "nameOfCat", "value": "Some Cats Name" } ], "settings": { "defaultLocale": "en-us", "defaultCurrency": "USD", "communicationPreferences": [ "sms", "push" ], "defaultLocationCode": "DERetail001", "marketingOptIn": false }, "externalUpdateDate": "2026-04-15T12:00:00Z" } ] }'

Create customers

Parameters

Path Parameters

merchantCode

required

string

Request Body

Media typeapplication/json

object

customers

required

Array<object>

object

externalCustomerNumber

External Customer number

string

Example

10001

firstName

required

First name of the customer

string

Example

John

middleName

Middle name of the customer

string | null

Example

Doug

lastName

required

Last name of the customer

string

Example

Doe

emailAddress

required

string format: email

Example

john.doe@shopgate.com

password

string

Example

superSecurePassword

status

string

default: active

Allowed values: active inactive deleted

Example

active

isAnonymous

Indicates anonymous/guest customer.

boolean

Example

true

taxExempt

Indicates if customer is exempted from tax.

boolean

Example

true

taxClass

Tax class of the customer.

string | null

contacts

Array

object

externalContactCode

External identifier of the contact

string | null

Example

357709b0-9378-470b-976e-1b040e29b97b

status

string

default: active

Allowed values: active inactive deleted

Example

active

firstName

required

string

Example

John

middleName

string | null

Example

Doug

lastName

required

string

Example

Doe

companyName

string | null

Example

Shopgate Inc

address1

string

Example

12 Somestreet

address2

string | null

Example

address3

string | null

Example

address4

string | null

Example

city

string

Example

Austin

postalCode

string

Example

78732

region

string

Example

TX

country

string

Example

US

additionalFields

object

dhlPostBoxNumber

Number of a postbox

string | null

>= 1 characters <= 5 characters

dhlPostNumber

Number of a post

string | null

>= 1 characters <= 10 characters

phone

Validated according to country code

string | null

Example

000-000-0000

fax

Validated according to country code

string | null

Example

000-000-0000

mobile

Validated according to country code

string | null

Example

000-000-0000

emailAddress

string format: email

Example

somelocation@someRetailer.com

isDefaultShipping

boolean

Example

true

isDefaultBilling

boolean

Example

true

externalUpdateDate

string format: date-time

attributes

Array

Custom customer attribute

object

code

required

Code of the defined customer attribute

string

Example

tshirtSize

value

Value for this attribute. Its a free text field for attributes where no values are set. Attributes which have value set should contains the code in an object. For instance value: { "code": "fish" }

Example

L

name

Human readable name of the attribute

string

Example

T-Shirt size

Example

[
  {
    "code": "tshirtSize",
    "value": {
      "code": "l"
    }
  },
  {
    "code": "nameOfCat",
    "value": "Some Cats Name"
  }
]

settings

All customer settings which are defined by Shopgate

object

defaultLocale

string

Example

en-us

defaultCurrency

string

Example

USD

communicationPreferences

Communication Preferences.

Array<string>

default: sms,push

Allowed values: sms email push

Example

[
  "email",
  "push",
  "sms"
]

defaultLocationCode

string

Example

DERetail001

marketingOptIn

boolean

externalUpdateDate

string format: date-time

Responses

201

Customer created

Media typeapplication/json

object

ids

Array<string>

errors

Array<object>

object

code

number

message

string

validationError

(optional) The original validation error that occured.

object

code

string

message

string

paramName

string

paramValue

string

entity

string

entityIndex

The index of the element the error refers to in the list of elements passed, starting from 0.

number

entityId

string

Example

{
  "ids": [
    "57de7a67-bd83-46e9-8276-c1206c301380"
  ],
  "errors": [
    {
      "code": 409,
      "message": "customer already exists",
      "entity": "customer",
      "entityIndex": 0,
      "entityId": "7a81af64-a25d-11e9-8352-0bb2329f4819"
    },
    {
      "code": 400,
      "message": "Validation error.",
      "validationError": {
        "code": "INVALID_TYPE",
        "message": "Request validation failed: Parameter (externalUpdateDate) at index 1 is not a valid date: today",
        "paramName": "externalUpdateDate",
        "paramValue": "today"
      },
      "entity": "customer",
      "entityIndex": 1,
      "entityId": null
    }
  ]
}

400

Bad request (mostly missing or invalid parameters/values)

Media typeapplication/json

object

errors

Array<object>

object

field

required

The parameter-field, that failed to validate, like “shopNumber”

string

value

The value, that was sent, like “xxx”

string

code

required

Machine readable error code

string

Allowed values: ENUM_MISMATCH MAXIMUM MAXIMUM_EXCLUSIVE MINIMUM MINIMUM_EXCLUSIVE MULTIPLE_OF ARRAY_LENGTH_LONG ARRAY_LENGTH_SHORT ARRAY_ADDITIONAL_ITEMS ARRAY_UNIQUE MAX_LENGTH MIN_LENGTH MAX_PROPERTIES MIN_PROPERTIES OBJECT_MISSING_REQUIRED_PROPERTY OBJECT_PROPERTIES_MAXIMUM OBJECT_PROPERTIES_MINIMUM OBJECT_ADDITIONAL_PROPERTIES OBJECT_DEPENDENCY_KEY ONE_OF_MISSING ONE_OF_MULTIPLE NOT_PASSED INVALID_FORMAT UNKNOWN_FORMAT PATTERN

message

required

Human readable error code

string

Example

{
  "errors": [
    {
      "code": "ENUM_MISMATCH"
    }
  ]
}

404

Merchant not found

Media typeapplication/json

default

Unexpected error

Media typeapplication/json

object

code

Machine readable error code

string

message

required

Human readable error code

string

Example^generated

{
  "code": "example",
  "message": "example"
}