Importing Customers

Create and update Customers in your Project.

The Customer data to import is represented by CustomerImport and included in a CustomerImportRequest, which is imported using Import Customers.

Representations

CustomerImportRequest

The request body to import Customers. Contains data for Customers to be created or updated in a Project.

type
String
"customer"

The Customer import resource type.

resources
Array of CustomerImport

The customer import resources of this request.

MaxItems: 20
Example: json
{
"type": "customer",
"resources": [
{
"customerNumber": "12345",
"email": "alice@example.com",
"password": "secret",
"firstName": "Alice",
"lastName": "Doe",
"middleName": "Ruth",
"title": "Ms.",
"dateOfBirth": "1980-01-01",
"companyName": "commercetools GmbH",
"vatId": "123456789",
"addresses": [
{
"key": "wCVKP6iU",
"firstName": "Alice",
"country": "DE"
},
{
"key": "en-wcvK6",
"firstName": "Alice",
"country": "US"
}
],
"defaultShippingAddress": 0,
"shippingAddresses": [0, 1],
"defaultBillingAddress": 0,
"billingAddresses": [0, 1],
"isEmailVerified": false,
"externalId": "external-id-123",
"customerGroup": {
"typeId": "customer-group",
"key": "customer-group-key"
},
"custom": {
"type": {
"key": "custom-type",
"typeId": "type"
},
"fields": {
"boolean-field": {
"type": "Boolean",
"value": true
}
}
},
"locale": "DE",
"salutation": "Dr.",
"key": "customer-import-resource-key",
"stores": [
{
"typeId": "store",
"key": "store-key"
}
],
"authenticationMode": "Password"
}
]
}

CustomerImport

The data representation for a Customer to be imported that is persisted as a Customer in the Project.

key
String

User-defined unique identifier. If a Customer with this key exists, it will be updated with the imported data.

customerNumber
String

Maps to Customer.customerNumber.

email
String

Maps to Customer.email.

password
String

Required when authenticationMode is set to Password. Maps to Customer.password.

stores
Array of StoreKeyReference

The References to the Stores with which the Customer is associated. If referenced Stores do not exist, the state of the ImportOperation will be set to unresolved until the necessary Stores are created.

firstName
String

Maps to Customer.firstName.

lastName
String

Maps to Customer.lastName.

middleName
String

Maps to Customer.middleName.

title
String

Maps to Customer.title.

salutation
String

Maps to Customer.salutation.

externalId
String

Maps to Customer.externalId.

dateOfBirth
Date

Maps to Customer.dateOfBirth.

companyName
String

Maps to Customer.companyName.

vatId
String

Maps to Customer.vatId.

isEmailVerified
Boolean

Maps to Customer.isEmailVerified.

customerGroup

The Reference to the CustomerGroup with which the Customer is associated. If referenced CustomerGroup does not exist, the state of the ImportOperation will be set to unresolved until the necessary CustomerGroup is created.

addresses
Array of CustomerAddress

Maps to Customer.addresses.

defaultBillingAddress
Int

The index of the address in the addresses array. The defaultBillingAddressId of the customer will be set to the ID of that address.

billingAddresses
Array of Integer

The indices of the billing addresses in the addresses array. The billingAddressIds of the customer will be set to the IDs of that addresses.

defaultShippingAddress
Int

The index of the address in the addresses array. The defaultShippingAddressId of the customer will be set to the ID of that address.

shippingAddresses
Array of Integer

The indices of the shipping addresses in the addresses array. The shippingAddressIds of the customer will be set to the IDs of that addresses.

locale
String

Maps to Customer.locale.

authenticationMode
  • Set to Password to make the password field required for the Customer.
  • Set to ExternalAuth when the password is not required for the Customer.
Default: Password
custom

The Custom Fields for this Customer.

CustomerAddress

Different from Address in that key is required and id is not supported.

key
String

User-defined identifier for the address. Must follow the pattern [a-zA-Z0-9_-]{2,256} and must be unique per customer.

title
String
salutation
String
firstName
String
lastName
String
streetName
String
streetNumber
String
additionalStreetInfo
String
postalCode
String
city
String
region
String
state
String
country
CountryCode

A two-digit country code as per ISO 3166-1 alpha-2.

company
String
department
String
building
String
apartment
String
pOBox
String
phone
String
mobile
String
email
String
fax
String
additionalAddressInfo
String
externalId
String
custom

Custom Fields for the address.

AuthenticationMode

Password

If set, the password field is required for the Customer.

ExternalAuth

If set, the password field is optional for the Customer.

Import Customers

POST
https://import.{region}.commercetools.com/{projectKey}/customers/import-containers/{importContainerKey}

Creates a request for creating new Customers or updating existing ones.

OAuth 2.0 Scopes:
manage_customers:{projectKey}
Path parameters:
region
String

The Region in which the Project is hosted.

projectKey
String

The Project key.

importContainerKey
String

The ImportContainer used to create the new resource

Request Body:CustomerImportRequestasapplication/json
Response:
201ImportResponseasapplication/json
Request Example:cURL
curl https://import.{region}.commercetools.com/{projectKey}/customers/import-containers/{importContainerKey} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"type" : "customer",
"resources" : [ {
"customerNumber" : "12345",
"email" : "alice@example.com",
"password" : "secret",
"firstName" : "Alice",
"lastName" : "Doe",
"middleName" : "Ruth",
"title" : "Ms.",
"dateOfBirth" : "1980-01-01",
"companyName" : "commercetools GmbH",
"vatId" : "123456789",
"addresses" : [ {
"key" : "wCVKP6iU",
"firstName" : "Alice",
"country" : "DE"
}, {
"key" : "en-wcvK6",
"firstName" : "Alice",
"country" : "US"
} ],
"defaultShippingAddress" : 0,
"shippingAddresses" : [ 0, 1 ],
"defaultBillingAddress" : 0,
"billingAddresses" : [ 0, 1 ],
"isEmailVerified" : false,
"externalId" : "external-id-123",
"customerGroup" : {
"typeId" : "customer-group",
"key" : "customer-group-key"
},
"custom" : {
"type" : {
"key" : "custom-type",
"typeId" : "type"
},
"fields" : {
"boolean-field" : {
"type" : "Boolean",
"value" : true
}
}
},
"locale" : "DE",
"salutation" : "Dr.",
"key" : "customer-import-resource-key",
"stores" : [ {
"typeId" : "store",
"key" : "store-key"
} ],
"authenticationMode" : "Password"
} ]
}
DATA
201 Response Example: ImportResponsejson
{
"operationStatus": [
{
"state": "processing",
"operationId": "252c6ed3-c668-4610-afe9-87b9255e62e0"
}
]
}