Documentation

Common API Data Types

Common API Types used within multiple API resources.

References

Reference

A Reference is a JSON object representing a (loose) reference to another resource on the commercetools platform. Reference supports Reference Expansion.

  • typeId - ReferenceType
    The type of referenced resource.
  • id - String
    The unique ID of the referenced resource.
  • obj – Object – Optional
    If Reference Expansion for a resource is requested, obj contains the properties of the referenced object.
{
  "typeId": "product",
  "id": "d1229e6f-2b79-441e-b419-180311e52754"
}

KeyReference

A KeyReference is a JSON object representing a loose reference to another resource on the commercetools platform by the resource's key field. When available, the key is immutable and mandatory. KeyReference does not support Reference Expansion.

  • typeId - ReferenceType
    The type of referenced resource.
  • key - String
    The unique and immutable key of the referenced resource.

ReferenceType

The reference type enumeration contains the following:

ResourceIdentifier

A reference to a resource can be created by providing the ID of the resource. Some resources also use the key as a unique identifier and a reference can be created by providing the key instead of the ID. In this case, the server will find the resource with the given key and use the ID of the found resource to create a reference.

The typeId is optional, but if given, it must match the expected ReferenceType of the referenced resource.

ResourceIdentifier by ID

  • id - String
    The unique ID of the referenced resource.
  • typeId - String - Optional
    The typeId of the reference

ResourceIdentifier by Key

  • key - String
    The unique key of the referenced resource.
  • typeId - String - Optional
    The typeId of the reference

The essential difference between ResourceIdentifiers and References is that the former acts as the draft object of the latter. In the draft, the caller of the API can choose between using the ID or the Key, whereas the response always returns either the respective Reference or the KeyReference depending on what the API endpoint determines. For example, the field parent of a CategoryDraft takes a ResourceIdentifier for its value while the value of the field parent of a Category is a Reference.

Localization

CountryCode

A string value representing a two-digit country code as per ISO 3166-1 alpha-2.

CurrencyCode

A currency code compliant to ISO 4217.

Locale

A string matching the pattern: ^[a-z]{2}(-[A-Z]{2})?$ representing an IETF language tag.

LocalizedString

A JSON object where the keys are of IETF language tag, and the values are the corresponding strings used for that language.

{
  "de": "Hundefutter",
  "en": "dog food"
}

TypedMoney

Base polymorphic read-only money type that stores currency amounts either in cent precision or in sub-cents, named as high precision. The actual type is determined by the type field, which takes either centPrecision or highPrecision.

This type is equivalent to BaseMoney in the GraphQL API.

CentPrecisionMoney

Object that stores cent amounts in a specific currency.

  • type - String with value centPrecision.
  • currencyCode - String
    The currency code compliant to ISO 4217.
  • centAmount - Number
    The smallest indivisible unit of a currency, such as, cents for USD or centime for CHF. The centAmount value for currencies without minor units (like JPY) excludes the fraction digits. For example, 5 JPY is specified as 5, whereas 5 CHF is specified as 500.
  • fractionDigits - Number
    The number of default fraction digits for the given currency, like 2 for EUR or 0 for JPY.
{
  "currencyCode": "EUR",
  "centAmount": 4200
}

or

{
  "type": "centPrecision",
  "currencyCode": "EUR",
  "centAmount": 4200,
  "fractionDigits": 2
}

This type is equivalent to Money in the GraphQL API.

HighPrecisionMoney

JSON object combining a currency and an amount below the smallest indivisible unit of the currency.

  • type - String with value highPrecision.

  • currencyCode - String
    The currency code compliant to ISO 4217.

  • centAmount - Number
    The amount in cents (the smallest indivisible unit of the currency) calculated by the commercetools Platform based on the preciseAmount provided by the client using the default rounding mode half even.

  • preciseAmount - Number
    The amount in 1 / (10 ^ fractionDigits) of a currency. Here are some examples:

    preciseAmountfractionDigitsAmount in currency
    1234563123.456
    12345651.23456
    12345670.0123456

  • fractionDigits - Number
    The number of fraction digits for a specified high precision money. Can't be less than or equal to the default number of fraction digits for the given currency. The maximum amount of fractionDigits is 20.

Usage:
For EUR and USD the smallest amount you use in financial transaction is the cent. In particular cases - usually when higher quantities of a certain item are bought - the unit price will be specified in sub-cents.

One example can be a gas station where gas prices are displayed as 1,197 EUR per liter.
This can only be expressed by using HighPrecisionMoney since it is impossible to represent it by just using the default fraction digits of a currency for EUR, which is 2. As a result, with Money it is only possible to define the price as 1.19 EUR or 1.20 EUR. To represent the previously mentioned gas price using sub-cents, you need to use HighPrecisionMoney type.

Most currencies like USD and EUR have 2 fraction digits (usually called cents).
Some currencies like JPY do not have fraction digits at all, for these currencies the fractionDigits is set to 0.
Some currencies like JOD - Jordanian Dinar have 3 fraction digits. With high precision money, fraction digits must be greater than the default number for the desired currency. The platform validates this when creating a price with high precision money. Therefore, you cannot create HighPrecisionMoney of currency EUR with fractionDigits of 2, because this is the default for the desired currency what can be expressed using regular Money instead.

Example:

{
  "type": "highPrecision",
  "currencyCode": "EUR",
  "centAmount": 1,
  "preciseAmount": 123456,
  "fractionDigits": 7
}

This type is equivalent to HighPrecisionMoney in the GraphQL API.

Money

Money is the draft representation of TypedMoney. The actual type is determined by the type field, which takes either centPrecision or highPrecision.

This type is equivalent to BaseMoneyInput in the GraphQL API.

CentPrecisionMoneyDraft

  • type - String with value centPrecision. - Optional
    When creating values of CentPrecisionMoney it's not necessary to specify this field since it's the default.
  • currencyCode - String
    The currency code compliant to ISO 4217.
  • centAmount - Number
    The smallest indivisible unit of a currency, such as, cents for USD or centime for CHF. The centAmount value for currencies without minor units (like JPY) excludes the fraction digits. For example, 5 JPY is specified as 5, whereas 5 CHF is specified as 500.
  • fractionDigits - Number - Optional
    When provided it must be equal to the number of default fraction digits for the given currency. The value is assigned by the platform automatically when not provided.

This type is equivalent to MoneyInput or MoneyDraft in the GraphQL API.

HighPrecisionMoneyDraft

JSON object combining a currency and an amount below the smallest indivisible unit of the currency. For intended use cases, please see HighPrecisionMoney.

  • type - String with value highPrecision.

  • currencyCode - String
    The currency code compliant to ISO 4217.

  • centAmount - Number - Optional
    The amount in cents (the smallest indivisible unit of the currency). This field is optional for high precision and it does not need to be provided by the client. If it is provided, then it is checked for validity: Basically, a price of 1.015 USD can be rounded either to 1.01 USD or 1.02 USD. If it is outside of this range, an error that centAmount must be correctly rounded will be sent back. If centAmount is not provided by the client, the platform will automatically calculate the value, using the default rounding mode half even.

  • preciseAmount - Number
    The amount in 1 / (10 ^ fractionDigits) of a currency. Here are some examples:

    preciseAmountfractionDigitsAmount in currency
    1234563123.456
    12345651.23456
    12345670.0123456

  • fractionDigits - Number - Optional
    The number of fraction digits for a specified high precision money. Note that you can't specify a HighPrecisionMoney that has fraction digits less than or equal to what the currency has by default. The maximum amount of fractionDigits that the platform supports is 20.

Example:

{
  "type": "highPrecision",
  "currencyCode": "EUR",
  "preciseAmount": 123456,
  "fractionDigits": 7
}

This type is equivalent to HighPrecisionMoneyInput in the GraphQL API.

Date

A Date is a JSON string representation of a date without timezone in ISO 8601 format (YYYY-MM-DD), for example:

"2018-10-12"

Time

A Time is a JSON string representation of a time without timezone in ISO 8601 format (hh:mm:ss.sss), for example:

"14:00:00.000"

DateTime

A DateTime is a JSON string representation of UTC date & time in ISO 8601 format (YYYY-MM-DDThh:mm:ss.sssZ), for example:

"2018-10-12T14:00:00.000Z"

Addresses

An Address is a JSON object representation of a postal address. It consists of the following fields:

Address

  • country - String
    A two-digit country code as per ISO 3166-1 alpha-2.
  • id - String - Optional
  • key - String - Optional
    User-defined identifier for the address. If given, it must follow the pattern [a-zA-Z0-9_\-]{2,256}.
  • title- String - Optional
  • salutation - String - Optional
  • firstName - String - Optional
  • lastName - String - Optional
  • streetName - String - Optional
  • streetNumber - String - Optional
  • additionalStreetInfo - String - Optional
  • postalCode - String - Optional
  • city - String - Optional
  • region - String - Optional
  • state - String - Optional
  • company - String - Optional
  • department - String - Optional
  • building - String - Optional
  • apartment - String - Optional
  • pOBox - String - Optional
  • phone - String - Optional
  • mobile - String - Optional
  • email - String - Optional
  • fax - String - Optional
  • additionalAddressInfo - String - Optional
  • externalId - String - Optional
  • custom - CustomFields - Optional

AddressDraft

  • country - String
    A two-digit country code as per ISO 3166-1 alpha-2.
  • id - String - Optional
    Note: The id is overwritten internally when creating an address for a Customer.
  • key - String - Optional
    User-defined identifier for the address. If given, it must follow the pattern [a-zA-Z0-9_\-]{2,256}.
  • title- String - Optional
  • salutation - String - Optional
  • firstName - String - Optional
  • lastName - String - Optional
  • streetName - String - Optional
  • streetNumber - String - Optional
  • additionalStreetInfo - String - Optional
  • postalCode - String - Optional
  • city - String - Optional
  • region - String - Optional
  • state - String - Optional
  • company - String - Optional
  • department - String - Optional
  • building - String - Optional
  • apartment - String - Optional
  • pOBox - String - Optional
  • phone - String - Optional
  • mobile - String - Optional
  • email - String - Optional
  • fax - String - Optional
  • additionalAddressInfo - String - Optional
  • externalId - String - Optional
  • custom - CustomFieldsDraft - Optional

Assets

Assets can be used to represent media assets, such as images, videos, or PDFs.
Please find more information about use of Assets in the respective tutorial.
An Asset consists of the following fields:

Asset

  • id - String
  • key - String - Optional User-defined identifier for the asset.
    Asset keys are unique inside their container (a product variant or a category).
  • sources - Array of AssetSource - Has at least one entry
  • name - Localized String
  • description - Localized String - Optional
  • tags - Array of String - Optional
  • custom - CustomFields - Optional

AssetDraft

AssetSource

An AssetSource is a representation of an Asset in a specific format, for example a video in a certain encoding, or an image in a certain resolution.

  • uri - String
  • key - String - Optional - Must be unique within the Asset
  • dimensions - AssetDimensions - Optional
  • contentType - String - Optional

AssetDimensions

The width and height of the asset source.

  • w - Number - The width of the asset source
  • h - Number - The height of the asset source

GeoJSON Geometry

A GeoJSON Geometry represents a Geometry Object as defined in the GeoJSON standard.

For the moment, only the Point type is supported.

Point

  • type - String with value "Point"
  • coordinates - Array containing two Number (longitude, latitude)

Client logging

These objects represent information about which API client created or modified a resource. For more information, see Client Logging.

CreatedBy BETA

  • clientId - String - Optional
    The ID of the API Client which created a resource.
  • externalUserId - String - Optional
    External user ID provided by X-External-User-ID HTTP Header. Maximum length is 128 characters.
  • customer - Reference to a Customer - Optional. Present when creating a resource using a token from the password flow.
  • anonymousId - String - Optional
    Present when creating a resource using a token from an anonymous session.

LastModifiedBy BETA

  • clientId - String - Optional
    The ID of the API Client which modified a resource.
  • externalUserId - String - Optional
    External user ID provided by X-External-User-ID HTTP Header. Maximum length is 128 characters.
  • customer - Reference to a Customer - Optional. Present when modifying a resource using a token from the password flow.
  • anonymousId - String - Optional
    Present when modifying a resource using a token from an anonymous session.