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: 2MaxLength: 256Pattern: ^[-_~.a-zA-Z0-9]+$
createdAt

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

createdByBETA

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

lastModifiedAt

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

lastModifiedByBETA

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

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
{
"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: 2MaxLength: 256Pattern: ^[-_~.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

id
String

Unique identifier of the referenced CustomObject.

typeId
String
"key-value-document"

References a CustomObject.

obj

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

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}'
Response 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>"
}
}
}

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

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
CustomObject Response 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>"
}
}
}
CustomObject Response 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>"
}
}
}

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
Query parameters:
where

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

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

The parameter can be passed multiple times.
expand

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

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

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.
version
Int

Last seen version of the resource.

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}'
Response 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>"
}
}
}