--- schema_version: "1" id: 230991c022d4ff4081b542b34a1d6ae5561ed3fe0887a7b25e8adcc9101b9561 title: Shopper Custom Objects 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/shopper-custom-objects.md canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-custom-objects source_site: developer.salesforce.com content_type: documentation content_hash: 4ccf15cc1284cb9f3c3d46263c4b39992cec438e60293c63efb42661c99ae15b products: - B2C Commerce API - Salesforce APIs --- Shopper Custom Objects # Shopper Custom Objects [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-custom-objects/shopper-custom-objects-oas-v1-public.yaml) ## API Overview Custom Objects hold configuration information that is unique to your business, such as third-party configuration information or special field values for Product Information Management (PIM) systems. For example, if your out-of-the-box B2C Commerce product attributes do not include employee ID information, you can create a custom attribute for employee ID and use this API to retrieve the information. You provide access to this Custom Object information when requesting a SLAS token. Use Business Manager to set up Custom Object types, including a definition of the object and the values it contains. Use the Shopper Custom Objects API to retrieve Custom Object information. You can specify an object type ID as well as a key attribute for the object. ### Authentication & Authorization The Shopper Custom Objects API requires a shopper access token from the Shopper Login and API Access Service (SLAS). You must include `sfcc.shopper-custom-objects.{object_type}` in the client ID used to generate the token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html) For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html) in the SLAS guides. Important: Using an additional scope namespace, you can define exactly which Custom Object types a specific token can access. The requested custom `object_type` must exactly match the `object-type` specified in the scope. Note that SLAS is capable of handling a maximum of 20 Custom Object scopes. For example, to limit access to a specific Custom Object type, such as `employee_details`, include it as the `object_type`. In this case, only the `employee_details` custom object type can be accessed: ``` sfcc.shopper-custom-objects.employee_details ``` To grant global access to all Custom Object types, specify: ``` sfcc.shopper-custom-objects ``` For access to multiple Custom Object types, define the applicable scope(s) in the SLAS API client scopes to be included in the SLAS token, for example: ``` sfcc.shopper-custom-objects.employee_details sfcc.shopper-custom-objects.employee_performance ``` ### Customization #### Custom Properties This API supports custom properties (prefixed with `c_`). For details, see [Custom Properties.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-properties.html) ### Request Details #### URL Encoding If resource identifiers in request parameters contain commas (`,`) or percent signs (`%`), they must be URL encoded. For details, see [Encode URL Special Characters.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-encode.html) ### Response Details #### Personalization Responses from this API are not personalized via the Shopper Context API. #### Caching Responses from this API are not cached. Custom object data is dynamic and may change frequently. #### Timeouts Shopper API requests must respond within 10 seconds, including any hook execution. 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) ### Use Cases #### Get a Custom Object Retrieve a custom object by its type and key. ```sh curl "https://{shortCode}.api.commercecloud.salesforce.com/custom-object/shopper-custom-objects/v1/organizations/{organizationId}/custom-objects/employee_details/emp_123?siteId=RefArch" \ -H "Authorization: Bearer {access_token}" ``` #### Create and View Custom Object Types Custom object types are created in Business Manager: 1. Navigate to **Administration** -> **Site Development** -> **Custom Object Types**. 2. In the **Custom Object Type List** section, the available Custom Objects are listed. 3. To create a new Custom Object type, select **New** and enter the applicable information. This creates the `custom_object_type` information that is in the call to the Shopper Custom Objects API endpoint. Additionally, keys that provide additional information can be defined for Custom Object types, for example, a `employee_id` key for an `employee_details` Custom Object type. #### Request Custom Object Information To request Custom Object type information, the Custom Object type is specified following `custom-objects/` in the API URL: ``` https://{shortCode}/custom-object/shopper-custom-objects/v1/organizations/{organizationId}/custom-objects/{objectType}/{key} ``` `key` is an optional parameter that retrieves additional Custom Object type information, if available. For example, to retrieve the Custom Object type key `employee_id` for the Custom Object type `employee_details`: ``` https://{shortCode}/custom-object/shopper-custom-objects/v1/organizations/{organizationId}/custom-objects/employee_details/employee_id?siteId=RefArch. ``` ### Constraints Custom Object scopes: SLAS is capable of handling a maximum of 20 custom object scopes. Custom Objects: Maximum 27 custom objects. For additional details, see [Governance and Quotas.](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-governance-and-quotas.html) ### Troubleshooting The Custom Object type requested must exactly match, including case, the information in the SLAS token, for example: If the scope is `sfcc.custom-object-type.employee_details`, `employee_details` must match the information in the Shopper Custom Objects request: ``` https://…/custom-object/shopper-custom-objects/v1/organizations/f_ecom_bgmj_stg/custom-objects/employee_details/{key}?siteId` ``` If you do not include the `shopper-custom-objects` as part of the SLAS token request, and you subsequently call the Shopper Custom Objects API, a 401 error is returned. If you specify `key` information when no `key` information has been defined for the Custom Object, a 404 response code is returned. **Version:** 1.1.2 ## Servers * `https://{shortCode}.api.commercecloud.salesforce.com/custom-object/shopper-custom-objects/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 * `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both the Open Commerce API (OCAPI) and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token. * OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token) * Scope sfcc.shopper-custom-objects: Shopper Custom Objects scope * Scope sfcc.shopper-custom-objects.{objectType}: Shopper Custom Objects objectType READ ONLY scope * OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token) * Scope sfcc.shopper-custom-objects: Shopper Custom Objects scope * Scope sfcc.shopper-custom-objects.{objectType}: Shopper Custom Objects objectType READ ONLY scope * `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only. * OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context) * Scope sfcc.shopper-custom-objects: Shopper Custom Objects scope * Scope sfcc.shopper-custom-objects.{objectType}: Shopper Custom Objects objectType READ ONLY scope ## Operations ### GET Read a custom object using its object type ID and its unique key attribute value. `GET /organizations/{organizationId}/custom-objects/{objectType}/{key}` Operation ID: `getCustomObject`. Security: ShopperToken (sfcc.shopper-custom-objects, sfcc.shopper-custom-objects.{objectType}); ShopperClientContextToken (sfcc.shopper-custom-objects, sfcc.shopper-custom-objects.{objectType}). #### 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 ``` * `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified. _Example: LanguageCountry_ ``` en-US ``` _Example: CountryCode_ ``` US ``` * `objectType` (path, string, required) The object type of custom object. Minimum length: 1. Example: `Test_Integer`. * `key` (path, string, required) The key to identify the custom object. Minimum length: 1. Example: `1`. * `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken. Example: `550e8400-e29b-41d4-a716-446655440000`. * `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response. Allowed values: `none`. Example: `none`. * `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application. #### Responses * **200** Custom object retrieved successfully. Media type: `application/json`. Schema: `CustomObject`. _Example: CustomObjectResultExample_ ``` { "keyProperty": "global_key", "objectType": "Global_String", "c_BooleanAttribute": true, "c_DateAttribute": "2015-02-03", "c_DateTimeAttribute": "2015-02-20T01:00:00.000Z", "c_EmailAttribute": "tralala@gmail.com", "c_HtmlAttribute": "\r\nsome title\r\nthe body\r\n", "c_ImageAttribute": "https://whatever/on/demandware.static/-/Sites/default/v0/home/user/images/image.gif", "c_IntegerAttribute": 42, "c_IntegerEnumAttribute": 3, "c_IntegerSetAttribute": [ 1, 2 ], "c_NumberAttribute": 42, "c_NumberSetAttribute": [ 1, 1.1 ], "c_PasswordAttribute": "UUIG6ydSpJtdBbYDb1JMd7jgiA1rwYmQTzB5AEvz/YjorR6cIl19cu1IN6H/i/Ol", "c_StringAttribute": "Tralala", "c_StringEnumAttribute": "Value3", "c_StringSetAttribute": [ "string1", "string2" ], "c_TextAttribute": "This is a text, which is not very meaningful." } ``` * **400** Bad request Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: MalformedKeyParameter_ ``` { "title": "Malformed Key Parameter", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-key-parameter", "detail": "The format of path parameter 'gdd' for data type 'integer' is invalid.", "value": "gdd", "parameter": "integer" } ``` * **401** Unauthorized Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: Unauthorized_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Your access token is invalid or expired and can’t be used to identify a user.", "accessToken": "hbGciOiJIUzI1NiIsenR5cCI6Ikp" } ``` * **404** Not found Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: CustomObjectNotFound_ ``` { "title": "Custom Object Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/custom-object-not-found", "detail": "No custom object with key '2213' for object type 'Test_Integer' could be found.", "key": "2213", "objectType": "Test_Integer" } ``` _Example: ObjectTypeNotFound_ ``` { "title": "Object Type Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/object-type-not-found", "detail": "No object type with ID 'Test_Integer1' could be found.", "objectType": "Test_Integer1" } ``` ## 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`. ### 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`. ### LocaleCode A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified. One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`. ### CustomObject Document representing a custom object that contains all defined custom attributes for its object type. * `keyProperty` (_string_) The name of the key property for the custom object. This is ignored in input documents. Example: `global_key`. * `keyValueInteger` (_integer (int32)_) The id of the custom object when the type of the key is Integer. This is ignored in input documents. Example: `1`. * `keyValueString` (_string_) The id of the custom object when the type of the key is String. This is ignored in input documents. Example: `1`. * `objectType` (_string_) The id of the object type. This is ignored in input documents. Maximum length: 256. Example: `Global_String`. 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`. ### 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`. ### LanguageCountry A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'. Type: `string`. Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`. ### LanguageCode A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). Type: `string`. Pattern: ^\[a-z\]\[a-z\]$. Example: `en`. ### DefaultFallback A specialized value indicating the system default values for locales. Type: `string`. Default: `default`. Pattern: ^default$. Example: `default`.