The /customers folder allows you to create or update customers in bulk via SFTP. This is useful for migrating existing customer data or onboarding large customer bases.

Upsert changes to Customer. For more details on how to use batch operations see the Jobs documentation for more details on how to use bulk/batch processing.

Folder

/customers

Required Scopes

jobs:create customers:create

File Format

Upload CSV files to the /customers folder. The CSV should use dot notation to match the Customer Creation API structure.

Required Fields

Field	Description	Required	Example
`ref`	Customer reference ID	Yes	`CUST001`

Optional Fields

The order of the columns only matters when it comes to address definitions.

ref is required. See Customer docs on ref for details.
address optional, defines an address to be defined on the Customer record. You can name multiple columns address and each will be added, in the order they are defined as columns. This makes the first address column your default address.
metadata.[some-name] optional, creates a metadata attribute on the Customer for using the [some-name] defined after metadata.. For example metadata.name will define a metadata attribute called name.
appdata.[some-name] optional, and behaves the same as metadata. See Customer for more details on how to use appdata.

Field	Description	Example
`firstName`	Customer first name	`John`
`lastName`	Customer last name	`Doe`
`email`	Customer email address	`john.doe@example.com`
`phone`	Customer phone number	`+1234567890`
`address.street`	Street address	`123 Main St`
`address.city`	City	`Springfield`
`address.state`	State/province	`IL`
`address.zip`	ZIP/postal code	`62701`
`address.country`	Country code	`US`
`metadata.key`	Custom metadata	`value`

Example CSV

ref,address,address,metadata.name
cus-1,+12223334444,test@test.com,Joe
cus-2,+22233334445,test1@test.com,Jane

Processing

For each valid record:

Data validation: Validate required fields and data formats
Customer creation: Create customer via API
Address creation: Create customer address if provided
Metadata assignment: Assign custom metadata if provided
Status update: Mark record as processed

Error Codes

Code	Description	Resolution
`MISSING_REQUIRED_FIELD`	Required field is missing	Add missing field
`INVALID_EMAIL`	Invalid email format	Check email format
`INVALID_PHONE`	Invalid phone format	Check phone format
`DUPLICATE_CUSTOMER`	Customer already exists	Check for duplicates
`INVALID_ADDRESS`	Invalid address format	Check address fields