Menu

Customers API Routes

Customers can either be created when they register through the Store APIs, or created by the admin using the Admin APIs.

These API routes allow admin users to manage customers in their store.

GET /admin/customers#

List Customers

Retrieve a list of customers. The customers can be filtered by fields such as id. The customers can also be sorted or paginated.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
groupsstring | object | string[]Optional
Filter by a customer group's ID to retrieve customers that belong to it.
qstringOptional
Search term to filter the customer's searchable properties by.
idstring | string[] | objectOptional
Filter by a customer's ID. Accepts the filter operators.
emailstring | string[] | objectOptional
Filter by a customer email. Accepts the filter operators.
company_namestring | string[] | objectOptional
Filter by a customer's company name. Accepts the filter operators.
first_namestring | string[] | objectOptional
Filter by a customer's first name. Accepts the filter operators.
last_namestring | string[] | objectOptional
Filter by a customer's last name. Accepts the filter operators.
created_bystring | string[] | objectOptional
Filter by a user ID to retrieve the customers they created. Accepts the filter operators.
created_atobjectOptional
Filter by the customer's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a customer's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter a customer by their deletion date. Accepts the filter operators.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
has_accountbooleanOptional
Filter by whether the customer is registered.
with_deletedbooleanOptional
Whether to include deleted records in the result.

Request examples

Responses

200 OK

limitnumber
The maximum number of items returned in the list.
offsetnumber
The number of items skipped before retrieving the returned items.
countnumber
The total number of items.
customersobject[]
The list of customers.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/customers#

Create Customer

Create a customer.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.

Request body (application/json)

emailstring
The customer's email.
company_namestring
The customer's company name.
first_namestring
The customer's first name.
last_namestring
The customer's last name.
phonestring
The customer's phone.
metadataobject
The customer's metadata.
additional_dataobjectOptional
Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Request examples

Responses

200 OK

customerobject
The customer's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • customer.created: Emitted when a customer is created.

POST /admin/customers/export#

Export Customers

Start a customer export process to retrieve a file of exported customers. Use the query parameters to filter the exported customers and select the fields to include.

You'll receive in the response the transaction ID of the workflow generating the file. To check the status of the execution, send a GET request to /admin/workflows-executions/export-customers/:transaction-id.

Once the execution finishes successfully, a notification is created for the export. You can retrieve the notifications using the /admin/notification API route to retrieve the file's download URL.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

groupsstring | object | string[]Optional
Filter by a customer group's ID to retrieve customers that belong to it.
has_accountbooleanOptional
Filter by whether the customer is registered.
qstringOptional
Search term to filter the customer's searchable properties by.
idstring | string[] | objectOptional
Filter by a customer's ID. Accepts the filter operators.
emailstring | string[] | objectOptional
Filter by a customer email. Accepts the filter operators.
company_namestring | string[] | objectOptional
Filter by a customer's company name. Accepts the filter operators.
first_namestring | string[] | objectOptional
Filter by a customer's first name. Accepts the filter operators.
last_namestring | string[] | objectOptional
Filter by a customer's last name. Accepts the filter operators.
created_bystring | string[] | objectOptional
Filter by a user ID to retrieve the customers they created. Accepts the filter operators.
created_atobjectOptional
Filter by the customer's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by the customer's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by the customer's deletion date. Accepts the filter operators.
limitnumberOptional
Limit the number of items returned in the list.
offsetnumberOptional
The number of items to skip when retrieving a list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
with_deletedbooleanOptional
Whether to include deleted records in the result.
fieldsstringOptional
Comma-separated fields that should be included in the returned data. If a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. Without prefix it will replace the entire default fields.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.

Request body (application/json)

format"csv" | "json"Optional
The format of the exported file. Defaults to json.
batch_sizestring | numberOptional
The number of customers to retrieve in each batch while generating the export.

Request examples

Responses

202 OK

transaction_idstring
The ID of the export customer workflow's transaction.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/customers/{id}#

Get a Customer

Retrieve a customer by its ID. You can expand the customer's relations or select the fields that should be returned.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The customer's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.

Request examples

Responses

200 OK

customerobject
The customer's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/customers/{id}#

Update a Customer

Update a customer's details.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The customer's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.

Request body (application/json)

emailstring
The customer's email.
company_namestring
The customer's company name.
first_namestring
The customer's first name.
last_namestring
The customer's last name.
phonestring
The customer's phone.
metadataobject
The customer's metadata.
additional_dataobjectOptional
Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Request examples

Responses

200 OK

customerobject
The customer's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • customer.updated: Emitted when a customer is updated.

DELETE /admin/customers/{id}#

Delete a Customer

Delete a customer.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The customer's ID.

Request examples

Responses

200 OK

idstring
The customer's ID.
objectstring
The customer's object.
deletedboolean
The customer's deleted.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • customer.deleted: Emitted when a customer is deleted.

GET /admin/customers/{id}/addresses#

List Addresses

Retrieve a list of addresses in a customer. The addresses can be filtered by fields like query. The addresses can also be paginated.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The customer's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
qstringOptional
Search term to apply on the address's searchable properties.
companystring | string[]Optional
Filter by a company.
citystring | string[]Optional
Filter by a city.
country_codestring | string[]Optional
Filter by a currency code.
provincestring | string[]Optional
Filter by an ISO 3166-2 province code. Must be lower-case.
postal_codestring | string[]Optional
Filter by a postal code.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
with_deletedbooleanOptional
Whether to include deleted records in the result.

Request examples

Responses

200 OK

limitnumber
The maximum number of items returned.
offsetnumber
The number of items skipped before retrieving the returned items.
countnumber
The total number of items.
addressesobject[]
The customer addresses.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/customers/{id}/addresses#

Add a Customer Address

Add an address to a customer.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The customer's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.

Request body (application/json)

address_namestring
The name of the address.
is_default_shippingbooleanOptional
Whether this address is used by default for shipping when placing an order.
is_default_billingbooleanOptional
Whether this address is used by default for billing when placing an order.
companystring
The address's company.
first_namestring
The address's first name.
last_namestring
The address's last name.
address_1string
The address's first line.
address_2string
The address's second line.
citystring
The address's city.
country_codestring
The address's country code.
provincestring
The address's ISO 3166-2 province code. Must be lower-case.
Example: us-ca
postal_codestring
The address's postal code.
phonestring
The address's phone.
metadataobject
The address's metadata.
additional_dataobjectOptional
Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Request examples

Responses

200 OK

customerobject
The customer's details.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/customers/{id}/addresses/{address_id}#

List Addresses

Retrieve a list of a customer's addresses. The addresses can be filtered by fields like company. The addresses can also be paginated.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The customer's ID.
address_idstring
The customer's address id.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.

Request examples

Responses

200 OK

addressobject
The customer's address.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/customers/{id}/addresses/{address_id}#

Update a Customer's Address

Update a customer address's details.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The customer's ID.
address_idstring
The customer's address id.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.

Request body (application/json)

address_namestring
The name of the address.
is_default_shippingbooleanOptional
Whether this address is used by default for shipping when placing an order.
is_default_billingbooleanOptional
Whether this address is used by default for billing when placing an order.
companystring
The address's company.
first_namestring
The address's first name.
last_namestring
The address's last name.
address_1string
The address's first line
address_2string
The address's second line
citystring
The address's city.
country_codestring
The address's country code.
provincestring
The address's ISO 3166-2 province code. Must be lower-case.
Example: us-ca
postal_codestring
The address's postal code.
phonestring
The address's phone.
metadataobject
The address's metadata.
additional_dataobjectOptional
Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Request examples

Responses

200 OK

customerobject
The customer's details.

400, 401, 404, 409, 422, 500: an error response is returned.

DELETE /admin/customers/{id}/addresses/{address_id}#

Remove an Address from Customer

Remove a customer's address.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The customer's ID.
address_idstring
The customer address's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.

Request examples

Responses

200 OK

idstring
The customer's ID.
objectstring
The name of the deleted object.
deletedboolean
Whether the Customer was deleted.
parentobjectOptional
The customer's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/customers/{id}/customer-groups#

Manage Customer Groups of Customer

Manage the customer groups of a customer, adding or removing the customer from those groups.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The customer's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.

Request body (application/json)

addstring[]Optional
The IDs of an entity to add to the other.
removestring[]Optional
The IDs of an entity to remove from the other.

Request examples

Responses

200 OK

customerobject
The customer's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page