This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official 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. For other entities, you can store custom data as a ReferenceType Custom Field 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: 1MaxLength: 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.

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.

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: 1MaxLength: 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
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:
200CustomObjectasapplication/json
Request Example:cURL
curl --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 to the same Custom Object returns a ConcurrentModification error 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:CustomObjectDraftasapplication/json
Response:
200CustomObjectasapplication/json201CustomObjectasapplication/json
Request Example:cURL
curl 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
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:
200CustomObjectPagedQueryResponseasapplication/json
Request Example:cURL
curl --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": "test-container",
"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"
}
]
}

Check if CustomObject exists

Check if CustomObject exists by Query Predicate

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

Checks if a CustomObject exists for a given Query Predicate. Returns a 200 OK status if any CustomObjects match the Query Predicate or a 404 Not Found otherwise.

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.

Query parameters:
where

Query Predicates on CustomObjects are limited to Text, Enum, Boolean, Number, Date, Time, and DateTime attribute types.

The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/custom-objects -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:
version
Int

Last seen version of the resource.

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.
dataErasure
Boolean

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

Response:
200CustomObjectasapplication/json
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"
}