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

Order contact

An order contact is a person who is the primary contact for an order. The same guest can be both the order contact and order consumer.

Operations

Order consumer

An order consumer represents a person who is consuming an order item. If the order item is a flight, the order consumer is the traveler or passenger of the flight segment. If more than one order consumer is consuming the same order item, the order item has a quantity representing the number of order consumers.

The same guest can be both the order contact and order consumer.

Operations

Order data extension

An order data extension is an object that lets you specify any key-value pairs you want. Order data extensions are optional and enable your organization to capture more robust information about your orders.

To get started with this API, create a data extension for the order you previously created.

Operations

Create an order data extension

Request

Creates an order data extension.

To avoid creating key-value pairs that already exist in the data extension for an order, first retrieve all the data extensions for an order to check that the keys you intend to create are unique.

Creating the request body

In the request body, you must provide one object. This object represents the data extension. Note the following about the object:

Can contain primitive values only. You cannot nest objects. If you need to group key-value pairs, use prefixes for the key names.
Can contain a maximum of 100 key-value pairs.
The key-value pairs you include in the object become the extension data. For example, if you include "firstTimeOrder": true in the object, First Time Order with the value of true becomes extension data.
Supported data types for the values:
- string, for example "level2"
- boolean, for example true
- integer, for example 9
- floating-point number, for example 99.9

Naming keys

The keys you enter in the request body must be:

Alphanumeric [A-Z,a-z,0-9] as per the JSON RFC 7159 specification.
In camel case.

Example request body

Here's an example request body:

{ 
"firstTimeOrder": true, 
"storeLocation": "London", 
"totalUnits": 8, 
"totalDiscount": "20%"
}

This creates four key-value pairs for the order.

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

dataExtensionNamestringrequired

The data extension name. You must set this to ext.

Example: ext

Bodyapplication/json

{exampleKey1}string or boolean or integer or number

A key-value pair of your choice. Supported data types for the values: string, boolean, integer, floating-point number. Example: "firstTimeOrder": true

Example: "{exampleValue1}"

{exampleKey2}string or boolean or integer or number

A key-value pair of your choice. Supported data types for the values: string, boolean, integer, floating-point number. Example:"storeLocation": "London"

Example: "{exampleValue2}"

curl -i -X POST \
  -u <username>:<password> \
  'https://api-engage-ap.sitecorecloud.io/v2.1/orders/{orderRef}/extensions/{dataExtensionName}' \
  -H 'Content-Type: application/json' \
  -d '{
    "{exampleKey1}": "{exampleValue1}",
    "{exampleKey2}": "{exampleValue2}"
  }'

Responses

Resource successfully created

Bodyapplication/json

namestring

The name of the data extension.

Example: "ext"

hrefstring

The URL of the order extension.

Example: "https://api-engage-eu.sitecorecloud.io/v2.1/orders/f7aabbca-1c1b-4fc2-be72-3e16294a4f03/extensions/ext"

refstring

The order extension reference.

Example: "6a5cb3c2-1a4a-56d8-8a01-1ede232b9db2"

keystring

The value "default".

Example: "default"

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 last updated in Sitecore CDP.

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

{exampleKey1}string or boolean or integer or number

A key-value pair of your choice. Supported data types for the values: string, boolean, integer, floating-point number. Example: "firstTimeOrder": true

Example: "{exampleValue1}"

{exampleKey2}string or boolean or integer or number

A key-value pair of your choice. Supported data types for the values: string, boolean, integer, floating-point number. Example:"storeLocation": "London"

Example: "{exampleValue2}"

orderobject(OrderLinkFirst)

The request's first list of orders URL.

Response

application/json

{
  "name": "ext",
  "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orders/f7aabbca-1c1b-4fc2-be72-3e16294a4f03/extensions/ext",
  "ref": "6a5cb3c2-1a4a-56d8-8a01-1ede232b9db2",
  "key": "default",
  "createdAt": "2024-01-01T16:17:16Z",
  "modifiedAt": "2024-01-01T16:17:16Z",
  "{exampleKey1}": "{exampleValue1}",
  "{exampleKey2}": "{exampleValue2}",
  "order": {
    "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orders?guestRef=2d7de9df-45a2-45ea-872c-30e45139007d&offset=1&limit=10"
  }
}

Retrieve an order data extension

Request

Retrieves a data extension for an order.

Path

orderRefstringrequired

The order reference. This is a unique identifier of the order record. If you don't know the order reference, first retrieve orders.

Example: f7aabbca-1c1b-4fc2-be72-3e16294a4f03

dataExtensionNamestringrequired

The name of the data extension. Set this to ext.

Example: ext

curl -i -X GET \
  -u <username>:<password> \
  'https://api-engage-ap.sitecorecloud.io/v2.1/orders/{orderRef}/extensions/{dataExtensionName}'

Responses

Resource successfully retrieved.

Bodyapplication/json

namestring

The name of the data extension.

Example: "ext"

hrefstring

The URL of the order extension.

Example: "https://api-engage-eu.sitecorecloud.io/v2.1/orders/f7aabbca-1c1b-4fc2-be72-3e16294a4f03/extensions/ext"

refstring

The order extension reference.

Example: "6a5cb3c2-1a4a-56d8-8a01-1ede232b9db2"

keystring

The value "default".

Example: "default"

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 last updated in Sitecore CDP.

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

{exampleKey1}string or boolean or integer or number

A key-value pair of your choice. Supported data types for the values: string, boolean, integer, floating-point number. Example: "firstTimeOrder": true

Example: "{exampleValue1}"

{exampleKey2}string or boolean or integer or number

A key-value pair of your choice. Supported data types for the values: string, boolean, integer, floating-point number. Example:"storeLocation": "London"

Example: "{exampleValue2}"

orderobject(OrderLinkFirst)

The request's first list of orders URL.

Response

application/json

{
  "name": "ext",
  "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orders/f7aabbca-1c1b-4fc2-be72-3e16294a4f03/extensions/ext",
  "ref": "6a5cb3c2-1a4a-56d8-8a01-1ede232b9db2",
  "key": "default",
  "createdAt": "2024-01-01T16:17:16Z",
  "modifiedAt": "2024-01-01T16:17:16Z",
  "{exampleKey1}": "{exampleValue1}",
  "{exampleKey2}": "{exampleValue2}",
  "order": {
    "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orders?guestRef=2d7de9df-45a2-45ea-872c-30e45139007d&offset=1&limit=10"
  }
}

Update an order data extension

Request

Fully updates a data extension for an order, replacing the entire resource including all the key-value pairs with the data you send in the request.

To update certain key-value pairs only, use the Partially update a data extension endpoint instead.

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

dataExtensionNamestringrequired

The name of the data extension. Set this to ext.

Example: ext

Bodyapplication/json

{exampleKey1}string or boolean or integer or number

A key-value pair of your choice. Supported data types for the values: string, boolean, integer, floating-point number. Example: "firstTimeOrder": true

Example: "{exampleValue1}"

{exampleKey2}string or boolean or integer or number

A key-value pair of your choice. Supported data types for the values: string, boolean, integer, floating-point number. Example:"storeLocation": "London"

Example: "{exampleValue2}"

curl -i -X PUT \
  -u <username>:<password> \
  'https://api-engage-ap.sitecorecloud.io/v2.1/orders/{orderRef}/extensions/{dataExtensionName}' \
  -H 'Content-Type: application/json' \
  -d '{
    "{exampleKey1}": "{exampleValue1}",
    "{exampleKey2}": "{exampleValue2}"
  }'

Responses

Successful operation

Bodyapplication/json

namestring

The name of the data extension.

Example: "ext"

hrefstring

The URL of the order extension.

Example: "https://api-engage-eu.sitecorecloud.io/v2.1/orders/f7aabbca-1c1b-4fc2-be72-3e16294a4f03/extensions/ext"

refstring

The order extension reference.

Example: "6a5cb3c2-1a4a-56d8-8a01-1ede232b9db2"

keystring

The value "default".

Example: "default"

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 last updated in Sitecore CDP.

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

{exampleKey1}string or boolean or integer or number

A key-value pair of your choice. Supported data types for the values: string, boolean, integer, floating-point number. Example: "firstTimeOrder": true

Example: "{exampleValue1}"

{exampleKey2}string or boolean or integer or number

A key-value pair of your choice. Supported data types for the values: string, boolean, integer, floating-point number. Example:"storeLocation": "London"

Example: "{exampleValue2}"

orderobject(OrderLinkFirst)

The request's first list of orders URL.

Response

application/json

{
  "name": "ext",
  "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orders/f7aabbca-1c1b-4fc2-be72-3e16294a4f03/extensions/ext",
  "ref": "6a5cb3c2-1a4a-56d8-8a01-1ede232b9db2",
  "key": "default",
  "createdAt": "2024-01-01T16:17:16Z",
  "modifiedAt": "2024-01-01T16:17:16Z",
  "{exampleKey1}": "{exampleValue1}",
  "{exampleKey2}": "{exampleValue2}",
  "order": {
    "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orders?guestRef=2d7de9df-45a2-45ea-872c-30e45139007d&offset=1&limit=10"
  }
}

Partially update an order data extension

Request

Partially updates a data extension for an order, replacing only those key-value pairs in the resource that you provide in the request.

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

dataExtensionNamestringrequired

The name of the data extension. Set this to ext.

Example: ext

Bodyapplication/json

{exampleKey1}string or boolean or integer or number

A key-value pair of your choice. Supported data types for the values: string, boolean, integer, floating-point number. Example: "firstTimeOrder": true

Example: "{exampleValue1}"

{exampleKey2}string or boolean or integer or number

A key-value pair of your choice. Supported data types for the values: string, boolean, integer, floating-point number. Example:"storeLocation": "London"

Example: "{exampleValue2}"

curl -i -X PATCH \
  -u <username>:<password> \
  'https://api-engage-ap.sitecorecloud.io/v2.1/orders/{orderRef}/extensions/{dataExtensionName}' \
  -H 'Content-Type: application/json' \
  -d '{
    "{exampleKey1}": "{exampleValue1}",
    "{exampleKey2}": "{exampleValue2}"
  }'

Responses

Successful operation

Bodyapplication/json

namestring

The name of the data extension.

Example: "ext"

hrefstring

The URL of the order extension.

Example: "https://api-engage-eu.sitecorecloud.io/v2.1/orders/f7aabbca-1c1b-4fc2-be72-3e16294a4f03/extensions/ext"

refstring

The order extension reference.

Example: "6a5cb3c2-1a4a-56d8-8a01-1ede232b9db2"

keystring

The value "default".

Example: "default"

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 last updated in Sitecore CDP.

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

{exampleKey1}string or boolean or integer or number

A key-value pair of your choice. Supported data types for the values: string, boolean, integer, floating-point number. Example: "firstTimeOrder": true

Example: "{exampleValue1}"

{exampleKey2}string or boolean or integer or number

A key-value pair of your choice. Supported data types for the values: string, boolean, integer, floating-point number. Example:"storeLocation": "London"

Example: "{exampleValue2}"

orderobject(OrderLinkFirst)

The request's first list of orders URL.

Response

application/json

{
  "name": "ext",
  "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orders/f7aabbca-1c1b-4fc2-be72-3e16294a4f03/extensions/ext",
  "ref": "6a5cb3c2-1a4a-56d8-8a01-1ede232b9db2",
  "key": "default",
  "createdAt": "2024-01-01T16:17:16Z",
  "modifiedAt": "2024-01-01T16:17:16Z",
  "{exampleKey1}": "{exampleValue1}",
  "{exampleKey2}": "{exampleValue2}",
  "order": {
    "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orders?guestRef=2d7de9df-45a2-45ea-872c-30e45139007d&offset=1&limit=10"
  }
}

Delete an order data extension

Request

Deletes the data extension for an order, including all the key-value pairs in the data extension.

To delete certain key-value pairs only, use the Delete key-value pairs from a data extension endpoint instead.

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

dataExtensionNamestringrequired

The name of the data extension. Set this to ext.

Example: ext

curl -i -X DELETE \
  -u <username>:<password> \
  'https://api-engage-ap.sitecorecloud.io/v2.1/orders/{orderRef}/extensions/{dataExtensionName}'

Responses

Successful operation

Bodyapplication/json

Response

application/json

null

Delete key-value pairs from an order data extension

Request

Deletes the key-value pairs you provide in the name query parameter from a data extension for an order.

For example, if your data extension contains the firstTimeOrder and storeLocation keys, you can delete both keys and their values by making the following request:

{baseURL}/v2.1/orders/{orderRef}/extensions/{dataExtensionName}/fields?name=firstTimeOrder|storeLocation

If you don't provide the query parameter, this operation will empty the data extension: the data extension itself will not be deleted, but all the key-value pairs in it will.

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

dataExtensionNamestringrequired

The name of the data extension. Set this to ext.

Example: ext

Query

nameArray of strings

The fields in the data extension object that you want to delete.

Example: name=withWarranty|color

curl -i -X DELETE \
  -u <username>:<password> \
  'https://api-engage-ap.sitecorecloud.io/v2.1/orders/{orderRef}/extensions/{dataExtensionName}/fields?name=withWarranty%2Ccolor'

Responses

Successful operation

Bodyapplication/json

namestring

The name of the data extension.

Example: "ext"

hrefstring

The URL of the order extension.

Example: "https://api-engage-eu.sitecorecloud.io/v2.1/orders/f7aabbca-1c1b-4fc2-be72-3e16294a4f03/extensions/ext"

refstring

The order extension reference.

Example: "6a5cb3c2-1a4a-56d8-8a01-1ede232b9db2"

keystring

The value "default".

Example: "default"

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 last updated in Sitecore CDP.

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

{exampleKey1}string or boolean or integer or number

A key-value pair of your choice. Supported data types for the values: string, boolean, integer, floating-point number. Example: "firstTimeOrder": true

Example: "{exampleValue1}"

{exampleKey2}string or boolean or integer or number

A key-value pair of your choice. Supported data types for the values: string, boolean, integer, floating-point number. Example:"storeLocation": "London"

Example: "{exampleValue2}"

orderobject(OrderLinkFirst)

The request's first list of orders URL.

Response

application/json

{
  "name": "ext",
  "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orders/f7aabbca-1c1b-4fc2-be72-3e16294a4f03/extensions/ext",
  "ref": "6a5cb3c2-1a4a-56d8-8a01-1ede232b9db2",
  "key": "default",
  "createdAt": "2024-01-01T16:17:16Z",
  "modifiedAt": "2024-01-01T16:17:16Z",
  "{exampleKey1}": "{exampleValue1}",
  "{exampleKey2}": "{exampleValue2}",
  "order": {
    "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orders?guestRef=2d7de9df-45a2-45ea-872c-30e45139007d&offset=1&limit=10"
  }
}

Retrieve the URL for an order's data extension

Request

Retrieves the URL for the order's data extension. This lets you check if the data extension exists.

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}/extensions?expand=true&limit=40&offset=0'

Responses

Successful operation

Bodyapplication/json

namestring

The name of the data extension.

Example: "ext"

offsetinteger(int32)

The request's offset.

Example: 0

limitinteger(int32)

The request's limit.

Example: 10

firstobject(OrderDataExtensionFirstLink)

The request's first list of order data extensions URL.

lastobject(OrderDataExtensionLastLink)

The request's last list of order data extensions URL.

nextobject(OrderDataExtensionNextLink)

The request's next list of order data extensions URL.

hrefstring

The request's URL.

Example: "https://api-engage-eu.sitecorecloud.io/v2.1/orders/cadd106a-feff-42b2-90fb-a6ed136ece51/extensions/ext"

itemsArray of objects(OrderDataExtensionLink)

The request's data extension items.

orderobject(OrderHref)

Response

application/json

{
  "name": "ext",
  "offset": 0,
  "limit": 10,
  "first": {
    "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orders/cadd106a-feff-42b2-90fb-a6ed136ece51/extensions"
  },
  "last": {
    "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orders/cadd106a-feff-42b2-90fb-a6ed136ece51/extensions"
  },
  "next": {
    "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orders/cadd106a-feff-42b2-90fb-a6ed136ece51/extensions"
  },
  "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orders/cadd106a-feff-42b2-90fb-a6ed136ece51/extensions/ext",
  "items": [
    { … }
  ],
  "order": {
    "href": "https://api-engage-eu.sitecorecloud.io/v2.1/orders/cadd106a-feff-42b2-90fb-a6ed136ece51"
  }
}

Order item data extension

An order item data extension is an object that lets you specify any key-value pairs you want. Order data extensions are optional and enable your organization to capture more robust information about your order items.

To get started with this API, create a data extension for the order items you previously created.

Operations

Sitecore CDP Order REST API (v2.1)

Authentication

Get started

Order

Order item

Order contact

Order consumer

Order data extension

Create an order data extension

Request

Creating the request body

Naming keys

Example request body

Responses

Was this helpful?

Retrieve an order data extension

Request

Responses

Was this helpful?

Update an order data extension

Request

Responses

Was this helpful?

Partially update an order data extension

Request

Responses

Was this helpful?

Delete an order data extension

Request

Responses

Was this helpful?

Delete key-value pairs from an order data extension

Request

Responses

Was this helpful?

Retrieve the URL for an order's data extension

Request

Responses

Was this helpful?

Order item data extension