--- schema_version: "1" id: f63516b64a518c6c3c63339415b87a7eb99374004bd8ba1f0ed41ff1923114c4 title: Customers collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/customers.md canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/customers source_site: developer.salesforce.com content_type: documentation content_hash: cae70d9764e17128e6ccebe0823a5e17ad73d0a25ce8f726315a6cb552c0f597 products: - B2C Commerce API - Salesforce APIs --- Customers # Customers [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/customers/customers-oas-v1-public.yaml) ## API Overview Use the Customers API to search for and manage customer information within a customer list. It also enables you to search for customer groups. Once you find information for a customer, you can also use the API to manage customer addresses. The `customerNo` is created when you create a shopper record. You can create a shopper record using the Customers API or Business Manager. For details, see [registerCustomer](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=registerCustomer) and [Create and Manage Customer Records](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-customer-records.html?q=create%20customer). ![b2c-commerce-customers-screenshot-1.png](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/b2c-commerce-customers-screenshot-1.png) ### Authentication & Authorization For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request. You must include the relevant scope(s) in the client ID used to generate the token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html) For detailed setup instructions, see the [Authorization for Admin APIs guide.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html) ### Response Details #### Timeouts Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html) #### Error Handling Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html) ### Related APIs * [Shopper Customers](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=Summary) — Shopper-facing registration, login, and profile management. **Version:** 1.1.4 ## Servers * `https://{shortCode}.api.commercecloud.salesforce.com/customer/customers/v1` * `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)` ## Security * `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication. * OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token) * Scope sfcc.customerlists: Customer Lists scope READONLY * Scope sfcc.customerlists.rw: Customer Lists scope * Scope sfcc.customergroups: Customer Groups scope READONLY * Scope sfcc.customergroups.rw: Customer Groups scope * OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token) ## Operations ### POST Search for customers in a customer list. `POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search` Operation ID: `searchCustomerInCustomerList`. Security: AmOAuth2 (sfcc.customerlists, sfcc.customerlists.rw). Search for customers in a customer list. The query attribute specifies a complex query that can be used to narrow down the search. The following list provides searchable attributes: | Attribute | Type | | --- | --- | | customerNo | String | | firstName | String | | secondName | String | | lastName | String | | suffix | String | | salutation | String | | title | String | | fax | String | | phoneHome | String | | phoneBusiness | String | | phoneMobile | String | | email | String | | gender | Integer | | companyName | String | | credentials.login | String | | credentials.enabled | Boolean | #### Parameters * `customerListId` (path, string, required) The customer list ID. Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`. * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` #### Request body (required) Media type: `application/json`. Schema: `SearchRequest`. _Example: CustomerSearchBody_ ``` { "limit": 2, "offset": 50, "query": { "textQuery": { "fields": [ "email" ], "searchPhrase": "wleung" } } } ``` #### Responses * **200** Success Media type: `application/json`. Schema: `CustomerSearchResult`. _Example: CustomerSearchResult_ ``` { "hits": [ { "data": { "birthday": "1999-12-31", "companyName": "Salesforce", "creationDate": "2023-07-21T07:29:39.505Z", "credentials": { "enabled": true, "locked": false, "login": "af4ab358-3187-4ec5-82a6-918e0fe8a21f" }, "customerId": "absAzIVSkman3GPpSYluYBbLrB", "customerNo": "00000012", "email": "w.leung@gmail.com", "fax": "123-123-1234", "firstName": "Wei", "gender": 1, "lastModified": "2023-07-21T07:29:39.506Z", "lastName": "Leung", "phoneBusiness": "123-123-1234", "phoneHome": "123-123-1234", "phoneMobile": "123-123-1234", "preferredLocale": "en-US", "salutation": "Dr.", "secondName": "J", "suffix": "Jr.", "title": "Mr." }, "relevance": 4.258296012878418 } ], "limit": 1, "offset": 0, "query": { "textQuery": { "fields": [ "email" ], "searchPhrase": "w.leung@gmail.com" } }, "total": 1 } ``` * **400** Bad Request. Returned when a specified parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: searchCustomerInCustomerList400_ ``` { "title": "Bad Request", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-query-parameter", "detail": "offset-BAD-REQUEST parameters are not defined in RAML." } ``` * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: searchCustomerInCustomerList401_ ``` { "title": "Invalid Access Token", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-access-token", "detail": "The request is unauthorized, the access token is invalid.", "accessToken": "hbGciOiJIUzI1NiIsInR5cCI6Ikp" } ``` * **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: searchCustomerInCustomerList404_ ``` { "title": "Customer List Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/customer-list-not-found", "detail": "No customer list with ID 'SiteGenesis-NOT-FOUND' could be found.", "listId": "SiteGenesis-NOT-FOUND" } ``` ### POST Create a new customer in a customer list. `POST /organizations/{organizationId}/customer-lists/{customerListId}/customers` Operation ID: `createCustomerList`. Security: AmOAuth2 (sfcc.customerlists.rw). Create a new customer. The customer is created using the specified credentials and customer information. This action verifies: * Login acceptance criteria and uniqueness. * Mandatory customer properties. If the action fails to create the customer, it returns a 400 fault with an appropriate message. #### Parameters * `customerListId` (path, string, required) The customer list ID. Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`. * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` #### Request body (required) Media type: `application/json`. Schema: `Customer`. _Example: PostCustomerBody_ ``` { "credentials": { "enabled": true, "locked": false, "login": "wleung", "passwordQuestion": "" }, "lastName": "Leung", "customerNo": "00005002" } ``` #### Responses * **200** Success Media type: `application/json`. Schema: `Customer`. _Example: postCustomers_ ``` { "creationDate": "2019-09-23T19:46:07.412Z", "credentials": { "enabled": true, "locked": false, "login": "wleung" }, "customerId": "adg2p1zObo8JDt3iXZCNIZBcai", "customerNo": "00005001", "lastModified": "2019-09-23T19:46:07.417Z", "lastName": "Leung" } ``` * **400** Bad Request. Returned when a specified parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._ * **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._ ### GET Get customer information. `GET /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}` Operation ID: `getCustomerFromCustomerList`. Security: AmOAuth2 (sfcc.customerlists, sfcc.customerlists.rw). Action to get customer information. #### Parameters * `customerNo` (path, string, required) The customer number. Minimum length: 1. Maximum length: 100. Example: `1`. * `customerListId` (path, string, required) The customer list ID. Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`. * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` #### Responses * **200** Success Media type: `application/json`. Schema: `Customer`. _Example postCustomers: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customers 200 response._ * **400** Bad Request. Returned when a specified parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._ * **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._ ### PUT Create a new customer in a customer list. `PUT /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}` Operation ID: `createCustomerInCustomerList`. Security: AmOAuth2 (sfcc.customerlists.rw). Create a new customer. The customer is created using the specified customer number, credentials, and customer information. This action verifies: * Login acceptance criteria and uniqueness. * Mandatory customer properties. If the action fails to create the customer, it returns a 400 fault with an appropriate message. #### Parameters * `customerNo` (path, string, required) The customer number. Minimum length: 1. Maximum length: 100. Example: `1`. * `customerListId` (path, string, required) The customer list ID. Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`. * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` #### Request body (required) Media type: `application/json`. Schema: `Customer`. _Example: PostCustomerBody_ ``` { "credentials": { "enabled": true, "locked": false, "login": "wleung", "passwordQuestion": "" }, "lastName": "Leung", "customerNo": "00005002" } ``` #### Responses * **200** Success Media type: `application/json`. Schema: `Customer`. _Example postCustomers: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customers 200 response._ * **201** Created Media type: `application/json`. Schema: `Customer`. _Example postCustomers: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customers 200 response._ * **400** Bad Request. Returned when a specified parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._ * **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._ ### DELETE Delete a customer from a customer list. `DELETE /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}` Operation ID: `deleteCustomerFromCustomerList`. Security: AmOAuth2 (sfcc.customerlists.rw). Deletes the customer, including all related information like the customer addresses. #### Parameters * `customerNo` (path, string, required) The customer number. Minimum length: 1. Maximum length: 100. Example: `1`. * `customerListId` (path, string, required) The customer list ID. Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`. * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` #### Responses * **204** No Content * **400** Bad Request. Returned when a specified parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._ * **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._ ### PATCH Update a customer in a customer list. `PATCH /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}` Operation ID: `updateCustomerInCustomerList`. Security: AmOAuth2 (sfcc.customerlists.rw). Updates the customer with the specified information. The customer number can be updated, but results in a CustomerNumberAlreadyInUseException if there is another customer with the same customer number. #### Parameters * `customerNo` (path, string, required) The customer number. Minimum length: 1. Maximum length: 100. Example: `1`. * `customerListId` (path, string, required) The customer list ID. Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`. * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` #### Request body (required) Media type: `application/json`. Schema: `Customer`. _Example: PostCustomerBody_ ``` { "credentials": { "enabled": true, "locked": false, "login": "wleung", "passwordQuestion": "" }, "lastName": "Leung", "customerNo": "00005002" } ``` #### Responses * **200** Success Media type: `application/json`. Schema: `Customer`. _Example postCustomers: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customers 200 response._ * **400** Bad Request. Returned when a specified parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._ * **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._ ### GET Get a list of customer addresses. `GET /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}/addresses` Operation ID: `getAddressesForCustomerFromCustomerList`. Security: AmOAuth2 (sfcc.customerlists, sfcc.customerlists.rw). Returns a list of all customer addresses in pages. The default page size is 10 customer addresses. #### Parameters * `customerNo` (path, string, required) The customer number. Minimum length: 1. Maximum length: 100. Example: `1`. * `customerListId` (path, string, required) The customer list ID. Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`. * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25. Default: `25`. Minimum: 1. Maximum: 50. * `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset. Default: `0`. Minimum: 0. #### Responses * **200** Success Media type: `application/json`. Schema: `CustomerAddressResult`. _Example: addressesGet_ ``` { "data": [ { "addressId": "1", "city": "San Francisco", "companyName": "Ursa Major Solar", "countryCode": "US", "creationDate": "2019-09-23T16:14:07.000Z", "etag": "d288bfd83f75b23640b4bbab2b0d3f65a5c5e934dab818f2246b7c1aed5672f8", "firstName": "Wei", "fullName": "Leung", "jobTitle": "", "lastModified": "2019-09-23T16:23:19.000Z", "lastName": "Leung", "phone": "415-555-1212", "postalCode": "94105", "salutation": "Ms", "secondName": "", "stateCode": "CA" } ], "limit": 1, "offset": 0, "total": 1 } ``` * **400** Bad Request. Returned when a specified parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._ * **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._ ### POST Add a new customer address. `POST /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}/addresses` Operation ID: `createAddressForCustomerInCustomerList`. Security: AmOAuth2 (sfcc.customerlists.rw). Creates a new customer address with the given address information. #### Parameters * `customerNo` (path, string, required) The customer number. Minimum length: 1. Maximum length: 100. Example: `1`. * `customerListId` (path, string, required) The customer list ID. Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`. * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` #### Request body (required) Media type: `application/json`. Schema: `CustomerAddress`. _Example: AddressesBody_ ``` { "addressId": "2", "address1": "123 Trailblazer Ave.", "postalCode": "94105", "lastName": "Leung", "title": "", "salutation": "Ms", "companyName": "Ursa Major Solar", "secondName": "", "phone": "415-555-1212", "countryCode": "US", "city": "San Francisco", "address2": "", "firstName": "Wei", "jobTitle": "", "stateCode": "CA" } ``` #### Responses * **200** Success Media type: `application/json`. Schema: `CustomerAddress`. _Example: addressesPost_ ``` { "addressId": "3", "city": "San Francisco", "companyName": "Ursa Major Solar", "countryCode": "US", "creationDate": "2019-09-23T20:49:38.370Z", "etag": "8772fd1c59fed8313a6c1ad260544c116dc0af4bc13941957173244edba47d31", "firstName": "Wei", "fullName": "Wei Leung", "jobTitle": "", "lastModified": "2019-09-23T20:49:38.372Z", "lastName": "Leung", "phone": "415-555-1212", "postalCode": "94105", "salutation": "Ms", "secondName": "", "stateCode": "CA" } ``` * **400** Bad Request. Returned when a specified parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._ * **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._ ### GET Get a customer address. `GET /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}/addresses/{addressId}` Operation ID: `getAddressForCustomerFromCustomerList`. Security: AmOAuth2 (sfcc.customerlists, sfcc.customerlists.rw). Action that returns a single customer address from a customer list. #### Parameters * `addressId` (path, string, required) The address ID. Minimum length: 1. Maximum length: 256. Example: `Home`. * `customerNo` (path, string, required) The customer number. Minimum length: 1. Maximum length: 100. Example: `1`. * `customerListId` (path, string, required) The customer list ID. Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`. * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` #### Responses * **200** Success Media type: `application/json`. Schema: `CustomerAddress`. _Example: AddressGet_ ``` { "address1": "123 Trailblazer Ave.", "address2": "", "addressId": "HomeAddress", "city": "San Francisco", "companyName": "", "countryCode": "US", "firstName": "Wei", "fullName": "Wei Leung", "jobTitle": "", "lastName": "Leung", "phone": "", "postalCode": "", "postBox": "", "salutation": "Ms.", "secondName": "", "stateCode": "CA", "suffix": "", "suite": "", "title": "" } ``` * **400** Bad Request. Returned when a specified parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._ * **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._ ### DELETE Delete a customer address. `DELETE /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}/addresses/{addressId}` Operation ID: `removeAddressForCustomerInCustomerList`. Security: AmOAuth2 (sfcc.customerlists.rw). Deletes a customer address. #### Parameters * `addressId` (path, string, required) The address ID. Minimum length: 1. Maximum length: 256. Example: `Home`. * `customerNo` (path, string, required) The customer number. Minimum length: 1. Maximum length: 100. Example: `1`. * `customerListId` (path, string, required) The customer list ID. Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`. * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` #### Responses * **204** No Content * **400** Bad Request. Returned when a specified parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._ * **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._ ### PATCH Update a customer address. `PATCH /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}/addresses/{addressId}` Operation ID: `updateAddressForCustomerInCustomerList`. Security: AmOAuth2 (sfcc.customerlists.rw). Updates an address of a customer with the given address information. #### Parameters * `addressId` (path, string, required) The address ID. Minimum length: 1. Maximum length: 256. Example: `Home`. * `customerNo` (path, string, required) The customer number. Minimum length: 1. Maximum length: 100. Example: `1`. * `customerListId` (path, string, required) The customer list ID. Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`. * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` #### Request body (required) Media type: `application/json`. Schema: `CustomerAddress`. _Example AddressesBody: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}/addresses request._ #### Responses * **200** Success Media type: `application/json`. Schema: `CustomerAddress`. _Example addressesPost: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}/addresses 200 response._ * **400** Bad Request. Returned when a specified parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._ * **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._ ### POST Search for customer groups. `POST /organizations/{organizationId}/customer-group-search` Operation ID: `searchCustomerGroup`. Security: AmOAuth2 (sfcc.customergroups, sfcc.customergroups.rw). Search for customer groups in a given site ID. The query attribute specifies a complex query that can be used to narrow down the search. The following list provides searchable attributes: | Attribute | Type | | --- | --- | | id | String | | description | String | | type | String | Note: This endpoint is available with B2C Commerce version 24.2. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites. _Example: SiteId_ ``` RefArch ``` #### Request body (required) Media type: `application/json`. Schema: `SearchRequest`. _Example: CustomerSearchBody_ ``` { "limit": 2, "offset": 50, "query": { "textQuery": { "fields": [ "email" ], "searchPhrase": "wleung" } } } ``` #### Responses * **200** Success Media type: `application/json`. Schema: `CustomerGroupSearchResult`. _Example: CustomerGroupSearchResult_ ``` { "limit": 1, "hits": [ { "creationDate": "2020-01-09T16:50:32.000Z", "description": "Big Spenders", "id": "Big Spenders", "inDeletion": false, "lastModified": "2020-01-09T16:50:32.000Z", "memberCount": 109, "rule": { "description": "Customers who spend more than $1000 in the last month" }, "type": "dynamic" } ], "query": { "textQuery": { "fields": [ "id" ], "searchPhrase": "Big" } }, "offset": 0, "total": 1 } ``` * **400** Bad Request. Returned if the search term in term query does not match any of the customer group or if the query is ill-formed. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: searchCustomerGroup400_ ``` { "title": "Customer Group Type Invalid", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-query-parameter", "detail": "The customer group type 'stat' is invalid." } ``` * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._ ### GET Get a list of customer groups. `GET /organizations/{organizationId}/customer-groups` Operation ID: `getCustomerGroups`. Security: AmOAuth2 (sfcc.customergroups, sfcc.customergroups.rw). Returns a list of all customer groups for a given site in pages. The default page size is 25 customer groups. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites. _Example: SiteId_ ``` RefArch ``` * `select` (query, Select) _Example: select_ ``` (**) ``` * `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25. Default: `25`. Minimum: 1. Maximum: 50. * `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset. Default: `0`. Minimum: 0. #### Responses * **200** Success Media type: `application/json`. Schema: `CustomerGroupResult`. _Example: CustomerGroupResult_ ``` { "limit": 3, "offset": 0, "total": 50, "data": [ { "creationDate": "2020-01-09T16:50:32.000Z", "description": "Big Spenders", "id": "Big Spenders", "lastModified": "2020-01-09T16:50:32.000Z", "rule": { "description": "Customers who spent more than $1000 in the last month" }, "type": "dynamic" }, { "creationDate": "2019-05-15T10:30:00.000Z", "description": "VIP Customers", "id": "VIP", "lastModified": "2020-03-20T14:15:30.000Z", "type": "static" }, { "creationDate": "2018-01-01T00:00:00.000Z", "description": "Everyone", "id": "Everyone", "lastModified": "2018-01-01T00:00:00.000Z", "type": "system" } ] } ``` * **400** Bad Request. Returned when a specified parameter value is invalid. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: malformedSelector400_ ``` { "title": "Malformed Selector", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-selector", "detail": "The property selector '(invalid' is malformed.", "selector": "(invalid" } ``` ### PUT Assign multiple customers to a customer group. `PUT /organizations/{organizationId}/customer-groups/{customerGroupId}/members` Operation ID: `assignCustomerGroupMembers`. Security: AmOAuth2 (sfcc.customergroups, sfcc.customergroups.rw). Add multiple customers to a (static) customer group. This endpoint assigns the specified customers to the customer group identified by the given ID. Only static customer groups support this operation. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites. _Example: SiteId_ ``` RefArch ``` * `customerGroupId` (path, CustomerGroupId, required) The customer group identifier. * `customerNos` (query, array of CustomerNo, required, style: form, explode: false) List of customer numbers to assign or unassign from the customer group. Minimum items: 1. Maximum items: 50. _Example_ ``` [ "00001234", "00005678", "00009012" ] ``` #### Responses * **200** Successfully returned the assigned customer group members. Media type: `application/json`. Schema: `CustomerGroupMemberResult`. _Example: AssignMembersSuccess_ Successful assignment of customers to a customer group Example response after successfully assigning multiple customers to a customer group ``` { "limit": 3, "total": 5, "data": [ { "customerNo": "00001234", "login": "johndoe", "firstName": "John", "lastName": "Doe", "active": true }, { "customerNo": "00005678", "login": "janesmith", "firstName": "Jane", "lastName": "Smith", "active": true }, { "customerNo": "00009012", "login": "bobjones", "firstName": "Bob", "lastName": "Jones", "active": true } ] } ``` * **403** Forbidden. The customer group is not a static group. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: customerGroupUnsupportedAssignment403_ ``` { "title": "Customer Group Unsupported Assignment", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/customer-group-unsupported-assignment", "detail": "No customer can be assigned to the non-static group 'Unregistered' for site 'RefArch'." } ``` * **404** Not Found. The customer group does not exist or one or more customers were not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: customerGroupNotFound404_ ``` { "title": "Customer Group Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/customer-group-not-found", "detail": "No customer group with ID 'invalidId' for site 'RefArch' could be found." } ``` _Example: customerNotFound404_ ``` { "title": "Customer Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/customer-not-found", "detail": "No customer with number '[\"invalidCustomerNo\"]' for site 'RefArch' could be found." } ``` * **409** Conflict. The customer group is already in deletion state. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: objectInDeletionConflict409_ ``` { "title": "Object In Deletion Conflict", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/object-in-deletion-conflict", "detail": "The request on object '{1}' can't be executed since it's already in the process of being deleted.", "objectId": "CustomerGroupInDeletion" } ``` ### DELETE Unassign multiple customers from a customer group. `DELETE /organizations/{organizationId}/customer-groups/{customerGroupId}/members` Operation ID: `unassignCustomerGroupMembers`. Security: AmOAuth2 (sfcc.customergroups, sfcc.customergroups.rw). Remove multiple customers from a (static) customer group. This endpoint unassigns the specified customers from the customer group identified by the given ID. Only static customer groups support this operation. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites. _Example: SiteId_ ``` RefArch ``` * `customerGroupId` (path, CustomerGroupId, required) The customer group identifier. * `customerNos` (query, array of CustomerNo, required, style: form, explode: false) List of customer numbers to assign or unassign from the customer group. Minimum items: 1. Maximum items: 50. _Example_ ``` [ "00001234", "00005678", "00009012" ] ``` #### Responses * **204** The customers were successfully unassigned from the customer group. * **404** Not Found. The customer group does not exist. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example customerGroupNotFound404: same as PUT /organizations/{organizationId}/customer-groups/{customerGroupId}/members 404 response._ _Example customerNotFound404: same as PUT /organizations/{organizationId}/customer-groups/{customerGroupId}/members 404 response._ * **409** Conflict. The customer group is already in deletion state. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example objectInDeletionConflict409: same as PUT /organizations/{organizationId}/customer-groups/{customerGroupId}/members 409 response._ ## Schemas ### OrganizationId An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). Type: `string`. Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`. ### SearchRequest Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource. * `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200. Minimum: 1. Maximum: 200. Example: `10`. * `query` (_Query_, required) * `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed. * `offset` (_Offset_) ### CustomerSearchResult Document representing a customer search result. Includes all fields of `PaginatedSearchResult`. * `hits` (_array of CustomerSearchHit_, required) The sorted array of search hits. Can be empty. _Example_ ``` [ { "customerNo": "D100201", "lastName": "Leung" } ] ``` _Example_ ``` { "value": { "hits": [ { "data": { "birthday": "1999-12-31", "companyName": "Salesforce", "creationDate": "2023-07-21T07:29:39.505Z", "credentials": { "enabled": true, "locked": false, "login": "af4ab358-3187-4ec5-82a6-918e0fe8a21f" }, "customerId": "absAzIVSkman3GPpSYluYBbLrB", "customerNo": "00000012", "email": "w.leung@gmail.com", "fax": "123-123-1234", "firstName": "Wei", "gender": 1, "lastModified": "2023-07-21T07:29:39.506Z", "lastName": "Leung", "phoneBusiness": "123-123-1234", "phoneHome": "123-123-1234", "phoneMobile": "123-123-1234", "preferredLocale": "en-US", "salutation": "Dr.", "secondName": "J", "suffix": "Jr.", "title": "Mr." }, "relevance": 4.258296012878418 } ], "limit": 1, "offset": 0, "query": { "textQuery": { "fields": [ "email" ], "searchPhrase": "w.leung@gmail.com" } }, "total": 1 } } ``` ### ErrorResponse * `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization Maximum length: 256. Example: `You do not have enough credit`. * `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `NotEnoughMoney`. * `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem. Example: `Your current balance is 30, but that costs 50`. * `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `/account/12345/msgs/abc`. ### Customer Person or entity who shops on Commerce Cloud storefronts by creating a shopper account in Commerce Cloud. * `birthday` (_string (date)_) The customer's birthday. Example: `1999-12-31`. * `companyName` (_string_) The customer's company name. Maximum length: 256. Example: `Ursa Major Solar`. * `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'. Example: `9999-12-31T00:00:00.0Z`. * `credentials` (_Credentials_) * `customerId` (_string_) The customer's ID. Both registered and guest customers have a customer ID. Maximum length: 28. Example: `wleung`. * `customerNo` (_string_, required) The customer's number. Maximum length: 100. Example: `D100201`. * `email` (_string_) The customer's email address. Maximum length: 256. Example: `wleung@example.com`. * `fax` (_string_) The customer's fax number. The length is restricted to 32 characters. Maximum length: 32. Example: `415-555-1213`. * `firstName` (_string_) The customer's first name. Maximum length: 256. Example: `Wei`. * `gender` (_integer (int32)_) The customer's gender. Example: `2`. * `jobTitle` (_string_) The customer's job title. Maximum length: 256. * `lastLoginTime` (_string (date-time)_) The last login time of the customer. Example: `9999-12-31T00:00:00.0Z`. * `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'. Example: `9999-12-31T00:00:00.0Z`. * `lastName` (_string_, required) The customer's last name. Maximum length: 256. Example: `Leung`. * `lastVisitTime` (_string (date-time)_) The last visit time of the customer. Example: `9999-12-31T00:00:00.0Z`. * `phoneBusiness` (_string_) The customer's business phone number. Maximum length: 32. Example: `333-333-3333`. * `phoneHome` (_string_) The customer's home phone number. Maximum length: 32. Example: `415-555-1211`. * `phoneMobile` (_string_) The customer's mobile phone number. Maximum length: 32. Example: `415-555-1212`. * `preferredLocale` (_string_) The customer's preferred locale. Maximum length: 5. Example: `en_US`. * `previousLoginTime` (_string (date-time)_) The time when the customer previously logged in. Example: `9999-12-31T00:00:00.0Z`. * `previousVisitTime` (_string (date-time)_) The time when the customer previously visited the store. Example: `9999-12-31T00:00:00.0Z`. * `primaryAddress` (_CustomerAddress_) * `salutation` (_string_) The customer's salutation. Maximum length: 256. Example: `Ms.`. * `secondName` (_string_) The customer's second name. Maximum length: 256. Example: `Leung`. * `suffix` (_string_) The customer's suffix (for example, "Jr." or "Sr."). Maximum length: 256. * `title` (_string_) The customer's title (for example, "Mrs" or "Mr"). Maximum length: 256. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### CustomerAddressResult Result document containing an array of customer addresses. Includes all fields of `PaginatedResultBase`. * `data` (_array of CustomerAddress_) The array of customer address documents. ### CustomerAddress Any address that is associated with a customer (billing, shipping, mailing, and so on). * `address1` (_string_) The customer's first address. Maximum length: 256. Example: `123 Trailblazer Ave.`. * `address2` (_string_) The customer's second address value. Maximum length: 256. * `addressId` (_string_, required) The customer address ID. Maximum length: 256. Example: `Home`. * `city` (_string_) The customer's city. Maximum length: 256. Example: `San Francisco`. * `companyName` (_string_) The customer's company name. Maximum length: 256. Example: `Ursa Major Solar`. * `countryCode` (_string_, required) The customer's two-character country code per ISO 3166-1 alpha-2. Maximum length: 2. Example: `US`. * `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'. Example: `9999-12-31T00:00:00.0Z`. * `etag` (_string_) The generated eTag representing the state of the customer address. Example: `0267dee58b0ddd9a13f27309470b84f5b2b7e00fa53dfcf400c1f7a5661f319d`. * `firstName` (_string_) The customer's first name. Maximum length: 256. Example: `Wei`. * `fullName` (_string_) The concatenation of the customer's first, middle, last names, and suffix. Maximum length: 1027. Example: `Wei Leung`. * `jobTitle` (_string_) The customer's job title. Maximum length: 256. * `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'. Example: `9999-12-31T00:00:00.0Z`. * `lastName` (_string_, required) The customer's last name. Maximum length: 256. Example: `Leung`. * `phone` (_string_) The customer's phone number. Maximum length: 32. Example: `415-555-1212`. * `postBox` (_string_) The customer's post box. Maximum length: 256. * `postalCode` (_string_) The customer's postal code. Maximum length: 256. Example: `94105`. * `salutation` (_string_) The customer's salutation. Maximum length: 256. Example: `Ms.`. * `secondName` (_string_) The customer's second name. Maximum length: 256. Example: `Leung`. * `stateCode` (_string_) The customer's state. Maximum length: 256. Example: `CA`. * `suffix` (_string_) The customer's suffix. Maximum length: 256. * `suite` (_string_) The customer's suite. Maximum length: 32. * `title` (_string_) The customer's title. Maximum length: 256. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### SiteId The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites Type: `string`. Minimum length: 1. Maximum length: 32. Example: `RefArch`. ### CustomerGroupSearchResult Document representing a customer group search result. Includes all fields of `PaginatedSearchResult`. * `hits` (_array of CustomerGroup_, required) The sorted array of search hits. Can be empty. _Example_ ``` { "value": { "limit": 1, "hits": [ { "creationDate": "2020-01-09T16:50:32.000Z", "description": "Big Spenders", "id": "Big Spenders", "inDeletion": false, "lastModified": "2020-01-09T16:50:32.000Z", "memberCount": 109, "rule": { "description": "Customers who spend more than $1000 in the last month" }, "type": "dynamic" } ], "query": { "textQuery": { "fields": [ "id" ], "searchPhrase": "Big" } }, "offset": 0, "total": 1 } } ``` ### Select The property selector declaring which fields are included into the response payload. You can specify a single field name, a comma-separated list of names or work with wildcards. You can also specify array operations and filter expressions. The actual selector value must be enclosed within parentheses. For more information, please read the documentation about property selectors [here](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html). Type: `string`. Minimum length: 1. Pattern: ^\[(\].\*\[)\]$. Example: `(name,id,variationAttributes.(**))`. ### CustomerGroupResult Document representing an unfiltered list of customer groups. Includes all fields of `PaginatedResultBase`. * `data` (_array of CustomerGroup_, required) The list of customer groups. ### CustomerGroupId Type: `string`. Minimum length: 1. Maximum length: 256. Example: `preferred-customers`. ### CustomerNo Type: `string`. Minimum length: 1. Maximum length: 100. Example: `00001234`. ### CustomerGroupMemberResult Results containing a list of customer group members Includes all fields of `ResultBase`. * `data` (_array of CustomerGroupMember_, required) List of customer group members. ### Query A set of objects that define criteria used to select records. A query can contain one of the following: * `MatchAllQuery` * Matches all documents. * `TermQuery` * Matches one or more documents against one or more document fields. * `TextQuery` * Matches text against one or more fields. * `BoolQuery` * Allows construction of a logical expression of multiple queries. * `FilteredQuery` * Allows a filter to be applied to a query. * `NestedQuery` * Allows you to query on nested documents. * _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._ Minimum properties: 1. Maximum properties: 1. * `boolQuery` (_BoolQuery_) * `filteredQuery` (_FilteredQuery_) * `matchAllQuery` (_MatchAllQuery_) * `nestedQuery` (_NestedQuery_) * `termQuery` (_TermQuery_) * `textQuery` (_TextQuery_) _Example_ ``` { "filteredQuery": { "query": { "textQuery": { "fields": [ "couponId" ], "searchPhrase": "disabled" } }, "filter": { "termFilter": { "field": "enabled", "operator": "is", "values": [ false ] } } } } ``` ### Sort Document representing a sort request. Each API has a different default sort configuration that can be modified in the request. * `field` (_string_, required) The name of the field to sort on. Maximum length: 256. Example: `couponId`. * `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used. Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`. _Example_ ``` { "field": "couponId", "sortOrder": "desc" } ``` ### Offset The zero-based index of the first hit/data to include in the result. Type: `integer (int32)`. Default: `0`. Minimum: 0. Example: `0`. ### PaginatedSearchResult Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`. Includes all fields of `PaginatedResultBase`. * `query` (_Query_, required) * `sorts` (_array of Sort_) The sorting that was applied to the result. * `hits` (_array of object_) The sorted array of search hits. Can be empty. _Example_ ``` { "limit": 1, "hits": [ { "couponId": "coupon1", "creationDate": "2019-10-20T12:00:00Z", "description": "This coupon is used to give 10% off stuff.", "enabled": false, "exportedCodeCount": 0, "lastModified": "2019-10-30T04:23:59Z", "redemptionCount": 3, "redemptionLimits": { "limitPerCode": 1, "limitPerCustomer": 1, "limitPerTimeFrame": { "limit": 2, "redemptionTimeFrame": 24 } }, "singleCode": "MyCode", "systemCodesConfig": { "codePrefix": "SG", "numberOfCodes": 500000 }, "totalCodesCount": 50, "type": "single_code" } ], "query": { "textQuery": { "fields": [ "id", "description" ], "searchPhrase": "stuff" } }, "sorts": [ { "field": "couponId", "sortOrder": "desc" } ], "offset": 2, "total": 8 } ``` ### CustomerSearchHit Document representing a customer search hit. * `data` (_object_, required) List of found customers. Includes all fields of `Customer`. * `relevance` (_number (double)_, required) The hit's relevance score. Example: `1`. ### Credentials Document representing the credentials of a customer. * `enabled` (_boolean_) A flag indicating whether the customer is enabled and can log in. Example: `true`. * `locked` (_boolean_) A flag indicating whether the customer account is locked. Example: `false`. * `login` (_string_, required) The login of the customer. Maximum length: 256. Example: `wleung`. * `passwordQuestion` (_string_) The password question. Maximum length: 256. Example: `Pet Name?`. ### PaginatedResultBase Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`. Includes all fields of `ResultBase`. * `offset` (_Offset_, required) ### CustomerGroup Document representing a customer group. * `creationDate` (_string (date-time)_) The date the customer group was created. Example: `9999-12-31T00:00:00.0Z`. * `description` (_string_) Customer Group description. Maximum length: 4000. Example: `Customers who spent more than $1000 in last month`. * `id` (_string_, required) Customer Group id. Minimum length: 1. Maximum length: 256. Example: `Big Spenders`. * `inDeletion` (_boolean_) Boolean to indicate if the customer group is marked for deletion. Example: `false`. * `lastModified` (_string (date-time)_) The date the customer group was last modified. Example: `9999-12-31T00:00:00.0Z`. * `memberCount` (_integer (int32)_) Number of members in the customer group Example: `109`. * `rule` (_CustomerGroupRule_) * `type` (_string_) Customer Group Type. Allowed values: `system`, `dynamic`, `static`. Example: `static`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### ResultBase Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned. * `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema. Example: `10`. * `total` (_Total_, required) ### CustomerGroupMember * `customerNo` (_string_, required) Customer number of the customer group member Minimum length: 1. Maximum length: 100. Example: `00001234`. * `login` (_string_) Customer login Maximum length: 256. Example: `johndoe`. * `firstName` (_string_) Customer's first name Maximum length: 256. Example: `John`. * `lastName` (_string_) Customer's last name Maximum length: 256. Example: `Doe`. * `active` (_boolean_) Flag indicating whether the customer is active Example: `true`. ### BoolQuery A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses: * `must`, which combines as an `AND` operator. * `should`, which combines as an `OR` operator. * `must_not`, which combines as a `NOT` operator. If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example: ``` (must-1 AND must-1 AND ...) AND (should-1 OR should-2 OR ...) AND NOT (must_not-1 OR must_not-2 OR ...) ``` * `must` (_array of Query_) List of queries to be evaluated as an `AND` operator. * `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator. * `should` (_array of Query_) List of queries to be evaluated as an `OR` operator. _Example_ ``` { "must": [ { "textQuery": { "fields": [ "couponId" ], "searchPhrase": "DEAL" } }, { "textQuery": { "fields": [ "description" ], "searchPhrase": "Big bargain deal" } } ], "mustNot": [ { "termQuery": { "fields": [ "enabled" ], "operator": "is", "values": [ false ] } } ] } ``` ### FilteredQuery Allows to filter the result of a possibly complex query using a possibly complex filter. * `filter` (_Filter_, required) * `query` (_Query_, required) _Example_ ``` { "query": { "textQuery": { "fields": [ "couponId" ], "searchPhrase": "disabled" } }, "filter": { "termFilter": { "field": "enabled", "operator": "is", "values": [ false ] } } } ``` ### MatchAllQuery Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints. ### NestedQuery Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints. A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation. * `path` (_string_, required) The path to the nested document. Maximum length: 2048. Example: `order.shippingAddresses`. * `query` (_Query_, required) * `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score. Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`. _Example_ ``` { "path": "order.shippingAddresses", "query": { "boolQuery": { "must": [ { "boolQuery": { "must": [ { "termQuery": { "fields": [ "order.shippingAddresses.firstName" ], "operator": "is", "values": [ "John" ] } } ] } }, { "boolQuery": { "must": [ { "termQuery": { "fields": [ "order.shippingAddresses.lastName" ], "operator": "is", "values": [ "Doe" ] } } ] } } ] } }, "scoreMode": "avg" } ``` ### TermQuery A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator. **Limitations:** * The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise. * A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields. * `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator. Minimum items: 1. * `operator` (_string_, required) Returns the operator to use for the term query. Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`. * `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator. Items: Example: `myCouponId`. ### TextQuery A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields. * `fields` (_array of Field_, required) The document fields that the search phrase matches against. Minimum items: 1. * `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces. Example: `campaign summer`. _Example_ ``` { "fields": [ "couponId" ], "searchPhrase": "limit" } ``` ### CustomerGroupRule Customer Group Rule * `description` (_string_, required) Customer Group Rule description. Describing its conditions in natural language. Example: `Customers who spend more than $1000 in the last month`. ### Total The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated. Type: `integer (int32)`. Default: `0`. Minimum: 0. Example: `10`. ### Filter Contains a set of objects that define criteria used to select records. A filter can contain one of the following: * `TermFilter` * Matches records where a field (or fields) exactly matches some simple value (including `null`). * `RangeFilter` * Matches records where a field value lies within a specified range. * `Range2Filter` * Matches records in a specified range across fields. * `QueryFilter` * Matches records based on a query. * `BoolFilter` * Provides filtering of records using a set of filters combined using a logical operator. Minimum properties: 1. Maximum properties: 1. * `boolFilter` (_BoolFilter_) * `queryFilter` (_QueryFilter_) * `range2Filter` (_Range2Filter_) * `rangeFilter` (_RangeFilter_) * `termFilter` (_TermFilter_) ### Field Name of the field. Might be a custom field name prefixed with c\_. Type: `string`. Maximum length: 260. Example: `couponId`. ### BoolFilter Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator. * `filters` (_array of Filter_) A list of filters that are logically combined by an operator. * `operator` (_string_, required) The logical operator that is used to combine the filters. Allowed values: `and`, `or`, `not`. Example: `and`. _Example_ ``` { "operator": "and", "filters": [ { "termFilter": { "field": "id", "operator": "is", "values": [ "myId" ] } }, { "termFilter": { "field": "couponId", "operator": "is", "values": [ "couponOne" ] } } ] } ``` ### QueryFilter Wraps any query and allows it to be used as a filter. * `query` (_Query_, required) ### Range2Filter Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range. The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`. The second range (R2) is defined by `fromValue` and `toValue`. The filter mode specifies the method used to compare the two ranges: * `overlap`: R1 overlaps fully or partially with R2. * `containing`: R1 contains R2. * `contained`: R1 is contained in R2. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive. A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default. * `filterMode` (_string_) Compare mode: overlap, containing, or contained. Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`. * `fromField` (_object_, required) The field name of the field that starts the first range. Example: `validFrom`. Includes all fields of `Field`. Example: `validFrom`. * `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`. Default: `true`. Example: `true`. * `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended. Example: `2007-01-01T00:00:00.000Z`. * `toField` (_object_, required) The field name of the field that ends the first range. Example: `validTo`. Includes all fields of `Field`. Example: `validTo`. * `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`. Default: `true`. Example: `true`. * `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended. Example: `2017-01-01T00:00:00.000Z`. _Example_ ``` { "fromField": "validFrom", "toField": "validTo", "filterMode": "overlap", "fromValue": "2007-01-01T00:00:00.000Z", "toValue": "2017-01-01T00:00:00.000Z" } ``` ### RangeFilter Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive. A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default. * `field` (_object_, required) The search field. Example: `validFrom`. Includes all fields of `Field`. Example: `validFrom`. * `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended. One of: `string (date-time)`, `integer`, `number`. * _string (date-time)_ Type: `string (date-time)`. Example: `2007-01-01T00:00:00.000Z`. * _integer_ Type: `integer`. Example: `1`. * _number_ Type: `number`. Example: `1`. * `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`. Default: `true`. Example: `true`. * `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended. One of: `string (date-time)`, `integer`, `number`. * _string (date-time)_ Type: `string (date-time)`. Example: `2007-01-02T00:00:00.000Z`. * _integer_ Type: `integer`. Example: `2`. * _number_ Type: `number`. Example: `2`. * `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`. Default: `true`. Example: `true`. ### TermFilter Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only. * `field` (_object_, required) The filter field. Includes all fields of `Field`. * `operator` (_string_, required) The operator used to compare the field's values with the given values. Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`. * `values` (_array of string_) The filter values. Items: Example: `myId`. _Example_ ``` { "field": "id", "operator": "is", "values": [ "myId" ] } ```