Sitecore API catalog
/
Sitecore CDP Order REST API
/
Order data extension
/
Partially update an order data extension

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
index.json
index.yaml
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

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}"