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 from any third-party persistence solution and means that all your data stays in one place. Custom Objects are grouped into containers, which can be used like namespaces.

You can store custom data for Products and other entities in Custom Objects and access the data using Reference Expansion. With this approach, you can query for the custom data associated to the resource without the need for Custom Objects scopes.

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​

Can be any JSON standard type, such as number, string, boolean, array, object, or a common API data type.

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

IDs and references that created the CustomObject.

lastModifiedAt​
DateTime​

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

lastModifiedBy​BETA
LastModifiedBy​

IDs and references that last modified the CustomObject.

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​

Can be any JSON standard type, such as number, string, boolean, array, object, or a common API data type.

  • Fields within value that have null values are not saved.
  • 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​
ReferenceTypeId​
"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.

Example: json
{
  "id": "4e2b758f-f259-4c14-808e-2beb126bc0f1",
  "typeId": "key-value-document"
}

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. If 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 within value that have null values are not 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. If 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
​

container of the CustomObjectPagedQueryResponse.

Query parameters:
where
​
QueryPredicate
​

id, key, version, createdAt, and lastModifiedAt can be used as predicate. value can also be used as predicate, but is not checked for validity. For example: value(exampleNumber > 1233) or value(exampleObject(exampleBoolean = true)).

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

Default: true​
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",
        "slug": "commercetools",
        "geoLocation": {
          "type": "Point",
          "coordinates": [13.412119019109015, 52.50103330534661]
        }
      },
      "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
​
QueryPredicate
​

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

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

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

To erase all related personal data in compliance with GDPR, set to true.

Default: false​
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"
}