# Order API 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](https://doc.sitecore.com/cdp/en/developers/api/index-en.html), including [examples](https://doc.sitecore.com/cdp/en/developers/api/examples-of-order-items-rest-api-v2-1.html) 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](https://doc.sitecore.com/cdp/en/users/sitecore-cdp/identifying-guests-in-sitecore-cdp.html). 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. Version: v2.1 License: Apache 2.0 Metadata: - product: CDP ## 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 ``` ## Security ### BasicAuth Type: http Scheme: basic ### BearerToken Type: http Scheme: bearer Bearer Format: JWT ## Download OpenAPI description [Order API](https://api-docs.sitecore.com/_bundle/cdp/order-rest-api/index.yaml) ## 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. ### Create an order - [POST /v2.1/orders](https://api-docs.sitecore.com/cdp/order-rest-api/order/createorder.md): Creates an order. In the response, ref contains the order reference. Use the order reference to interact with a specific order, for example, to retrieve it, update it, or create a data extension for it. ### List orders - [GET /v2.1/orders](https://api-docs.sitecore.com/cdp/order-rest-api/order/retrieveorders.md): Retrieves a list of orders that either have the same reference ID or belong to the same guest. You must include either the referenceId of the order or the guestRef as a query string parameter in the URI of the request, but not both. In the response, items.ref contains the order reference. Use the order reference to interact with a specific order, for example, to retrieve it, update it, or create a data extension for it. ### Retrieve an order - [GET /v2.1/orders/{orderRef}](https://api-docs.sitecore.com/cdp/order-rest-api/order/retrieveorder.md): Retrieves an order. ### Update an order - [PUT /v2.1/orders/{orderRef}](https://api-docs.sitecore.com/cdp/order-rest-api/order/updateorder.md): Updates an order. You can update orders that have the same referenceId and have orderedAt values (purchase dates) within two days of another. referenceId and orderedAt cannot be updated. ### Partially update an order - [PATCH /v2.1/orders/{orderRef}](https://api-docs.sitecore.com/cdp/order-rest-api/order/updateorder_1.md): Partially updates an order. You can update orders that have the same referenceId and have orderedAt values (purchase dates) within two days of another. referenceId and orderedAt cannot be updated. ### Delete an order - [DELETE /v2.1/orders/{orderRef}](https://api-docs.sitecore.com/cdp/order-rest-api/order/deleteorder_1.md): Deletes an order. An empty, 204 No Content response means that the deletion was successful. ## 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. ### Create an order item - [POST /v2.1/orders/{orderRef}/orderItems](https://api-docs.sitecore.com/cdp/order-rest-api/order-item/createorderitem.md): 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. ### List order items for an order - [GET /v2.1/orders/{orderRef}/orderItems](https://api-docs.sitecore.com/cdp/order-rest-api/order-item/retrieveorderitems_1.md): 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. ### Retrieve an order item - [GET /v2.1/orderItems/{orderItemRef}](https://api-docs.sitecore.com/cdp/order-rest-api/order-item/retrieveorderitem.md): Retrieves an order item. ### Update an order item - [PUT /v2.1/orderItems/{orderItemRef}](https://api-docs.sitecore.com/cdp/order-rest-api/order-item/updatesorderitem.md): Updates an order item. ### Partially update an order item - [PATCH /v2.1/orderItems/{orderItemRef}](https://api-docs.sitecore.com/cdp/order-rest-api/order-item/partiallyupdatesorderitem.md): Partially updates an order item. ### Delete an order item - [DELETE /v2.1/orderItems/{orderItemRef}](https://api-docs.sitecore.com/cdp/order-rest-api/order-item/deleteorderitem.md): Deletes an order item. ## 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. ### Create an order contact - [POST /v2.1/orders/{orderRef}/contacts](https://api-docs.sitecore.com/cdp/order-rest-api/order-contact/createordercontact.md): Creates the primary contact on an order. In identifiers, make sure to provide enough identity information according to your organization's identity rules. In the response, ref contains the order contact reference. Use the order contact reference to interact with a specific contact, for example, to retrieve or update it. ### List order contacts for an order - [GET /v2.1/orders/{orderRef}/contacts](https://api-docs.sitecore.com/cdp/order-rest-api/order-contact/retrieveordercontacts.md): Retrieves a list of order contacts for an order. In the response, items.ref contains the order contact reference. Use the order contact reference to interact with a specific order contact, for example, to retrieve or update it. ### Retrieve an order contact - [GET /v2.1/orderContacts/{orderContactRef}](https://api-docs.sitecore.com/cdp/order-rest-api/order-contact/retrievesordercontact.md): Retrieves an order contact. ### Update an order contact - [PUT /v2.1/orderContacts/{orderContactRef}](https://api-docs.sitecore.com/cdp/order-rest-api/order-contact/updateordercontact.md): Updates an order contact. ### Partially update an order contact - [PATCH /v2.1/orderContacts/{orderContactRef}](https://api-docs.sitecore.com/cdp/order-rest-api/order-contact/partiallyupdateordercontact_1.md): Partially updates an order contact. ### Delete an order contact - [DELETE /v2.1/orderContacts/{orderContactRef}](https://api-docs.sitecore.com/cdp/order-rest-api/order-contact/partiallyupdateordercontact.md): Partially updates an order contact. ## 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. ### Create an order consumer - [POST /v2.1/orders/{orderRef}/consumers](https://api-docs.sitecore.com/cdp/order-rest-api/order-consumer/createorderconsumer.md): Creates a consumer on an order. In identifiers, make sure to provide enough identity information according to your organization's identity rules. In the response, ref contains the order consumer reference. Use the order consumer reference to interact with a specific consumer, for example, to retrieve or update it. ### List consumers of an order - [GET /v2.1/orders/{orderRef}/consumers](https://api-docs.sitecore.com/cdp/order-rest-api/order-consumer/retrieveorderconsumers.md): Retrieves a list of order consumers for an order. In the response, items.ref contains the order consumer reference. Use the order consumer reference to interact with a specific order consumer, for example, to retrieve or update it. ### Retrieve an order consumer - [GET /v2.1/orderConsumers/{orderConsumerRef}](https://api-docs.sitecore.com/cdp/order-rest-api/order-consumer/retrieveorderconsumer.md): Retrieves an order consumer. ### Update an order consumer - [PUT /v2.1/orderConsumers/{orderConsumerRef}](https://api-docs.sitecore.com/cdp/order-rest-api/order-consumer/updateorderconsumer.md): Updates an order consumer. ### Partially update an order consumer - [PATCH /v2.1/orderConsumers/{orderConsumerRef}](https://api-docs.sitecore.com/cdp/order-rest-api/order-consumer/partiallyupdateordeconsumer.md): Partially updates an order consumer. ### Delete an order consumer - [DELETE /v2.1/orderConsumers/{orderConsumerRef}](https://api-docs.sitecore.com/cdp/order-rest-api/order-consumer/deleteorder.md): Delete an order consumer. An empty, 204 response means that the deletion was successful. ### List a consumer's order items - [GET /v2.1/orderConsumers/{orderConsumerRef}/orderItems](https://api-docs.sitecore.com/cdp/order-rest-api/order-consumer/retrieveorderitems.md): Retrieves order items for a consumer. ## 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. ### Create an order data extension - [POST /v2.1/orders/{orderRef}/extensions/{dataExtensionName}](https://api-docs.sitecore.com/cdp/order-rest-api/order-data-extension/createorderdataextension.md): 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. ### Retrieve an order data extension - [GET /v2.1/orders/{orderRef}/extensions/{dataExtensionName}](https://api-docs.sitecore.com/cdp/order-rest-api/order-data-extension/retrieveorderdataextension.md): Retrieves a data extension for an order. ### Update an order data extension - [PUT /v2.1/orders/{orderRef}/extensions/{dataExtensionName}](https://api-docs.sitecore.com/cdp/order-rest-api/order-data-extension/putorderdataextension.md): 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. ### Partially update an order data extension - [PATCH /v2.1/orders/{orderRef}/extensions/{dataExtensionName}](https://api-docs.sitecore.com/cdp/order-rest-api/order-data-extension/updateorderdataextension.md): Partially updates a data extension for an order, replacing only those key-value pairs in the resource that you provide in the request. ### Delete an order data extension - [DELETE /v2.1/orders/{orderRef}/extensions/{dataExtensionName}](https://api-docs.sitecore.com/cdp/order-rest-api/order-data-extension/deleteorderdataextension.md): 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. ### Delete key-value pairs from an order data extension - [DELETE /v2.1/orders/{orderRef}/extensions/{dataExtensionName}/fields](https://api-docs.sitecore.com/cdp/order-rest-api/order-data-extension/deleteorderdataextensionfields.md): 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. ### Retrieve the URL for an order's data extension - [GET /v2.1/orders/{orderRef}/extensions](https://api-docs.sitecore.com/cdp/order-rest-api/order-data-extension/retrieveorderdataextensions.md): Retrieves the URL for the order's data extension. This lets you check if the data extension exists. ## 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. ### Create an order item data extension - [POST /v2.1/orderItems/{orderItemRef}/extensions/{dataExtensionName}](https://api-docs.sitecore.com/cdp/order-rest-api/order-item-data-extension/createorderitemdataextension.md): Creates an order item data extension. To avoid creating key-value pairs that already exist in the data extension for an order item, first retrieve all the data extensions for an order item 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 "withWarranty": true in the object, With Warranty 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: { "withWarranty": true, "color": "obsidian", "capacityInGb": 128 } This creates three key-value pairs for the order item. ### Retrieve an order item data extension - [GET /v2.1/orderItems/{orderItemRef}/extensions/{dataExtensionName}](https://api-docs.sitecore.com/cdp/order-rest-api/order-item-data-extension/retrieveorderitemdataextension.md): Retrieves a data extension for an order item. ### Update an order item data extension - [PUT /v2.1/orderItems/{orderItemRef}/extensions/{dataExtensionName}](https://api-docs.sitecore.com/cdp/order-rest-api/order-item-data-extension/putorderitemdataextension.md): Fully updates a data extension for an order item, 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. ### Partially update an order item data extension - [PATCH /v2.1/orderItems/{orderItemRef}/extensions/{dataExtensionName}](https://api-docs.sitecore.com/cdp/order-rest-api/order-item-data-extension/updateorderitemdataextension_1.md): Partially updates a data extension for an order, replacing only those key-value pairs in the resource that you provide in the request. ### Delete an order item data extension - [DELETE /v2.1/orderItems/{orderItemRef}/extensions/{dataExtensionName}](https://api-docs.sitecore.com/cdp/order-rest-api/order-item-data-extension/deleteorderitemdataextension.md): Deletes the data extension for an order item, 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. ### Delete key-value pairs from an order item data extension - [DELETE /v2.1/orderItems/{orderItemRef}/extensions/{dataExtensionName}/fields](https://api-docs.sitecore.com/cdp/order-rest-api/order-item-data-extension/updateorderitemdataextension.md): Deletes the key-value pairs you provide in the name query parameter from a data extension for an order item. 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. ### Retrieve the URL for an order item's data extension - [GET /v2.1/orderItems/{orderItemRef}/extensions](https://api-docs.sitecore.com/cdp/order-rest-api/order-item-data-extension/retrieveorderitemdataextensions.md): Retrieves the URL for the order item's data extension. This lets you check if the data extension exists.