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 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

  • 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 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 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 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:

  • where - Query Predicate - Optional
    The fields container, key, 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
  • offset - Number - Optional

Delete CustomObject by ID

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

  • version - Number - Optional
    The version control is optional. If the query contains a version, then it must match the version of the object.

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}