--- schema_version: "1" id: 47ddc117ce590a16c370df04d9f885781c2a8dde8ff21d03b88254b41956a247 title: 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/custom-objects.md canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/custom-objects source_site: developer.salesforce.com content_type: documentation content_hash: 34a3dcd012c4b3f26cea9f601dc806d9171640b7bf622a12112f731410a1eea3 products: - B2C Commerce API - Salesforce APIs --- Custom Objects # Custom Objects [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/custom-objects/custom-objects-oas-v1-public.yaml) ## API Overview The Custom Objects API lets you manage custom objects in Commerce Cloud. ### Overview Custom objects are instances of custom object types that can hold any business-specific data. Each custom object belongs to an object type and is identified by a unique key attribute. Custom objects can be scoped globally (organization-level) or to a specific site. ### Key Features * **CRUD Operations**: Create, read, update, and delete custom objects by object type and key * **Search**: Search custom objects using flexible query expressions with pagination and sorting * **Site-Specific Scope**: Operate on global or site-specific custom objects via separate endpoints ### Searchable Attributes The following attributes can be used in search queries: * `keyValueString` - The string key value of the custom object (String) * `keyValueInteger` - The integer key value of the custom object (Integer) * `creationDate` - The creation date of the custom object (Date) * `lastModified` - The last modification date of the custom object (Date) * `siteId` - The site identifier (String) * Any custom attribute ### Sortable Attributes Only searchable attributes can be used in sorting. ### Authentication This API requires OAuth 2.0 authentication with the appropriate scopes: * `sfcc.custom-objects` - Read access to custom object resources * `sfcc.custom-objects.rw` - Read and write access to custom object resources **Version:** 1.1.0 ## Servers * `https://{shortCode}.api.commercecloud.salesforce.com/custom-object/custom-objects/v1` * `shortCode (default shortCode)` ## Security * `AmOAuth2` (oauth2) Authentication via Account Manager OAuth 2.0. * OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token) * Scope sfcc.custom-objects: Allows read access to custom objects. * Scope sfcc.custom-objects.rw: Allows read and write access to custom objects. ## Operations ### GET Read a global custom object by its object type ID and key. `GET /organizations/{organizationId}/custom-objects/{objectType}/{key}` Operation ID: `getCustomObject`. Security: AmOAuth2 (sfcc.custom-objects, sfcc.custom-objects.rw). Reads a global custom object with a given object type ID and a value for the key attribute of the object which represents its unique identifier. #### 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 ``` * `objectType` (path, string, required) The ID of the custom object type. Minimum length: 1. Maximum length: 256. Example: `MyCustomType`. * `key` (path, string, required) The key attribute value that identifies the custom object. Minimum length: 1. Maximum length: 256. Example: `my-key-value`. #### Responses * **200** Custom object retrieved successfully. Media type: `application/json`. Schema: `CustomObject`. _Example: CustomObjectResultExample_ ``` { "keyProperty": "global_key", "keyValueString": "my-key-value", "objectType": "MyCustomType", "c_textField": "some text value", "c_numberField": 42, "c_booleanField": true } ``` * **400** Bad request. Media type: `application/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 'abc' for data type 'integer' is invalid." } ``` * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "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." } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Your access token is valid, but you don’t have the required permissions to access the resource." } ``` * **404** Not found. Media type: `application/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 'nonexistent' for object type 'MyCustomType' could be found." } ``` _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 'NonExistentType' could be found." } ``` ### PUT Create or replace a global custom object. `PUT /organizations/{organizationId}/custom-objects/{objectType}/{key}` Operation ID: `createCustomObject`. Security: AmOAuth2 (sfcc.custom-objects.rw). Creates a global custom object from request body. Note that an existing global custom object with the same key will be overwritten by this action. #### 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 ``` * `objectType` (path, string, required) The ID of the custom object type. Minimum length: 1. Maximum length: 256. Example: `MyCustomType`. * `key` (path, string, required) The key attribute value that identifies the custom object. Minimum length: 1. Maximum length: 256. Example: `my-key-value`. #### Request body (required) Media type: `application/json`. Schema: `CustomObject`. _Example: CreateCustomObjectExample_ ``` { "c_textField": "some text value", "c_numberField": 42, "c_booleanField": true } ``` #### Responses * **200** Custom object replaced successfully. Media type: `application/json`. Schema: `CustomObject`. _Example: CustomObjectResultExample_ ``` { "keyProperty": "global_key", "keyValueString": "my-key-value", "objectType": "MyCustomType", "c_textField": "some text value", "c_numberField": 42, "c_booleanField": true } ``` * **201** Custom object created successfully. Media type: `application/json`. Schema: `CustomObject`. _Example: CustomObjectResultExample_ ``` { "keyProperty": "global_key", "keyValueString": "my-key-value", "objectType": "MyCustomType", "c_textField": "some text value", "c_numberField": 42, "c_booleanField": true } ``` * **400** Bad request. Media type: `application/json`. Schema: `ErrorResponse`. _Example MalformedKeyParameter: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 400 response._ * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example UnauthorizedExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 401 response._ * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example ForbiddenExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 403 response._ * **404** Not found. Media type: `application/json`. Schema: `ErrorResponse`. _Example ObjectTypeNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._ ### DELETE Delete a global custom object. `DELETE /organizations/{organizationId}/custom-objects/{objectType}/{key}` Operation ID: `deleteCustomObject`. Security: AmOAuth2 (sfcc.custom-objects.rw). Deletes a global custom object. If the custom object does not exist, this will do nothing. #### 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 ``` * `objectType` (path, string, required) The ID of the custom object type. Minimum length: 1. Maximum length: 256. Example: `MyCustomType`. * `key` (path, string, required) The key attribute value that identifies the custom object. Minimum length: 1. Maximum length: 256. Example: `my-key-value`. #### Responses * **204** Custom object deleted successfully. * **400** Bad request. Media type: `application/json`. Schema: `ErrorResponse`. _Example MalformedKeyParameter: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 400 response._ * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example UnauthorizedExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 401 response._ * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example ForbiddenExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 403 response._ * **404** Not found. Media type: `application/json`. Schema: `ErrorResponse`. _Example ObjectTypeNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._ ### PATCH Update a global custom object. `PATCH /organizations/{organizationId}/custom-objects/{objectType}/{key}` Operation ID: `updateCustomObject`. Security: AmOAuth2 (sfcc.custom-objects.rw). Updates a global custom object with information from request body. Note that only mentioned attributes will be updated and the key attribute is ignored. All other attributes will be left unattended. #### 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 ``` * `objectType` (path, string, required) The ID of the custom object type. Minimum length: 1. Maximum length: 256. Example: `MyCustomType`. * `key` (path, string, required) The key attribute value that identifies the custom object. Minimum length: 1. Maximum length: 256. Example: `my-key-value`. #### Request body (required) Media type: `application/json`. Schema: `CustomObject`. _Example: UpdateCustomObjectExample_ ``` { "c_textField": "updated text value" } ``` #### Responses * **200** Custom object updated successfully. Media type: `application/json`. Schema: `CustomObject`. _Example: CustomObjectResultExample_ ``` { "keyProperty": "global_key", "keyValueString": "my-key-value", "objectType": "MyCustomType", "c_textField": "some text value", "c_numberField": 42, "c_booleanField": true } ``` * **400** Bad request. Media type: `application/json`. Schema: `ErrorResponse`. _Example MalformedKeyParameter: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 400 response._ * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example UnauthorizedExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 401 response._ * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example ForbiddenExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 403 response._ * **404** Not found. Media type: `application/json`. Schema: `ErrorResponse`. _Example CustomObjectNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._ _Example ObjectTypeNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._ ### POST Search custom objects by object type. `POST /organizations/{organizationId}/custom-objects-search/{objectType}` Operation ID: `searchCustomObjects`. Security: AmOAuth2 (sfcc.custom-objects, sfcc.custom-objects.rw). Searches for custom objects of a specific object type. The query attribute specifies a complex query that can be used to narrow down the search. The following attributes are searchable: * `keyValueString` (String) * `keyValueInteger` (Integer) * `creationDate` (Date) * `lastModified` (Date) * `siteId` (String) * Any custom attribute Only searchable attributes can be used in sorting. #### 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 ``` * `objectType` (path, string, required) The ID of the custom object type. Minimum length: 1. Maximum length: 256. Example: `MyCustomType`. * `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 50. Default: `50`. Minimum: 1. Maximum: 200. * `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset. Default: `0`. Minimum: 0. #### Request body (required) Media type: `application/json`. Schema: `SearchRequest`. _Example: SearchCustomObjectsExample_ ``` { "query": { "matchAllQuery": {} }, "limit": 25, "offset": 0, "sorts": [ { "field": "key_value_string", "sortOrder": "asc" } ] } ``` _Example: SearchCustomObjectsBySiteIdExample_ Search custom objects belonging to a specific site Restricts the search to custom objects of a specific site by filtering on the searchable `siteId` attribute. Custom object search is not scoped by site at the URL level, so filtering by `siteId` is the supported way to limit results to a single site. ``` { "query": { "termQuery": { "fields": [ "siteId" ], "operator": "is", "values": [ "SiteGenesis" ] } }, "limit": 25, "offset": 0 } ``` #### Responses * **200** Custom objects search result. Media type: `application/json`. Schema: `CustomObjectSearchResult`. _Example: CustomObjectSearchResultExample_ ``` { "limit": 2, "hits": [ { "keyProperty": "global_key", "keyValueString": "key1", "objectType": "MyCustomType", "c_textField": "value1" }, { "keyProperty": "global_key", "keyValueString": "key2", "objectType": "MyCustomType", "c_textField": "value2" } ], "query": { "matchAllQuery": {} }, "offset": 0, "total": 2 } ``` * **400** Bad request. Media type: `application/json`. Schema: `ErrorResponse`. _Example: TypeMismatch_ ``` { "title": "Type Mismatch", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/type-mismatch", "detail": "There is a type mismatch for field 'key_value_integer'." } ``` * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example UnauthorizedExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 401 response._ * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example ForbiddenExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 403 response._ * **404** Not found. Media type: `application/json`. Schema: `ErrorResponse`. _Example ObjectTypeNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._ ### GET Read a site-specific custom object by its object type ID and key. `GET /organizations/{organizationId}/sites/{siteId}/custom-objects/{objectType}/{key}` Operation ID: `getSiteCustomObject`. Security: AmOAuth2 (sfcc.custom-objects, sfcc.custom-objects.rw). Reads a site-specific custom object with a given object type ID and a value for the key attribute of the object which represents its unique identifier. #### 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` (path, SiteId, required) The ID of the site that the custom object belongs to. _Example_ ``` SiteGenesis ``` * `objectType` (path, string, required) The ID of the custom object type. Minimum length: 1. Maximum length: 256. Example: `MyCustomType`. * `key` (path, string, required) The key attribute value that identifies the custom object. Minimum length: 1. Maximum length: 256. Example: `my-key-value`. #### Responses * **200** Custom object retrieved successfully. Media type: `application/json`. Schema: `CustomObject`. _Example: CustomObjectResultExample_ ``` { "keyProperty": "global_key", "keyValueString": "my-key-value", "objectType": "MyCustomType", "c_textField": "some text value", "c_numberField": 42, "c_booleanField": true } ``` * **400** Bad request. Media type: `application/json`. Schema: `ErrorResponse`. _Example MalformedKeyParameter: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 400 response._ * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example UnauthorizedExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 401 response._ * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example ForbiddenExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 403 response._ * **404** Not found. Media type: `application/json`. Schema: `ErrorResponse`. _Example CustomObjectNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._ _Example ObjectTypeNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._ ### PUT Create or replace a site-specific custom object. `PUT /organizations/{organizationId}/sites/{siteId}/custom-objects/{objectType}/{key}` Operation ID: `createSiteCustomObject`. Security: AmOAuth2 (sfcc.custom-objects.rw). Creates a site-specific custom object from request body. Note that an existing site-specific custom object with the same key will be overwritten by this action. #### 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` (path, SiteId, required) The ID of the site that the custom object belongs to. _Example_ ``` SiteGenesis ``` * `objectType` (path, string, required) The ID of the custom object type. Minimum length: 1. Maximum length: 256. Example: `MyCustomType`. * `key` (path, string, required) The key attribute value that identifies the custom object. Minimum length: 1. Maximum length: 256. Example: `my-key-value`. #### Request body (required) Media type: `application/json`. Schema: `CustomObject`. _Example: CreateCustomObjectExample_ ``` { "c_textField": "some text value", "c_numberField": 42, "c_booleanField": true } ``` #### Responses * **200** Custom object replaced successfully. Media type: `application/json`. Schema: `CustomObject`. _Example: CustomObjectResultExample_ ``` { "keyProperty": "global_key", "keyValueString": "my-key-value", "objectType": "MyCustomType", "c_textField": "some text value", "c_numberField": 42, "c_booleanField": true } ``` * **201** Custom object created successfully. Media type: `application/json`. Schema: `CustomObject`. _Example: CustomObjectResultExample_ ``` { "keyProperty": "global_key", "keyValueString": "my-key-value", "objectType": "MyCustomType", "c_textField": "some text value", "c_numberField": 42, "c_booleanField": true } ``` * **400** Bad request. Media type: `application/json`. Schema: `ErrorResponse`. _Example MalformedKeyParameter: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 400 response._ * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example UnauthorizedExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 401 response._ * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example ForbiddenExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 403 response._ * **404** Not found. Media type: `application/json`. Schema: `ErrorResponse`. _Example ObjectTypeNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._ ### DELETE Delete a site-specific custom object. `DELETE /organizations/{organizationId}/sites/{siteId}/custom-objects/{objectType}/{key}` Operation ID: `deleteSiteCustomObject`. Security: AmOAuth2 (sfcc.custom-objects.rw). Deletes a site-specific custom object. If the custom object does not exist, this will do nothing. #### 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` (path, SiteId, required) The ID of the site that the custom object belongs to. _Example_ ``` SiteGenesis ``` * `objectType` (path, string, required) The ID of the custom object type. Minimum length: 1. Maximum length: 256. Example: `MyCustomType`. * `key` (path, string, required) The key attribute value that identifies the custom object. Minimum length: 1. Maximum length: 256. Example: `my-key-value`. #### Responses * **204** Custom object deleted successfully. * **400** Bad request. Media type: `application/json`. Schema: `ErrorResponse`. _Example MalformedKeyParameter: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 400 response._ * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example UnauthorizedExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 401 response._ * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example ForbiddenExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 403 response._ * **404** Not found. Media type: `application/json`. Schema: `ErrorResponse`. _Example ObjectTypeNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._ ### PATCH Update a site-specific custom object. `PATCH /organizations/{organizationId}/sites/{siteId}/custom-objects/{objectType}/{key}` Operation ID: `updateSiteCustomObject`. Security: AmOAuth2 (sfcc.custom-objects.rw). Updates a site-specific custom object with information from request body. Note that only mentioned attributes will be updated and the key attribute is ignored. All other attributes will be left unattended. #### 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` (path, SiteId, required) The ID of the site that the custom object belongs to. _Example_ ``` SiteGenesis ``` * `objectType` (path, string, required) The ID of the custom object type. Minimum length: 1. Maximum length: 256. Example: `MyCustomType`. * `key` (path, string, required) The key attribute value that identifies the custom object. Minimum length: 1. Maximum length: 256. Example: `my-key-value`. #### Request body (required) Media type: `application/json`. Schema: `CustomObject`. _Example: UpdateCustomObjectExample_ ``` { "c_textField": "updated text value" } ``` #### Responses * **200** Custom object updated successfully. Media type: `application/json`. Schema: `CustomObject`. _Example: CustomObjectResultExample_ ``` { "keyProperty": "global_key", "keyValueString": "my-key-value", "objectType": "MyCustomType", "c_textField": "some text value", "c_numberField": 42, "c_booleanField": true } ``` * **400** Bad request. Media type: `application/json`. Schema: `ErrorResponse`. _Example MalformedKeyParameter: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 400 response._ * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example UnauthorizedExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 401 response._ * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example ForbiddenExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 403 response._ * **404** Not found. Media type: `application/json`. Schema: `ErrorResponse`. _Example CustomObjectNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._ _Example ObjectTypeNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 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`. ### 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. Minimum length: 1. Maximum length: 256. Example: `myKey`. * `keyValueInteger` (_integer (int32)_) The id of the custom object when the type of the key is Integer. This is ignored in input documents. Example: `42`. * `keyValueString` (_string_) The id of the custom object when the type of the key is String. This is ignored in input documents. Minimum length: 1. Maximum length: 256. Example: `my-key-value`. * `objectType` (_string_) The id of the object type. This is ignored in input documents. Maximum length: 256. Example: `MyCustomType`. * `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'. Example: `2019-10-20T12:00:00Z`. * `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'. Example: `2019-10-20T13:00:00Z`. 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`. ### 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_) ### CustomObjectSearchResult Search result containing a paginated list of custom objects. Includes all fields of `PaginatedSearchResult`. * `hits` (_array of CustomObject_, required) The sorted array of search hits. Can be empty. ### 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`. ### 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 } ``` ### 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_ ``` { "value": { "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" } ``` ### 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) ### 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`. ### 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) ### 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_ ``` { "value": { "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" ] } ``` ### 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`.