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

CustomObjectDraft

CustomObjectPagedQueryResponse

CustomObjectReference

CustomObjectKeyReference

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. Default: `20`Minimum: `0`Maximum: `500`
`offset` Int	Number of elements skipped. Default: `0`Maximum: `10000`
`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` Type of referenced resource.
`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"
}

CustomObjectKeyReference

Used by the Import API to identify a CustomObject.

`key` String	User-defined unique identifier of the referenced CustomObject.
`typeId` ReferenceType	`key-value-document` Type of referenced resource.
`container` String	The `container` of the referenced CustomObject.

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:

200

CustomObject

application/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:

200

CustomObject

application/json

201

CustomObject

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

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.
`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. Default: `20` Minimum: `0` Maximum: `500`
`offset` Int	Number of elements skipped. Default: `0` Maximum: `10000`
`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`
`var.<varName>` String	Predicate parameter values. The parameter can be passed multiple times.

Response:

200

CustomObjectPagedQueryResponse

application/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 one or more CustomObjects exist for the provided query predicate. Returns a 200 status if any CustomObjects match the query predicate, or a 404 status 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:

200

CustomObject

application/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"
}

Custom Objects

Representations.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

CustomObject.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

CustomObjectDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

CustomObjectPagedQueryResponse.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

CustomObjectReference.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

CustomObjectKeyReference.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Get CustomObject by container and key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Create or Update CustomObject.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Query CustomObjects.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if CustomObject exists.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if CustomObject exists by Query Predicate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Delete CustomObject by Container and Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Representations

CustomObject

CustomObjectDraft

CustomObjectPagedQueryResponse

CustomObjectReference

CustomObjectKeyReference

Get CustomObject by container and key

Create or Update CustomObject

Query CustomObjects

Check if CustomObject exists

Check if CustomObject exists by Query Predicate

Delete CustomObject by Container and Key