Documentation

Custom Objects

Store schema-free JSON documents.

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 the 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. The combination of a container and a user-defined key uniquely identifies a Custom Object.

You can use Custom Objects to store custom data for a Product as a ReferenceType Attribute, or as a ReferenceType Custom Object by setting referenceTypeId to key-value-document. When you do this, any data stored in the Custom Object is accessible using Reference Expansion, and no additional scopes are required.

A maximum number of 20 000 000 Custom Objects can be created per project. Learn more about this limit.

Representations

CustomObject

  • id - String
  • createdAt - DateTime
  • lastModifiedAt - DateTime
  • container - String, matching the pattern [-_~.a-zA-Z0-9]+
    A namespace to group Custom Objects.
  • key - String, matching the pattern [-_~.a-zA-Z0-9]+
  • value - JSON types Number, String, Boolean, Array, Object
  • version - Number

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

  • container - String, matching the pattern [-_~.a-zA-Z0-9]+
    A namespace to group Custom Objects.
  • key - String, matching the pattern [-_~.a-zA-Z0-9]+
    A user-defined key that is unique within the given container.
  • value - JSON types Number, String, Boolean, Array, Object
  • version - Number - Optional

Get CustomObject by container and key

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

Create or Update a CustomObject

Endpoint: /{projectKey}/custom-objects
Method: POST
OAuth 2.0 Scopes: manage_products:{projectKey}, manage_orders:{projectKey}, manage_customers:{projectKey}, manage_key_value_documents:{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 will be replaced with the new value and the version is incremented. 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. Concurrent updates for the same Custom Object still can result in a Conflict (409) even if the version is not provided.

Fields with null values will not be saved.

Query CustomObjects

The query endpoint allows to retrieve Custom Objects in a specific container.

Endpoint: /{projectKey}/custom-objects/{container}/
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}, view_orders:{projectKey}, view_customers:{projectKey}, view_key_value_documents:{projectKey}
Response Representation: PagedQueryResult with results containing an array of CustomObject
Query Parameters:

  • where - Query Predicate - Optional
    The fields id, key, version, createdAt and lastModifiedAt can be used as predicate.
    The field value can also be used as predicate but is not checked for validity.
    For example, you can use any predicates: value(aValue=true) or value(myObject(myValue="abc"))
  • sort - Sort - Optional
    It is possible to sort by container, key, createdAt and lastModifiedAt.
  • limit - Number - Optional
  • expand - Expansion - Optional
  • offset - Number - Optional

Delete CustomObject by container and key

Endpoint: /{projectKey}/custom-objects/{container}/{key}
Method: DELETE
OAuth 2.0 Scopes: manage_products:{projectKey}, manage_orders:{projectKey}, manage_customers:{projectKey}, manage_key_value_documents:{projectKey}
Query Parameters:

  • dataErasure - Boolean - Optional, defaults to false