Custom Objects

Store custom JSON values.

Custom objects are a way to store arbitrary JSON-formatted data on the commercetools platform. It allows you to persist data that does not fit our standard data model. This frees your application completely from any third-party persistence solution and means that all your data stays on the commercetools platform.

Custom objects are grouped into containers, which can be used like namespaces.

Representations

CustomObject

In the value field, it is possible to put a reference to another object . In the following example, the order field is a reference to an order:

{
  "value": {
    "order": {
      "typeId": "order",
      "id": "<order-id>"
    }
  },
  [...]
}

Such a reference can be expanded.

Be aware that the integrity of the data is not guaranteed. If the referenced object is deleted, the reference will not be deleted and will point to a non-existing object.

When asking to expand an invalid reference, the API will return the non-expanded reference.

CustomObjectDraft

Get CustomObject by id

Endpoint: /{projectKey}/custom-objects/{id}
Method: GET
OAuth2 Scopes: view_products:{projectKey}, view_orders:{projectKey}, view_customers:{projectKey}
Response Representation: CustomObject

Get CustomObject by container and key

Endpoint: /{projectKey}/custom-objects/{container}/{key}
Method: GET
OAuth2 Scopes: view_products:{projectKey}, view_orders:{projectKey}, view_customers:{projectKey}
Response Representation: CustomObject

Create or Update a CustomObject

Endpoint: /{projectKey}/custom-objects
Method: POST
OAuth2 Scopes: manage_products:{projectKey}, manage_orders:{projectKey}, manage_customers:{projectKey}
Request Representation: CustomObjectDraft
Response Representation: CustomObject

Creates a new custom object or updates an existing custom object.
If an object with the given container/key exists, the object is replaced with the new value and the version is incremented.
The version control is optional. If the request contains a version and an object with the given container/key exists then the version must match the version of the existing object.

Fields with null values will not be saved.

Query CustomObjects

The query endpoint allows to retrieve custom objects in a specific container or all custom objects.

For performance reasons, it is highly advisable to query only for custom objects in a container by using the container field in the where predicate.

Endpoint: /{projectKey}/custom-objects
Method: GET
OAuth2 Scopes: view_products:{projectKey}, view_orders:{projectKey}, view_customers:{projectKey}
Response Representation: PagedQueryResult with the results array of CustomObject
Query Parameters:

Delete CustomObject by ID

Endpoint: /{projectKey}/custom-objects/{id}
Method: DELETE
OAuth2 Scopes: manage_products:{projectKey}, manage_orders:{projectKey}, manage_customers:{projectKey}
Query Parameters:

Delete CustomObject by Container and Key

Endpoint: /{projectKey}/custom-objects/{container}/{key}
Method: DELETE
OAuth2 Scopes: manage_products:{projectKey}, manage_orders:{projectKey}, manage_customers:{projectKey}