j1.0.12
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
Use Cases
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://{{short-code}}/custom-object/shopper-custom-objects/v1/organizations/{organization_id}/custom-objects/{custom_object_type}/{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://{{short-code}}/custom-object/shopper-custom-objects/v1/organizations/{organization_id}/custom-objects/employee_details/employee_id?siteId=RefArch.
Use Hooks
For details working with hooks, see Extensibility with Hooks.
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!