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

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

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

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 data types Embedded Prices and Standalone Prices have in common. 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: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
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. Prices that are no longer valid are not automatically removed, but they can be removed if necessary.

discounted

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

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: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
value

Money value of this Price.

country

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

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

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

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

validFrom

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

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

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:

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

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

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

ProductDiscount related to the discounted price.

DiscountedPriceDraft

value

Sets the money value for the discounted price.

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 in cent precision or high precision, that is in sub-cents.

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

Type of money used.

fractionDigits
Int

Number of digits after the decimal separator.

  • For CentPrecisionMoney, it is equal to the default number of fraction digits for a currency.
  • For HighPrecisionMoney, it is greater than the default number of fraction digits for a currency.
Maximum: 20

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"

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.

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"

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.

Base polymorphic money type containing common fields for Money and HighPrecisionMoneyDraft.

centAmount
Int

Amount in the smallest indivisible unit of a currency.

currencyCode

Currency code compliant to ISO 4217.

type

Determines the type of money used.

fractionDigits
Int

Number of fraction digits for a specified money.

Maximum: 20

Money

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

Draft type that stores amounts only in cent precision for 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.

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

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 API calculates the value automatically using the default rounding mode half even.

currencyCode

Currency code compliant to ISO 4217.

type
String
"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:

preciseAmountfractionDigitsAmount in currency
1234563123.456
12345651.23456
12345670.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

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

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

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: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
externalId
String

ID for the contact used in an external system.

country

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

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

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: 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 identifier for the Asset. Must be unique per Category or ProductVariant.

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 identifier of the AssetSource. Must be unique per Asset.

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 API Client which created the resource.

externalUserId
String

External user ID provided by X-External-User-ID HTTP Header or external_user_id:{externalUserId} scope.

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.

associate

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.

LastModifiedBy BETA

Present on resources modified 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 X-External-User-ID HTTP Header or external_user_id:{externalUserId} scope.

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.

associate

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.