Common API Data Types

Common API Types used within multiple API resources.

References

Reference

A Reference represents a loose reference to another resource in the same commercetools Project identified by its id. The typeId indicates the type of the referenced resource. Each resource type has its corresponding Reference type, like ChannelReference. A referenced resource can be embedded through Reference Expansion. The expanded reference is the value of an additional obj field then.

id
String

Unique ID of the referenced resource.

typeId

Type of referenced resource.

Example: json
{
"typeId" : "product",
"id" : "d1229e6f-2b79-441e-b419-180311e52754"
}

KeyReference

A KeyReference represents a loose reference to another resource in the same commercetools Project identified by the resource's key field. If available, the key is immutable and mandatory. KeyReferences do not support Reference Expansion.

key
String

User-defined unique and immutable key of the referenced resource.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
typeId

Type of referenced resource.

ResourceIdentifier

Draft type to create a Reference or a KeyReference to a resource. Provide either the id or (wherever supported) the key of the resource to reference, but depending on the API endpoint the response returns either a Reference or a KeyReference. For example, the field parent of a CategoryDraft takes a ResourceIdentifier for its value while the value of the corresponding field of a Category is a Reference.

Each resource type has its corresponding ResourceIdentifier, like ChannelResourceIdentifier.

id
String

Platform-generated unique identifier of the referenced resource. Required if key is absent.

key
String

User-defined unique identifier of the referenced resource. Required if id is absent.

typeId

Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

ReferenceTypeId

supported resource type identifiers:

cart

References a Cart.

cart-discount

References a CartDiscount.

category

References a Category.

channel

References a Channel.

customer

References a Customer.

customer-group

References a CustomerGroup.

discount-code

References a DiscountCode.

extension

References an Extension.

inventory-entry

References an InventoryEntry.

key-value-document

References a CustomObject.

order

References an Order.

order-edit

References an Order Edit.

payment

References a Payment.

product

References a Product.

product-discount

References a ProductDiscount.

product-price

References an EmbeddedPrice.

product-selection

References a ProductSelection.

product-type

References a ProductType.

review

References a Review.

shipping-method

References a ShippingMethod.

shopping-list

References a ShoppingList.

state

References a State.

store

References a Store.

subscription

References a Subscription.

tax-category

References a TaxCategory.

type

References a Type.

zone

References a Zone.

Prices

This section contains representations for price-related types.

Price

id
String

Platform-generated unique identifier of this Price.

value

Money value of this Price.

country

Country for which this Price is valid.

Pattern: ^[A-Z]{2}$
customerGroup

CustomerGroup for which this Price is valid.

channel

ProductDistribution Channel for which this Price is valid.

validFrom

Date and time from which this Price is valid.

validUntil

Date and time until this Price is valid.

discounted

Is set if a ProductDiscount has been applied. If set, the commercetools Platform uses the DiscountedPrice value for the LineItem Price selection. When a relative discount has been applied and the fraction part of the DiscountedPrice value is 0.5, the value is rounded in favor of the customer with half down rounding.

tiers
Array of PriceTier

Present if different Prices for certain LineItem quantities have been specified.

custom

Custom Fields defined for the Price.

PriceDraft

value

Money value of this Price.

country

Set this field if this Price is only valid for the specified country.

Pattern: ^[A-Z]{2}$
customerGroup

Set this field if this Price is only valid for the referenced CustomerGroup.

channel

Set this field if this Price is only valid for the referenced ProductDistribution Channel.

validFrom

Set this field if this Price is valid only valid from the specified date and time.

validUntil

Set this field if this Price is valid only valid until the specified date and time.

discounted

Set this field to add a DiscountedPrice from an external service.

The commercetools Platform sets this field automatically if at least one ProductDiscount applies. The DiscountedPrice must reference a ProductDiscount with:

  • The isActive flag set to true.
  • A ProductDiscountValue of type external.
  • A predicate that matches the ProductVariant the Price is referenced from.
tiers
Array of PriceTierDraft

Set this field to specify different Prices for certain LineItem quantities.

custom

Custom Fields for the Price.

PriceTier

A Price tier is selected instead of the default Price when a certain quantity of the ProductVariant is added to a Cart and ordered. For example: the Price can be lower if more than 10 items are ordered. If no Price tier is found for the Order quantity, the base Price is used. A Price tier is applied for the entire quantity of a Product Variant put as LineItem in a Cart as soon as the minimum quantity for the Price tier is reached. The Price tier is applied per Line Item of the Product Variant. If, for example, the same Product Variant appears in the same Cart as several Line Items, (what can be achieved by different values of a Custom Field on the Line Items) for each Line Item the minimum quantity must be reached to get the Price tier.

minimumQuantity
Int

Minimum quantity this Price tier is valid for.

The minimum quantity is always greater than or equal to 2. The base Price is interpreted as valid for a minimum quantity equal to 1.

value

Money value that applies when the minimumQuantity is greater than or equal to the LineItem quantity.

The currencyCode of a Price tier is always the same as the currencyCode in the value of the related Price.

PriceTierDraft

Specifies a Price tier that applies when the minimum quantity for the LineItem of a ProductVariant with the related Price is reached in a Cart.

minimumQuantity
Int

Minimum quantity this Price tier is valid for.

The minimum quantity is always greater than or equal to 2. The base Price is interpreted as valid for a minimum quantity equal to 1.

value

Money value that applies when the minimumQuantity is greater than or equal to the LineItem quantity.

The currencyCode of a Price tier must be the same as the currencyCode in the value of the related Price.

DiscountedPrice

value

Money value of the discounted price.

discount

ProductDiscount related to the discounted price.

DiscountedPriceDraft

value

Sets the money value for the discounted price.

discount

Relates the referenced ProductDiscount to the discounted price.

Moneys

TypedMoney

This type is equivalent to BaseMoney in the GraphQL API.

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.

CentPrecisionMoney

This type is equivalent to Money in the GraphQL API.

Object that stores cent amounts in a specific currency.

centAmount
Int

Amount in the smallest indivisible unit of a currency, such as:

  • Cents for EUR and USD, pence for GBP, or centime for CHF (5 CHF is specified as 500).
  • The value in the major unit for currencies without minor units, like JPY (5 JPY is specified as 5).
currencyCode

Currency code compliant to ISO 4217.

type
String
"centPrecision"

for CentPrecisionMoney.

fractionDigits
Int

The number of default fraction digits for the given currency, like 2 for EUR or 0 for JPY.

Maximum: 3
Example: json
{
"type" : "centPrecision",
"currencyCode" : "EUR",
"centAmount" : 4200,
"fractionDigits" : 2
}

HighPrecisionMoney

This type is equivalent to HighPrecisionMoney in the GraphQL API.

Money object that stores an amount of a fraction of the smallest indivisible unit of the specified currency.

centAmount
Int

Amount in the smallest indivisible unit of a currency, such as:

  • Cents for EUR and USD, pence for GBP, or centime for CHF (5 CHF is specified as 500).
  • The value in the major unit for currencies without minor units, like JPY (5 JPY is specified as 5).
currencyCode

Currency code compliant to ISO 4217.

type
String
"highPrecision"

for HighPrecisionMoney.

fractionDigits
Int

Number of digits after the decimal separator, greater than the default number of fraction digits for a currency.

Maximum: 20
preciseAmount
Int

Amount in 1 / (10 ^ fractionDigits) of a currency.

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

For details on how to use fraction digits and some examples, refer to Usage.

Money

This type is equivalent to BaseMoneyInput in the GraphQL API.

Draft type that stores amounts in cent precision for the specified currency.

For storing money values in fractions of the minor unit in a currency, use HighPrecisionMoneyDraft instead.

centAmount
Int

Amount in the smallest indivisible unit of a currency, such as:

  • Cents for EUR and USD, pence for GBP, or centime for CHF (5 CHF is specified as 500).
  • The value in the major unit for currencies without minor units, like JPY (5 JPY is specified as 5).
currencyCode

Currency code compliant to ISO 4217.

Example: json
{
"currencyCode" : "EUR",
"centAmount" : 4200
}

CentPrecisionMoneyDraft

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

centAmount
Int

Amount in the smallest indivisible unit of a currency, such as:

  • Cents for EUR and USD, pence for GBP, or centime for CHF (5 CHF is specified as 500).
  • The value in the major unit for currencies without minor units, like JPY (5 JPY is specified as 5).
currencyCode

Currency code compliant to ISO 4217.

type
String
"centPrecision"

for CentPrecisionMoney.

fractionDigits
Int

This field is optional for cent precision. If provided, it must be equal to the default number of fraction digits for the specified currency.

Maximum: 3
Example: json
{
"centAmount" : 4200,
"currencyCode" : "EUR",
"type" : "centPrecision"
}

HighPrecisionMoneyDraft

This type is equivalent to HighPrecisionMoneyInput in the GraphQL API.

Money draft object to store an amount of a fraction of the smallest indivisible unit of the specified currency.

centAmount
Int

Amount in the smallest indivisible unit of a currency. This field is optional for high precision. If provided, it is checked for validity. Example:

A Price of 1.015 USD can be rounded either to 1.01 USD or 1.02 USD. If it lies outside of this range, an error message stating that centAmount must be rounded correctly will be returned.

If centAmount is not provided, the commercetools Platform calculates the value automatically using the default rounding mode half even.

currencyCode

Currency code compliant to ISO 4217.

type
String
"highPrecision"

for HighPrecisionMoney.

fractionDigits
Int

Number of fraction digits for a specified high precision money. It must be greater than the default number of fraction digits for the specified currency.

Maximum: 20
preciseAmount
Int

Amount in 1 / (10 ^ fractionDigits) of a currency.

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

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 using only the default fractionDigits for EUR, which is 2. As a result, with CentPrecisionMoney 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 the HighPrecisionMoney type.

Most currencies like USD and EUR have 2 fraction digits (usually called cents). However, there are some exceptions, for example: JPY - Japanese Yen does not have fraction digits at all. For this type of currencies fractionDigits is set to 0. Some currencies like JOD - Jordanian Dinar have 3 fraction digits. With HighPrecisionMoney, fractionDigits must be greater than the default number for the desired currency. The platform validates this when creating a price with a HighPrecisionMoneyDraft.

For example, you cannot create a HighPrecisionMoney type with fractionDigits of 2 for the currency EUR, since this is the default value for this currency. Instead, regular Money can be used in this case.

The following table shows how fractionDigits affect a preciseAmount:

preciseAmountfractionDigitsAmount in currency
1234563123.456
12345651.23456
12345670.0123456

Date and Time

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"

Localization

CountryCode

CurrencyCode

Locale

LocalizedString

/^[a-z]{2}-[A-Z]{2}?$/
Any string property matching this regular expression

String used for the specified language.

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

GeoJSON Geometry

Representation of a Geometry Object as defined in the GeoJSON standard. Currently, only the Point type is supported.

Point

type
String
"Point"
coordinates
Array of Number

Longitude (stored on index [0]) and latitude (stored on index [1]) of the Point.

Addresses

Representation of a postal address and contact details.

Address

id
String

Platform-generated unique identifier of the Address.

key
String

User-defined unique identifier of the Address.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
country

Two-digit country code as per ISO 3166-1 alpha-2.

title
String

Title of the contact, for example 'Dr.'

salutation
String

Salutation of the contact, for example 'Mr.' or 'Ms.'

firstName
String

Given name (first name) of the contact.

lastName
String

Family name (last name) of the contact.

streetName
String

Name of the street.

streetNumber
String

Street number.

additionalStreetInfo
String

Further information on the street address.

postalCode
String

Postal code.

city
String

Name of the city.

region
String

Name of the region.

state
String

Name of the state, for example, Colorado.

company
String

Name of the company.

department
String

Name of the department.

building
String

Number or name of the building.

apartment
String

Number or name of the apartment.

pOBox
String

Post office box number.

phone
String

Phone number of the contact.

mobile
String

Mobile phone number of the contact.

email
String

Email address of the contact.

fax
String

Fax number of the contact.

additionalAddressInfo
String

Further information on the Address.

externalId
String

ID for the contact used in an external system.

custom

Custom Fields defined for the Address.

AddressDraft

id
String

Unique identifier for the Address. Not recommended to set it manually since the Platform overwrites this ID when creating an Address for a Customer. Use key instead and omit this field to let the Platform generate the ID for the Address.

key
String

User-defined unique identifier for the Address.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
country

Two-digit country code as per ISO 3166-1 alpha-2.

title
String

Title of the contact, for example 'Dr.'

salutation
String

Salutation of the contact, for example 'Mr.' or 'Ms.'

firstName
String

Given name (first name) of the contact.

lastName
String

Family name (last name) of the contact.

streetName
String

Name of the street.

streetNumber
String

Street number.

additionalStreetInfo
String

Further information on the street address.

postalCode
String

Postal code.

city
String

Name of the city.

region
String

Name of the region.

state
String

Name of the state, for example, Colorado.

company
String

Name of the company.

department
String

Name of the department.

building
String

Number or name of the building.

apartment
String

Number or name of the apartment.

pOBox
String

Post office box number.

phone
String

Phone number of the contact.

mobile
String

Mobile phone number of the contact.

email
String

Email address of the contact.

fax
String

Fax number of the contact.

additionalAddressInfo
String

Further information on the Address.

externalId
String

ID for the contact used in an external system.

custom

Custom Fields defined for the Address.

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.

Asset

id
String

Platform-generated unique identifier of the Asset.

key
String

User-defined unique identifier of the Asset.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
sources
Array of AssetSource
MinItems: 1
name

Name of the Asset.

description

Description of the Asset.

tags
Array of String

Keywords for categorizing and organizing Assets.

custom

Custom Fields defined for the Asset.

AssetDraft

key
String

User-defined unique identifier for the Asset.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
sources
Array of AssetSource
MinItems: 1
name

Name of the Asset.

description

Description of the Asset.

tags
Array of String

Keywords for categorizing and organizing Assets.

custom

Custom Fields defined for the Asset.

AssetSource

Representation of an Asset in a specific format, for example a video in a certain encoding, or an image in a certain resolution.

key
String

User-defined unique identifier of the AssetSource.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
uri
String

URI of the AssetSource.

dimensions

Width and height of the AssetSource.

contentType
String

Indicates the type of content, for example application/pdf.

AssetDimensions

Dimensions of the Asset source specified by the number of pixels.

w
Int

Width of the Asset source.

h
Int

Height of the Asset source.

Client logging

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

CreatedBy BETA

Present on resources created after 1 February 2019 except for events not tracked.

clientId
String

id of the APIClient which created the resource.

externalUserId
String

External user ID provided by X-External-User-ID HTTP Header.

MaxLength: 128
customer

Indicates the Customer who created the resource using a token from the password flow.

anonymousId
String

Indicates the anonymous session during which the resource was created.

LastModifiedBy BETA

Present on resources modified after 1 February 2019 except for events not tracked.

clientId
String

id of the APIClient which modified the resource.

externalUserId
String

External user ID provided by X-External-User-ID HTTP Header.

MaxLength: 128
customer

Indicates the Customer who modified the resource using a token from the password flow.

anonymousId
String

Indicates the anonymous session during which the resource was modified.

Developer Center
HTTP APIGraphQL APIPlatform Release NotesCustom ApplicationsBETASDKs & Client LibrariesImport & ExportSUNRISE Starter FrontendsTutorialsFAQ
Merchant Center
DocumentationRelease Notes
Sign upLog inTech BlogIntegrationsStatusSupportUser Research Program
Copyright © 2022 commercetools
Privacy PolicyImprint