Common API Types

Common API Types used within multiple API resources.

LocalizedString

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

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

Reference

A Reference is a JSON object representing a (loose) reference to another resource on the commercetools platform. It consists of two fields:

  • typeId - String
    The typeId designates the type of the referenced resource (see the list of reference types below).
  • id - String
    The unique ID of the referenced resource.
{
  "typeId": "product",
  "id": "d1229e6f-2b79-441e-b419-180311e52754"
}

Reference Types

  • cart - Identifies a reference to a Cart.
  • cart-discount - Identifies a reference to a CartDiscount.
  • category - Identifies a reference to a Category.
  • channel - Identifies a reference to a Channel.
  • customer - Identifies a reference to a Customer.
  • customer-group - Identifies a reference to a CustomerGroup.
  • discount-code - Identifies a reference to a DiscountCode.
  • key-value-document - Identifies a reference to a CustomObject.
  • payment - Identifies a reference to a Payment.
  • product - Identifies a reference to a Product.
  • product-discount - Identifies a reference to a ProductDiscount.
  • product-price - Identifies a reference to a Price.
  • product-type - Identifies a reference to a ProductType.
  • order - Identifies a reference to an Order.
  • shipping-method - Identifies a reference to a ShippingMethod.
  • shopping-list - Identifies a reference to a ShoppingList.
  • state - Identifies a reference to a State.
  • tax-category - Identifies a reference to a TaxCategory.
  • type - Identifies a reference to a Type.
  • zone - Identifies a reference to a Zone.

Expanded Reference

If a reference is returned by a query endpoint and reference expansion of a certain reference was requested then the reference might contain an additional obj field containing the resource.

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 reference type 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

BaseMoney

Base polymorphic Money type which can be stored in cent or high precision. The actual type is determined by the field type. If the type field is not provided, it would be interpreted as a cent precision money due to backwards compatibility.

Money

Money is a JSON object combining a currency and an amount (in cents). It consists of four fields:

  • type - String with value centPrecision.
    When creating values of Money 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 amount in cents (the smallest indivisible unit of the currency).
  • fractionDigits - Number
    For money type it’s equal to the number of default fraction digits for a currency, can be omitted since it’s always equal to currency fraction digits.
{
 "currencyCode": "EUR",
 "centAmount":4200
}

or

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

HighPrecisionMoney

HighPrecisionMoney is a JSON object combining a currency and an amount below the smallest indivisible unit of the currency. It consists of five fields:

  • 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). 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 US 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:

    preciseAmount fractionDigits result
    123456 3 123.456
    123456 5 1.23456
    123456 7 0.0123456
  • fractionDigits - Number
    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.

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

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

Date

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

  "2001-09-11"

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:

  "2001-09-11T14:00:00.000Z"

Address

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

  • id - String - Optional
  • key - String - Optional, if given it must match [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
  • country - String
    A two-digit country code as per ↗ ISO 3166-1 alpha-2 .
  • 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

Asset

An Asset 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:

  • 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, e.g. 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)