Common API Types used within multiple API resources.
References
Reference
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. |
{
"typeId": "product",
"id": "d1229e6f-2b79-441e-b419-180311e52754"
}
KeyReference
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 | Type of referenced resource. |
ResourceIdentifier
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.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. Only available for B2B-enabled Projects.
approval-rule
- References an ApprovalRule. Only available for B2B-enabled Projects.
associate-role
- References an AssociateRole. Only available for B2B-enabled Projects.
attribute-group
- References an AttributeGroup.
business-unit
- References a BusinessUnit. Only available for B2B-enabled Projects.
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
Price
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 | 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 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 | 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
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 value of this Price. To set the money value in high precision, use HighPrecisionMoneyDraft. |
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 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 | 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
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
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 .
To set the money value in high precision, use HighPrecisionMoneyDraft.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. To set the money value in high precision, use HighPrecisionMoneyDraft. |
discount | Relates the referenced ProductDiscount to the discounted price. |
Moneys
TypedMoney
CentPrecisionMoney
Object that stores money in cent amounts of a specific currency.
centAmount Int | Amount in the smallest indivisible unit of a currency, such as:
|
currencyCode | Currency code compliant to ISO 4217. DisplayName: CurrencyCode |
type | centPrecision Type of money used. |
fractionDigits Int | The number of default fraction digits for the given currency, like Maximum: 2 for EUR or 0 for JPY.3 |
{
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 4200,
"fractionDigits": 2
}
HighPrecisionMoney
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:
|
currencyCode | Currency code compliant to ISO 4217. DisplayName: CurrencyCode |
type | highPrecision Type of money used. |
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. |
{
"type": "highPrecision",
"currencyCode": "EUR",
"centAmount": 1,
"preciseAmount": 123456,
"fractionDigits": 7
}
TypedMoneyDraft
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
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:
|
currencyCode | Currency code compliant to ISO 4217. DisplayName: CurrencyCode |
{
"currencyCode": "EUR",
"centAmount": 4200
}
HighPrecisionMoneyDraft
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 | Currency code compliant to ISO 4217. DisplayName: CurrencyCode |
type | highPrecision Determines the type of money used. |
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. |
{
"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
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.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.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.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.fractionDigits
affect a preciseAmount
:preciseAmount | fractionDigits | Amount in currency |
---|---|---|
123456 | 3 | 123.456 |
123456 | 5 | 1.23456 |
123456 | 7 | 0.0123456 |
centAmount
and preciseAmount
are represented as 64-bit integers.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.Date and Time
Date
Date
is a JSON string representation of a date without timezone in ISO 8601 format (YYYY-MM-DD), for example:"2018-10-12"
Time
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
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
en
, en-US
, zh-Hans-SG
.LocalizedString
{
"de": "Hundefutter",
"en": "dog food"
}
GeoJSON Geometry
Point
type String | "Point" |
coordinates Array of Number |
{
"type": "Point",
"coordinates": [
13.412119019109015,
52.50103330534661
]
}
Addresses
BaseAddress
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 MinLength: itemShippingAddresses (LineItem-specific addresses) of a Cart, Order, QuoteRequest, or Quote.2 MaxLength: 256 Pattern: ^[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
custom
field can be present in addition to the fields of a BaseAddress.custom | Custom Fields defined for the Address. |
AddressDraft
custom
field in addition to the fields of a BaseAddress.custom | Custom Fields defined for the Address. |
{
"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
You can 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 | 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: 2 MaxLength: 256 Pattern: ^[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
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 | 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
CreatedBy BETA
clientId String | id of the API Client which created the resource. |
externalUserId String | External user ID provided by the MaxLength: X-External-User-ID HTTP Header or external_user_id:{externalUserId} scope.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 available for B2B-enabled Project when an Associate acts on behalf of a company using the associate endpoints. |
attributedTo | Indicates if the resource was created indirectly. |
LastModifiedBy BETA
clientId String | id of the API Client which modified the resource. |
externalUserId String | External user ID provided by the MaxLength: X-External-User-ID HTTP Header or external_user_id:{externalUserId} scope.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 available for B2B-enabled Projects when an Associate acts on behalf of a company using the associate endpoints. |
attributedTo | 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 | 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
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." |
{
"code": "ImageProcessingOngoing",
"message": "The image processing is still ongoing."
}