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:

Create an order. The response contains the order reference.
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.
Copy the guest reference.
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.
On the Guest Profile page, click the Orders tab. The order you previously created displays.

Download OpenAPI description

index.json

index.yaml

Overview

License Apache 2.0

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

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)

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

Sitecore CDP Order REST API (v2.1)

Authentication

Get started

Order

Order item

Create an order item

Request

Responses

Was this helpful?

List order items for an order

Request

Responses

Was this helpful?

Retrieve an order item

Request

Responses