j1.1.0
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.
For details on how to request a shopper access token from SLAS, see the guest user flows for public clients and private clients 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.
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.
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.
Error Handling
Error responses follow the RFC 7807 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.
Use Cases
Get a Custom Object
Retrieve a custom object by its type and key.
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:
- Navigate to Administration -> Site Development -> Custom Object Types.
- In the Custom Object Type List section, the available Custom Objects are listed.
- To create a new Custom Object type, select New and enter the applicable information. This creates the
custom_object_typeinformation 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.
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.
Let us know so we can improve!