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.idString | 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.keyString | User-defined unique and immutable key of the referenced resource. MinLength:2MaxLength: 256Pattern: ^[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.idString | Unique identifier of the referenced resource. Required if key is absent. |
keyString | 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.
discount-group- References a DiscountGroup.
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-method- References a PaymentMethod.
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.
recurrence-policy- References a RecurrencePolicy.
recurring-order- References a RecurringOrder.
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.idString | Unique identifier of this Price. |
keyString | 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.If an absolute discount value exceeds the price of the Product Variant, the discounted price is a negative value. |
tiersArray 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. |
recurrencePolicy | Recurrence Policy for which this Price is valid. |
custom | Custom Fields defined for the Price. |
PriceDraft
Embedded. For the Standalone ProductPriceMode use StandalonePriceDraft.keyString | 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. 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 | 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:
|
tiersArray 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. |
recurrencePolicy | RecurrencePolicy for which this Price is valid. |
custom | Custom Fields for the Price. |
PriceKeyReference
keyString | User-defined unique identifier of the referenced Embedded Price. |
typeId | priceType of referenced resource. |
PriceTier
minimumQuantityInt | 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
minimumQuantityInt | 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.
centAmountInt | Amount in the smallest indivisible unit of a currency, such as:
|
currencyCode | Currency code compliant to ISO 4217. |
type | centPrecisionType of money used. |
fractionDigitsInt | 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.
centAmountInt | Amount in the smallest indivisible unit of a currency, such as:
|
currencyCode | Currency code compliant to ISO 4217. |
type | highPrecisionType of money used. |
fractionDigitsInt | Number of digits after the decimal separator, greater than the default number of fraction digits for a currency. Maximum:20 |
preciseAmountInt | 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.
centAmountInt | Amount in the smallest indivisible unit of a currency, such as:
|
currencyCode | Currency code compliant to ISO 4217. |
{
"currencyCode": "EUR",
"centAmount": 4200
}HighPrecisionMoneyDraft
Draft object to store money as a fraction of the smallest indivisible unit for a specific currency.
centAmountInt | 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 | highPrecisionDetermines the type of money used. |
fractionDigitsInt | 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 |
preciseAmountInt | Amount in 1 / (10 ^ fractionDigits) of a currency. |
{
"type": "highPrecision",
"currencyCode": "EUR",
"preciseAmount": 123456,
"fractionDigits": 7
}MoneyType
Determines the type of money used.
centPrecisionUse to set currency in cent precision.
highPrecisionUse 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
typeString | "Point" |
coordinatesArray of Number |
{
"type": "Point",
"coordinates": [
13.412119019109015,
52.50103330534661
]
}Addresses
BaseAddress
custom field.idString | 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. |
keyString | 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.2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$ |
externalIdString | ID for the contact used in an external system. |
country | Name of the country. |
titleString | Title of the contact, for example 'Dr.' |
salutationString | Salutation of the contact, for example 'Mr.' or 'Ms.' |
firstNameString | Given name (first name) of the contact. |
lastNameString | Family name (last name) of the contact. |
streetNameString | Name of the street. |
streetNumberString | Street number. |
additionalStreetInfoString | Further information on the street address. |
postalCodeString | Postal code. |
cityString | Name of the city. |
regionString | Name of the region. |
stateString | Name of the state, for example, Colorado. |
companyString | Name of the company. |
departmentString | Name of the department. |
buildingString | Number or name of the building. |
apartmentString | Number or name of the apartment. |
pOBoxString | Post office box number. |
phoneString | Phone number of the contact. |
mobileString | Mobile phone number of the contact. |
emailString | Email address of the contact. |
faxString | Fax number of the contact. |
additionalAddressInfoString | 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
idString | Unique identifier of the Asset. Not required when importing Assets using the Import API. |
keyString | User-defined identifier of the Asset. It is unique per Category or ProductVariant. MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$ |
sourcesArray of AssetSource | MinItems: 1 |
name | Name of the Asset. |
description | Description of the Asset. |
tagsArray of String | Keywords for categorizing and organizing Assets. |
custom | Custom Fields defined for the Asset. |
AssetDraft
keyString | User-defined identifier for the Asset. Must be unique per Category or ProductVariant. MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$ |
sourcesArray of AssetSource | MinItems: 1 |
name | Name of the Asset. |
description | Description of the Asset. |
tagsArray of String | Keywords for categorizing and organizing Assets. |
custom | Custom Fields defined for the Asset. |
AssetSource
keyString | User-defined identifier of the AssetSource. Must be unique per Asset. MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$ |
uriString | URI of the AssetSource. |
dimensions | Width and height of the AssetSource. |
contentTypeString | Indicates the type of content, for example application/pdf. |
AssetDimensions
Dimensions of the Asset source specified by the number of pixels.
wInt | Width of the Asset source. |
hInt | Height of the Asset source. |
Client logging
CreatedBy BETA
clientIdString | id of the API Client which created the resource. |
externalUserIdString | 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. |
anonymousIdString | 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
clientIdString | id of the API Client which modified the resource. |
externalUserIdString | 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. |
anonymousIdString | 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.
clientIdString | 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
ImportResource was created or updated during import.
ExportResource was created or updated during export.
Warnings
WarningObject
Represents a warning related to the returned response.
codeString | Identifier for the type of warning. |
messageString | 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.codeString | "ImageProcessingOngoing" |
messageString | "The image processing is still ongoing." |
{
"code": "ImageProcessingOngoing",
"message": "The image processing is still ongoing."
}