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

Money

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

  • currencyCode - String
    The currency code compliant to ↗ ISO 4217 .
  • centAmount - Number
    The amount in cents (the smallest indivisible unit of the currency).
{
  "currencyCode": "EUR",
  "centAmount":4200
}

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 string representation of a postal address. It consists of the following fields:

  • id - String - Optional
  • key - String - Optional, if given it must match ``
  • 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)