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 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` ReferenceTypeId	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 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: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`typeId` ReferenceTypeId	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	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` ReferenceTypeId	Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

ReferenceTypeId

Type of resource the value should reference. Supported resource type identifiers are:

approval-flow: References an ApprovalFlow.
approval-rule: References an ApprovalRule.
associate-role: References an AssociateRole.
attribute-group: References an AttributeGroup.
business-unit: References a BusinessUnit.
cart: References a Cart.
cart-discount: References a CartDiscount.
category: References a Category.
channel: References a Channel.
customer: References a Customer.
customer-email-token: References a CustomerToken for email verification.
customer-group: References a CustomerGroup.
customer-password-token: References a CustomerToken for password reset.
direct-discount: References a DirectDiscount.
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 Embedded Price.
product-selection: References a ProductSelection.
product-tailoring: References a ProductTailoring.
product-type: References a ProductType.
quote: References a Quote.
quote-request: References a QuoteRequest.
review: References a Review.
shipping-method: References a ShippingMethod.
shopping-list: References a ShoppingList.
staged-quote: References a StagedQuote.
standalone-price: References a StandalonePrice.
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 prices that are embedded into ProductVariants and Line Items, as well as common data types for Embedded Prices and Standalone Prices. The representations specific to Standalone Prices are documented on their dedicated page.

Price

This type is equivalent to ProductPrice in the GraphQL API.

The representation for prices embedded in LineItems and in ProductVariants when the ProductPriceMode is Embedded. For the Standalone ProductPriceMode refer to StandalonePrice.

`id` String	Unique identifier of this Price.
`key` String	User-defined identifier of the Price. It is unique per ProductVariant. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`value` TypedMoney	Money value of this Price.
`country` CountryCode	Country for which this Price is valid. Pattern: `^[A-Z]{2}$`
`customerGroup` CustomerGroupReference	CustomerGroup for which this Price is valid.
`channel` ChannelReference	`ProductDistribution` Channel for which this Price is valid.
`validFrom` DateTime	Date and time from which this Price is valid.
`validUntil` DateTime	Date and time until this Price is valid. Prices that are no longer valid are not automatically removed, but they can be removed if necessary.
`discounted` DiscountedPrice	Is set if a ProductDiscount has been applied. If set, the API uses the DiscountedPrice value for the Line Item 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. If `discounted` is present, the tiered Price is ignored for a Product Variant.
`custom` CustomFields	Custom Fields defined for the Price.

PriceDraft

This type is equivalent to ProductPriceDataInput in the GraphQL API.

The draft representation for prices to be embedded into ProductVariantDrafts when the ProductPriceMode is Embedded. For the Standalone ProductPriceMode use StandalonePriceDraft.

`key` String	User-defined identifier for the Price. It must be unique per ProductVariant. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`value` Money	Money value of this Price.
`country` CountryCode	Set this field if this Price is only valid for the specified country. Pattern: `^[A-Z]{2}$`
`customerGroup` CustomerGroupResourceIdentifier	Set this field if this Price is only valid for the referenced CustomerGroup.
`channel` ChannelResourceIdentifier	Set this field if this Price is only valid for the referenced `ProductDistribution` Channel.
`validFrom` DateTime	Set this field if this Price is only valid from the specified date and time. Must be at least 1 ms earlier than `validUntil`.
`validUntil` DateTime	Set this field if this Price is only valid until the specified date and time. Must be at least 1 ms later than `validFrom`. Prices that are no longer valid are not automatically removed, but they can be removed if necessary.
`discounted` DiscountedPriceDraft	Set this field to add a DiscountedPrice from an external service. Otherwise, Composable Commerce 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. If `discounted` is set, the tiered Price is ignored for a Product Variant.
`custom` CustomFieldsDraft	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. A Price or StandalonePrice cannot contain more than one tier with the same `minimumQuantity`.
`value` TypedMoney	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

This type is equivalent to ProductPriceTierInput in the GraphQL API.

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. A Price or StandalonePrice cannot contain more than one tier with the same `minimumQuantity`. In the case one of the constraint is not met an InvalidField is returned.
`value` Money	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` TypedMoney	Money value of the discounted price.
`discount` ProductDiscountReference	ProductDiscount related to the discounted price.

DiscountedPriceDraft

This type is equivalent to DiscountedProductPriceValueInput in the GraphQL API.

`value` Money	Sets the money value for the discounted price.
`discount` ProductDiscountReference	Relates the referenced ProductDiscount to the discounted price.

Moneys

TypedMoney -CentPrecisionMoney -HighPrecisionMoney

TypedMoneyDraft -Money -HighPrecisionMoneyDraft

MoneyType

Usage

TypedMoney

This type is equivalent to BaseMoney in the GraphQL API.

Polymorphic base read-only money type that holds money in cent precision or high precision (in sub-cents).

CentPrecisionMoney

This type is equivalent to Money in the GraphQL API.

Object that stores money in cent amounts of 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` CurrencyCode	Currency code compliant to ISO 4217.
`type` MoneyType	`"centPrecision"` Use to set currency in cent precision.
`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.

Object that stores money as a fraction of the smallest indivisible unit of 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` CurrencyCode	Currency code compliant to ISO 4217.
`type` MoneyType	`"highPrecision"` Use to set currency in high precision.
`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.

TypedMoneyDraft

This type is equivalent to BaseMoneyInput in the GraphQL API.

Polymorphic base money type that can hold money in cent precision or high precision (in sub-cents).

To set money in cent precision, use Money.
To set money in high precision, use HighPrecisionMoneyDraft.

Money

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

Draft object to store money in cent amounts for 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` CurrencyCode	Currency code compliant to ISO 4217.

Example: json

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

HighPrecisionMoneyDraft

This type is equivalent to HighPrecisionMoneyInput in the GraphQL API.

Draft object to store money as a fraction of the smallest indivisible unit for a specific 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 API calculates the value automatically using the default rounding mode half even.
`currencyCode` CurrencyCode	Currency code compliant to ISO 4217.
`type` MoneyType	`"highPrecision"` Use to set currency in high precision.
`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
}

MoneyType

Determines the type of money used.

centPrecision: Use to set currency in cent precision.
highPrecision: Use to set currency in high precision.

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 API 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:

preciseAmount	fractionDigits	Amount in currency
123456	3	123.456
123456	5	1.23456
123456	7	0.0123456

Both centAmount and preciseAmount are represented as 64-bit integers.

Please note that for HighPrecisionMoney, the more fractionDigits you use, the fewer integer digits are available, as both must fit into a 64-bit integer. For example, if you use the maximum allowable amount of 20 fractionDigits, the highest expressible amount is approximately 9 cents.

If a Money operation, such as arithmetic with unusually large amounts, results in either object exceeding the 64-bit limit, the API returns a 400 Bad Request with the MoneyOverflow error code.

Date and Time

Date

Time

DateTime

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

GeoJSON Geometry -Point

CountryCode

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

CurrencyCode

Currency code compliant to ISO 4217.

Locale

String value specifying linguistic and regional preferences using the IETF language tag format, as described in BCP 47. The format combines language, script, and region using hyphen-separated subtags. For example: en, en-US, zh-Hans-SG.

LocalizedString

JSON object where the keys are of type Locale, and the values are the strings used for the corresponding language.

Examplejson

{
  "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

BaseAddress -Address -AddressDraft

BaseAddress

Polymorphic base type that represents a postal address and contact details. Depending on the read or write action, it can be either Address or AddressDraft that only differ in the data type for the optional custom field.

`id` String	Unique identifier of the Address. It is not recommended to set it manually since the API overwrites this ID when creating an Address for a Customer. Use `key` instead and omit this field from the request to let the API generate the ID for the Address.
`key` String	User-defined identifier of the Address that must be unique when multiple addresses are referenced in BusinessUnits, Customers, and `itemShippingAddresses` (LineItem-specific addresses) of a Cart, Order, QuoteRequest, or Quote. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`externalId` String	ID for the contact used in an external system.
`country` CountryCode	Name of the country.
`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.

Address

Address type returned by read methods. Optionally, the custom field can be present in addition to the fields of a BaseAddress.

custom

CustomFields

Custom Fields defined for the Address.

AddressDraft

This type is equivalent to AddressInput in the GraphQL API.

Address type to be used on write methods. Optionally, use the custom field in addition to the fields of a BaseAddress.

custom

CustomFieldsDraft

Custom Fields defined for the Address.

Example: json

{
  "key": "address1",
  "title": "Mrs.",
  "firstName": "Jane",
  "lastName": "Doe",
  "streetName": "First Street",
  "streetNumber": "12",
  "postalCode": "12345",
  "city": "Example City",
  "country": "NL",
  "phone": "+312345678",
  "mobile": "+312345679",
  "email": "jane.doe@example.com"
}

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	Unique identifier of the Asset.
`key` String	User-defined identifier of the Asset. It is unique per Category or ProductVariant. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`sources` Array of AssetSource	MinItems: `1`
`name` LocalizedString	Name of the Asset.
`description` LocalizedString	Description of the Asset.
`tags` Array of String	Keywords for categorizing and organizing Assets.
`custom` CustomFields	Custom Fields defined for the Asset.

AssetDraft

`key` String	User-defined identifier for the Asset. Must be unique per Category or ProductVariant. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`sources` Array of AssetSource	MinItems: `1`
`name` LocalizedString	Name of the Asset.
`description` LocalizedString	Description of the Asset.
`tags` Array of String	Keywords for categorizing and organizing Assets.
`custom` CustomFieldsDraft	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 identifier of the AssetSource. Must be unique per Asset. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`uri` String	URI of the AssetSource.
`dimensions` AssetDimensions	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

IDs and references that created the resource. This is present on resources created after 1 February 2019 except for events not tracked.

`clientId` String	`id` of the API Client which created the resource.
`externalUserId` String	External user ID provided by the `X-External-User-ID` HTTP Header or `external_user_id:{externalUserId}` scope. MaxLength: `128`
`customer` CustomerReference	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.
`associate` CustomerReference	Indicates the Customer who created the resource in the context of a Business Unit. Only present when an Associate acts on behalf of a company using the associate endpoints.
`attributedTo` Attribution	Indicates if the resource was created indirectly.

LastModifiedBy BETA

IDs and references that last modified the resource. This is present on resources created or updated after 1 February 2019 except for events not tracked.

`clientId` String	`id` of the API Client which modified the resource.
`externalUserId` String	External user ID provided by the `X-External-User-ID` HTTP Header or `external_user_id:{externalUserId}` scope. MaxLength: `128`
`customer` CustomerReference	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.
`associate` CustomerReference	Indicates the Customer who modified the resource in the context of a Business Unit. Only present when an Associate acts on behalf of a company using the associate endpoints.
`attributedTo` Attribution	Indicates if the resource was modified indirectly.

Attribution BETA

Indicates the source and method that indirectly created or modified the resource. This is present on resources created or updated after 1 April 2024.

`clientId` String	`id` of the API Client that created or modified the resource.
`source` AttributionSource	Method used to initiate the creation or modification of the resource.

AttributionSource BETA

Import: Resource was created or updated during import.
Export: Resource was created or updated during export.

Warnings

WarningObject

Represents a warning related to the returned response.

`code` String	Identifier for the type of warning.
`message` String	Contains information about the returned response.

ImageProcessingOngoing Warning

Contained in responses to an Upload Product image or an Upload Product Tailoring image request with response status code 202 Accepted. Indicates that the API is still creating the remaining sizes of the uploaded image. They will be available on the Content Delivery Network (CDN) soon.

`code` String	`"ImageProcessingOngoing"`
`message` String	`"The image processing is still ongoing."`

Example: json

{
  "code": "ImageProcessingOngoing",
  "message": "The image processing is still ongoing."
}