Sitecore CDP Order REST API (v2.1)

Use the Order REST API to create, retrieve, update, and delete order data in Sitecore CDP.

This REST API lets you interact with the following objects:

  • Order - the parent for all other objects, containing attributes common to the entire order.
  • Order item - something that has been purchased as part of the order.
  • Order contact - the primary contact person for an order.
  • Order consumer - the person that consumes the order item.
  • Order data extension - any key-value pairs you want to add to the order object.
  • Order item data extension - any key-value pairs you want to add to the order item object.

Note the following:

  • To use this REST API, you must authenticate your API requests.
  • All API requests are made in your production environment.
  • This reference documentation describes Sitecore CDP functionality for data model 2.1.

For more information, see the official Sitecore CDP developer documentation, including examples of order items and order item data extensions.

Authentication

The Order REST API uses basic authentication. Basic authentication involves sending a user name and a password with every request. To find your user name and password, in Sitecore CDP, on the navigation pane, click Settings > API access:

  • The user name is the Client key.
  • The password is the API token.

You must include the user name and password in every request you make. For example:

curl -X GET '{baseURL}/v2.1/orders' \ 
-u '{YOUR_USERNAME}:{YOUR_PASSWORD}' \ 
-H 'Accept: application/json' 

Get started

To create your first order and find it in Sitecore CDP:

  1. Create an order. The response contains the order reference.
  2. Create an order contact using the order reference. Make sure to provide enough identity information according to your organization's identity rules. This associates a guest with the order. In the response, in guest.href, the guest reference is the string that follows the final slash.
  3. Copy the guest reference.
  4. In Sitecore CDP, click Guests. In the Search field, enter the guest reference, then click the Guest type: All filter. Then, Sitecore CDP lists the guest profile for the guest.
  5. On the Guest Profile page, click the Orders tab. The order you previously created displays.
Download OpenAPI description
Overview
License Apache 2.0
Languages
Servers
Production server AP
https://api-engage-ap.sitecorecloud.io/
Production server EU
https://api-engage-eu.sitecorecloud.io/
Production server JP
https://api-engage-jpe.sitecorecloud.io/
Production server US
https://api-engage-us.sitecorecloud.io/

Order

An order object is the parent for all other objects and contains attributes that are common to the entire order. The Order REST API matches orders that have the same referenceId values and have orderedAt values (purchase dates) within two days of another.

Operations

Order item

The order item object represents something that has been purchased as part of the order. For an airline reservation, an order item is typically one or more flight segments, or an ancillary item purchased in addition to the flight, such as excess baggage allowance or priority boarding.

Operations

Create an order item

Request

Creates an order item on an order.

In the response, ref contains the order item reference. Use the order item reference to interact with a specific order item, for example, to retrieve it, update it, or create a data extension for it.

Path
orderRefstringrequired

The order reference. This is a unique identifier of the order record. Automatically generated when you created the order. If you don't know the order reference, first list orders.

Example: 2d7de9df-45a2-45ea-872c-30e45139007d
Bodyapplication/json
currencyCodestringrequired

The organization's currency code for the order item.

Example: "EUR"
namestringrequired

The name of the order item. Free text value. Maximum character limit: 128

Example: "Mobile AZ10"
pricenumberrequired

The organization's price for the order item.

Example: 105
statusstringrequired

The status of the order item.

Example: "CONFIRMED"
typestringrequired

The type of order item. Must not be set to any of the following: "FLIGHT", "HOTEL", "MORTGAGE", "MORTGAGE_APPLICATION", "LOAN_APPLICATION", "PERSONAL_LOAN", "RAIL"

Example: "MOBILE"
descriptionstring

The description of the order item.

Example: "Mobile AZ10 description"
productIdstring

The ID of the product.

Example: "1233-44"
originalPricenumber

The unit price of the order item before conversion to the organization's currency.

Example: 110
originalCurrencyCodestring

The original currency code for the order item.

Example: "USD"
referenceIdstring

An ID generated by the client to reference the order item.

Example: "AAAAA-134"
vendorstring

The organization that is selling the order item.

Example: "Vendor XYZ"
languagestring

The language used when making the order.

Example: "EN"
quantityinteger(int32)

The number or quantity of the order item.

Example: 1
channelstring

The channel used in the order.

Example: "WEB"
curl -i -X POST \
  -u <username>:<password> \
  'https://api-engage-ap.sitecorecloud.io/v2.1/orders/{orderRef}/orderItems' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Mobile AZ10",
    "description": "Mobile AZ10 description",
    "type": "MOBILE",
    "productId": "1233-44",
    "price": 105,
    "currencyCode": "EUR",
    "originalPrice": 110,
    "originalCurrencyCode": "USD",
    "referenceId": "AAAAA-134",
    "vendor": "Vendor XYZ",
    "status": "CONFIRMED",
    "language": "EN",
    "quantity": 1,
    "channel": "WEB"
  }'

Responses

Resource successfully created

Bodyapplication/json
refstring(UUID)

The order item reference. This is a unique identifier of the order item. Use the order item reference to interact with a specific order item, for example, to retrieve it, update it, or create a data extension for it.

Example: "2d7de9df-45a2-45ea-872c-30e45139007d"
hrefstring

The link to the order item.

Example: "https://api-engage-eu.sitecorecloud.io/v2.1/orderItems/2d7de9df-45a2-45ea-872c-30e45139007d"
namestring

The name of the order item. Free text value. Maximum character limit: 128

Example: "Mobile AZ10"
descriptionstring

The description of the order item.

Example: "Mobile AZ10 description"
createdAtstring(date-time)

The date and time when the resource was created in Sitecore CDP.

Example: "2024-01-01T16:17:16Z"
modifiedAtstring(date-time)

The date and time when the resource was updated in Sitecore CDP.

Example: "2024-01-01T16:17:16Z"
orderedAtstring(date-time)

The date and time when the order item was made.

Example: "2024-01-01T16:17:16Z"
typestring

The type of order item.

Example: "MOBILE"
productIdstring

The ID of the product.

Example: "1233-44"
pricenumber

The organization's price for the order item.

Example: 105
currencyCodestring

The organization's currency code for the order item.

Example: "EUR"
originalPricenumber

The unit price of the order item before conversion to the organization's currency.

Example: 110
originalCurrencyCodestring

The original currency code for the order item.

Example: "USD"
referenceIdstring

An ID generated by the client to reference the order item.

Example: "AAAAA-134"
vendorstring

The organization that is selling the order item.

Example: "Vendor XYZ"
statusstring

The status of the order item.

Example: "CONFIRMED"
languagestring

The language used when making the order.

Example: "EN"
quantityinteger(int32)

The number or quantity of the order item.

Example: 1
channelstring

The channel used in the order.

Example: "WEB"
orderobject(OrderLinkFirst)

The request's first list of orders URL.

Response
application/json
{ "ref": "2d7de9df-45a2-45ea-872c-30e45139007d", "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orderItems/2d7de9df-45a2-45ea-872c-30e45139007d", "name": "Mobile AZ10", "description": "Mobile AZ10 description", "createdAt": "2024-01-01T16:17:16Z", "modifiedAt": "2024-01-01T16:17:16Z", "orderedAt": "2024-01-01T16:17:16Z", "type": "MOBILE", "productId": "1233-44", "price": 105, "currencyCode": "EUR", "originalPrice": 110, "originalCurrencyCode": "USD", "referenceId": "AAAAA-134", "vendor": "Vendor XYZ", "status": "CONFIRMED", "language": "EN", "quantity": 1, "channel": "WEB", "order": { "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orders?guestRef=2d7de9df-45a2-45ea-872c-30e45139007d&offset=1&limit=10" } }

List order items for an order

Request

Retrieves a list of order items for an order.

In the response, items.ref contains the order item reference. Use the order item reference to interact with a specific order item, for example, to retrieve or update it.

Path
orderRefstringrequired

The order reference. This is a unique identifier of the order record. Automatically generated when you created the order. If you don't know the order reference, first list orders.

Example: 2d7de9df-45a2-45ea-872c-30e45139007d
Query
expandArray of strings

You can expand items in a collection by setting expand=true. This eliminates the need to send multiple follow-up requests (one for the collection and another for each of its items). This also helps you check if the data you intend to create already exists.

Example: expand=true
offsetobject(Offset)

Collection responses use offset pagination. The offset query parameter is used to exclude from a response the first N items of the entire resource collection.

Default "0"
Example: offset=0
limitobject(Limit)[ 10 .. 100 ]

Collection responses use offset pagination. This query parameter lets you adjust the maximum number of collection items to return for a single request.

Default "10"
Example: limit=40
curl -i -X GET \
  -u <username>:<password> \
  'https://api-engage-ap.sitecorecloud.io/v2.1/orders/{orderRef}/orderItems?expand=true&limit=40&offset=0'

Responses

Successful operation

Bodyapplication/json
offsetinteger(int32)

The request's offset.

Example: 0
limitinteger(int32)

The request's limit.

Example: 10
firstobject(OrderItemLinkFirst)

The request's first list of order items URL.

lastobject(OrderItemLinkLast)

The request's last list of order items URL.

nextobject(OrderItemNext)

The request's next list of order items URL.

hrefstring

The request's URL.

Example: "https://api-engage-eu.sitecorecloud.io/v2.1/orders/cadd106a-feff-42b2-90fb-a6ed136ece51/orderItems?offset=0&limit=10"
itemsArray of objects(items)
Response
application/json
{ "offset": 0, "limit": 10, "first": { "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orderItems/111d106a-feff-42b2-90fb-a6ed136ec333" }, "last": { "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orderItems/111d106a-feff-42b2-90fb-a6ed136ec333" }, "next": { "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orders/111d106a-feff-42b2-90fb-a6ed136ec333/orderItems?offset=1&limit=10" }, "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orders/cadd106a-feff-42b2-90fb-a6ed136ece51/orderItems?offset=0&limit=10", "items": [ { … } ] }

Retrieve an order item

Request

Retrieves an order item.

Path
orderItemRefstring(UUID)required

The order item reference. This is a unique identifier of the order item. Automatically generated when you created the order item. If you don't know the order item reference, first list order items.

Example: 2d7de9df-45a2-45ea-872c-30e45139007d
Query
expandArray of strings

You can expand items in a collection by setting expand=true. This eliminates the need to send multiple follow-up requests (one for the collection and another for each of its items). This also helps you check if the data you intend to create already exists.

Example: expand=true
curl -i -X GET \
  -u <username>:<password> \
  'https://api-engage-ap.sitecorecloud.io/v2.1/orderItems/{orderItemRef}?expand=true'

Responses

Resource successfully created

Bodyapplication/json
refstring(UUID)

The order item reference. This is a unique identifier of the order item. Use the order item reference to interact with a specific order item, for example, to retrieve it, update it, or create a data extension for it.

Example: "2d7de9df-45a2-45ea-872c-30e45139007d"
hrefstring

The link to the order item.

Example: "https://api-engage-eu.sitecorecloud.io/v2.1/orderItems/2d7de9df-45a2-45ea-872c-30e45139007d"
namestring

The name of the order item. Free text value. Maximum character limit: 128

Example: "Mobile AZ10"
descriptionstring

The description of the order item.

Example: "Mobile AZ10 description"
createdAtstring(date-time)

The date and time when the resource was created in Sitecore CDP.

Example: "2024-01-01T16:17:16Z"
modifiedAtstring(date-time)

The date and time when the resource was updated in Sitecore CDP.

Example: "2024-01-01T16:17:16Z"
orderedAtstring(date-time)

The date and time when the order item was made.

Example: "2024-01-01T16:17:16Z"
typestring

The type of order item.

Example: "MOBILE"
productIdstring

The ID of the product.

Example: "1233-44"
pricenumber

The organization's price for the order item.

Example: 105
currencyCodestring

The organization's currency code for the order item.

Example: "EUR"
originalPricenumber

The unit price of the order item before conversion to the organization's currency.

Example: 110
originalCurrencyCodestring

The original currency code for the order item.

Example: "USD"
referenceIdstring

An ID generated by the client to reference the order item.

Example: "AAAAA-134"
vendorstring

The organization that is selling the order item.

Example: "Vendor XYZ"
statusstring

The status of the order item.

Example: "CONFIRMED"
languagestring

The language used when making the order.

Example: "EN"
quantityinteger(int32)

The number or quantity of the order item.

Example: 1
channelstring

The channel used in the order.

Example: "WEB"
orderobject(OrderLinkFirst)

The request's first list of orders URL.

Response