Documentation

Custom Objects

Custom Objects store arbitrary JSON-formatted data on commercetools Composable Commerce.

Custom Objects allow 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 in one place. They are grouped into containers, which can be used like namespaces.

You can use Custom Objects to store custom data for a Product as an AttributeReferenceType 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​

Unique identifier of the CustomObject.

version​
Int​

Current version of the CustomObject.

key​
String​

User-defined unique identifier of the CustomObject within the defined container.

MinLength: 1​MaxLength: 256​Pattern: ^[-_~.a-zA-Z0-9]+$​
container​
String​

Namespace to group CustomObjects.

Pattern: ^[-_~.a-zA-Z0-9]+$​
value​
Any​

JSON standard types Number, String, Boolean, Array, Object, and common API data types. For values of type Reference the integrity of the data is not guaranteed. If the referenced object is deleted, the API does not delete the corresponding reference to it and the value points to a non-existing object in such case.

createdAt​
DateTime​

Date and time (UTC) the CustomObject was initially created.

createdBy​BETA
CreatedBy​

Present on resources created after 1 February 2019 except for events not tracked.

lastModifiedAt​
DateTime​

Date and time (UTC) the CustomObject was last updated.

lastModifiedBy​BETA
LastModifiedBy​

Present on resources created after 1 February 2019 except for events not tracked.

Example: json
{
  "id" : "fa58f10a-1df3-45e2-a49c-2bf06b17d168",
  "version" : 1,
  "createdAt" : "2018-09-11T14:12:05.512Z",
  "lastModifiedAt" : "2018-09-11T14:12:05.512Z",
  "container" : "myContainer",
  "key" : "myKey",
  "value" : {
    "text" : {
      "de" : "Das ist ein Text",
      "en" : "This is a text"
    },
    "order" : {
      "typeId" : "order",
      "id" : "<order-id>"
    }
  }
}

CustomObjectDraft

version​
Int​

Current version of the CustomObject.

key​
String​

User-defined unique identifier of the CustomObject within the defined container.

MinLength: 1​MaxLength: 256​Pattern: ^[-_~.a-zA-Z0-9]+$​
container​
String​

Namespace to group CustomObjects.

Pattern: ^[-_~.a-zA-Z0-9]+$​
value​
Any​

JSON standard types Number, String, Boolean, Array, Object, and common API data types. For values of type Reference the integrity of the data is not guaranteed. If the referenced object is deleted, the API does not delete the corresponding reference to it and the value points to a non-existing object in such case.

Example: json
{
  "container" : "myContainer",
  "key" : "myKey",
  "value" : {
    "text" : {
      "de" : "Das ist ein Text",
      "en" : "This is a text"
    },
    "order" : {
      "typeId" : "order",
      "id" : "<order-id>"
    }
  }
}

CustomObjectPagedQueryResponse

PagedQueryResult with results containing an array of CustomObject.

limit​
Int​

Number of results requested.

offset​
Int​

Number of elements skipped.

count​
Int​

Actual number of results returned.

total​
Int​

The total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false. When the results are filtered with a Query Predicate, total is subject to a limit.

results​
Array of CustomObject​

CustomObjects matching the query.

CustomObjectReference

Reference to a CustomObject.

id​
String​

Unique identifier of the referenced CustomObject.

typeId​
String​
"key-value-document"

References a CustomObject.

obj​
CustomObject​

Contains the representation of the expanded CustomObject. Only present in responses to requests with Reference Expansion for CustomObjects.

Get CustomObject by container and key

GET
https://api.{region}.commercetools.com/{projectKey}/custom-objects/{container}/{key}
OAuth 2.0 Scopes:
view_products:{projectKey}, view_orders:{projectKey}, view_customers:{projectKey}, view_key_value_documents:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

container
​
String
​

container of the CustomObject.

key
​
String
​

key of the CustomObject.

Query parameters:
expand
​
Expansion
​

Expands a value of type Reference. In case the referenced object does not exist, the API returns the non-expanded reference.

The parameter can be passed multiple times.
Response:

200CustomObject

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/custom-objects/{container}/{key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: CustomObjectjson
{
  "id" : "d8523d32-a79d-441c-90f4-744cc342126e",
  "version" : 2,
  "container" : "test-container",
  "key" : "test-key",
  "value" : "test-value",
  "createdAt" : "2016-02-18T10:36:29.468Z",
  "lastModifiedAt" : "2016-02-18T10:36:29.571Z"
}

Create or Update CustomObject

POST
https://api.{region}.commercetools.com/{projectKey}/custom-objects

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, then the version must match the version of the existing object. Concurrent updates for the same Custom Object can result in a 409 Conflict even if the version is not provided.

Fields with null values will not be saved.

OAuth 2.0 Scopes:
manage_products:{projectKey}, manage_orders:{projectKey}, manage_customers:{projectKey}, manage_key_value_documents:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
expand
​
Expansion
​

Expands a value of type Reference. In case the referenced object does not exist, the API returns the non-expanded reference.

The parameter can be passed multiple times.
Request Body:CustomObjectDraft
Response:

200CustomObject

201CustomObject

Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/custom-objects -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "container" : "test-container",
  "key" : "test-key",
  "value" : "test-value"
}
DATA
200 Response Example: CustomObjectjson
{
  "id" : "fa58f10a-1df3-45e2-a49c-2bf06b17d168",
  "version" : 1,
  "createdAt" : "2018-09-11T14:12:05.512Z",
  "lastModifiedAt" : "2018-09-11T14:12:05.512Z",
  "container" : "myContainer",
  "key" : "myKey",
  "value" : {
    "text" : {
      "de" : "Das ist ein Text",
      "en" : "This is a text"
    },
    "order" : {
      "typeId" : "order",
      "id" : "<order-id>"
    }
  }
}
201 Response Example: CustomObjectjson
{
  "id" : "d8523d32-a79d-441c-90f4-744cc342126e",
  "version" : 2,
  "container" : "test-container",
  "key" : "test-key",
  "value" : "test-value",
  "createdAt" : "2016-02-18T10:36:29.468Z",
  "lastModifiedAt" : "2016-02-18T10:36:29.571Z"
}

Query CustomObjects

GET
https://api.{region}.commercetools.com/{projectKey}/custom-objects/{container}
OAuth 2.0 Scopes:
view_products:{projectKey}, view_orders:{projectKey}, view_customers:{projectKey}, view_key_value_documents:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

container
​
String
​

container of the CustomObjectPagedQueryResponse.

Query parameters:
where
​
QueryPredicate
​

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")).

The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
​
Any string parameter matching this regular expression
​

Predicate parameter values.

The parameter can be passed multiple times.
sort
​
Sort
​

Query results can be sorted by container, key, createdAt, and lastModifiedAt.

The parameter can be passed multiple times.
expand
​
Expansion
​

Expands a value of type Reference. In case the referenced object does not exist, the API returns the non-expanded reference.

The parameter can be passed multiple times.
limit
​
Int
​

Number of results requested.

offset
​
Int
​

Number of elements skipped.

withTotal
​
Boolean
​

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Response:

200CustomObjectPagedQueryResponse

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/custom-objects/{container} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: CustomObjectPagedQueryResponsejson
{
  "limit" : 20,
  "offset" : 0,
  "count" : 2,
  "total" : 2,
  "results" : [ {
    "id" : "f584ebbb-3805-43f3-80c8-76f98b2c18b5",
    "version" : 5,
    "container" : "channel",
    "key" : "ac390383-370f-43f8-a534-db1604cb96a8",
    "value" : "{\"name\":\"commercetools Composable Commerce\",\"slug\":\"commercetools-composable-commerce\",\"lat\":52.523753,\"lng\":13.380434}",
    "createdAt" : "2015-05-28T09:48:35.098Z",
    "lastModifiedAt" : "2015-07-01T15:58:36.930Z"
  }, {
    "id" : "d8523d32-a79d-441c-90f4-744cc342126e",
    "version" : 2,
    "container" : "test-container",
    "key" : "test-key",
    "value" : "test-value",
    "createdAt" : "2016-02-18T10:36:29.468Z",
    "lastModifiedAt" : "2016-02-18T10:36:29.571Z"
  } ]
}

Delete CustomObject by container and key

DELETE
https://api.{region}.commercetools.com/{projectKey}/custom-objects/{container}/{key}
OAuth 2.0 Scopes:
manage_products:{projectKey}, manage_orders:{projectKey}, manage_customers:{projectKey}, manage_key_value_documents:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

container
​
String
​

container of the CustomObject.

key
​
String
​

key of the CustomObject.

Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​

Expands a value of type Reference. In case the referenced object does not exist, the API returns the non-expanded reference.

The parameter can be passed multiple times.
dataErasure
​
Boolean
​

Defaults to false. Set to true if you want to erase all related personal data in compliance with GDPR.

Response:

200CustomObject

Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/custom-objects/{container}/{key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: CustomObjectjson
{
  "id" : "d8523d32-a79d-441c-90f4-744cc342126e",
  "version" : 2,
  "container" : "test-container",
  "key" : "test-key",
  "value" : "test-value",
  "createdAt" : "2016-02-18T10:36:29.468Z",
  "lastModifiedAt" : "2016-02-18T10:36:29.571Z"
}