Manage Recommendations using APIs
You can use the following APIs to provide in-context recommendations to your customer:
Fetch Recommendations
Use the Fetch Recommendations API call with appropriate query parameters to retrieve the relevant recommendations:
Request Header
See Headers section.
Request Body
Here’s the sample request body:
{
"recommendationContext": "RENEWAL_ORDER_PREVIEW | GENERIC | ORDERS_VIEW",
"customerId": "<CustomerId>",
"offers": [
{
"offerId": "30005897CA01A12",
"quantity": 10
},
{
"offerId": "30006566CA14A12",
"quantity": 5
}
],
"country": "JP",
"language": "MULT"
}
Request parameters
The following table lists the request parameters and their corresponding descriptions:
EN <br /> - MULT <br />Note: Use EN for Western Europe customers or global customers deploying in Europe. MULT is available for all other regions.Offers object
Response
Response Header
The following response header, added to all responses, provides data to understand how recommendations are working: x-recommendation-tracker-id: <Some String identifier>. For more information, see Provide recommendation tracking data to Adobe to improve future recommendations.
Response Body
{
"productRecommendations": {
"upsells": [
{
"rank": 0,
"product": {
"baseOfferId": "30006208CA01A12"
},
"source": {
"sourceType": "OFFER",
"offerIds": [
"30005702CA01A12"
],
},
},
{
"rank": 1,
"product": {
"baseOfferId": "65304921CA01A12"
},
"source": {
"sourceType": "OFFER",
"offerIds": [
"30005702CA01A12"
],
},
},
],
"crossSells": [
{
"rank": 0,
"product": {
"baseOfferId": "30006208CA01A12"
},
"source": {
"sourceType": "OFFER",
"offerIds": [
"30005702CA01A12"
],
},
},
],
"addOns": [
{
"rank": 0,
"product": {
"baseOfferId": "65304921CA01A12"
},
"source": {
"sourceType": "OFFER",
"offerIds": [
"30005702CA01A12"
],
},
},
],
},
}
Response parameters
OFFER is supported.HTTP Status Codes
Preview Order
Use the Preview Order API to get the recommendations to display while previewing the order.
/v3/customers/<customerId>/ordersQuery parameters
You can use the following query parameters as shown in this request URL: POST <cpapi-host>/v3/customers/<customerId>/orders?fetch-recommendations=true&recommendation-country=US&recommendation-language=EN
Request header
See Headers section.
Request body
No change to the standard request payload. For example:
{
"externalReferenceId": "{{externalReferenceId}}",
"orderType": "PREVIEW",
"currencyCode": "USD",
"lineItems": [
{
"extLineItemNumber": 1,
"offerId": "65304479CA03A12",
"quantity": 20,
"currencyCode": "USD",
"deploymentId": "12345"
}
]
}
Response
Response header: x-recommendation-tracker-id: <Some String identifier>
Response body:
{
"externalReferenceId": "9ddd98ba-2361-41c9-ae21-7feb04bf9cd",
"orderId": "ABCDORDER1",
"customerId": "1005513019",
"...": "..."
"lineItems":[
{
"extLineItemNumber":1,
"...": "..."
}
],
"creationDate":"2025-02-18T13:02:50Z"
"recommendations": {
"productRecommendations": {
"upsells": [...],
"crossSells": [...],
"addOns": [...]
}
}
}
Note: The recommendations block lists the available recommendations.
HTTP Status Code
No change from the standard Preview Order API.
Preview Order Renewal
Use the Preview Renewal API call with appropriate query parameters to fetch relevant recommendations for both auto and manual renewal scenarios:
/v3/customers/<customerId>/ordersQuery Parameters
You can use the following query parameters as shown in this request URL: POST <cpapi-host>/v3/customers/<customerId>/orders?fetch-recommendations=true&recommendation-country=US&recommendation-language=EN
Request header
See Headers section.
Request body
No change to the standard request body. For example:
{
"externalReferenceId": "{{externalReferenceId}}",
"referenceOrderId": "{{orderId}}",
"orderType": "PREVIEW_RENEWAL",
"currencyCode": "USD"
}
Note: Manual renewal accepts OfferIds in the request payload.
Response
{
"externalReferenceId": "9ddd98ba-2361-41c9-ae21-7feb04bf9cd",
"orderId": "",
"lineItems": [
{
"extLineItemNumber": 1,
"...": "..."
}
],
"eligibleOffers": [
{
"offerId": "65324918CA01V12",
"discountCode": "CA01V12",
"quantity": 25,
"eligibleCustomer": "ALL"
},
{
"": ""
}
],
"creationDate": "2025-02-18T13:02:50Z",
"recommendations": {
"productRecommendations": {
"upsells": [...],
"crossSells": [...],
"addOns": [...]
}
}
}
Note: The recommendations block lists the available recommendations.
Response parameters
HTTP Status Code
Get Subscription
Use the GET Subscriptions API call with appropriate query parameters to fetch relevant recommendations:
/v3/customers/<customerId>/subscriptionsQuery Parameters
You can use the following query parameters as shown in this request URL: GET <cpapi-host>/v3/customers/<customerId>/subscriptions?fetch-recommendations=true&recommendation-country=US&recommendation-language=EN
Request header
See Headers section.
Request body
None.
Response
{
"totalCount": 2,
"items": [
{
"subscriptionId": "d76634e0c34cb2bb1057380b998cd2NA",
"offerId": "65322587CA01A12",
"currentQuantity": 5009,
"usedQuantity": 0,
"autoRenewal": {
"enabled": true,
"renewalQuantity": 5009
},
"creationDate": "2024-07-17T01:13:09Z",
"renewalDate": "2025-07-17",
"status": "1000",
"currencyCode": "USD",
"links": {
"self": {
"uri": "/v3/customers/1005513019/subscriptions/d76634e0c34cb2bb1057380b998cd2NA",
"method": "GET",
"headers": []
}
}
},
{
"subscriptionId": "da5410d3114d38b9ab6149fdb1f120NA",
"offerId": "65304479CA01A12",
"currentQuantity": 60,
"usedQuantity": 0,
"autoRenewal": {
"enabled": true,
"renewalQuantity": 60
},
"creationDate": "2025-01-07T19:25:46Z",
"renewalDate": "2025-07-17",
"status": "1000",
"currencyCode": "USD",
"links": {
"self": {
"uri": "/v3/customers/1005513019/subscriptions/da5410d3114d38b9ab6149fdb1f120NA",
"method": "GET",
"headers": []
}
}
}
],
"links": {
"self": {
"uri": "/v3/customers/1005513019/subscriptions",
"method": "GET",
"headers": []
}
},
"recommendations": {
"productRecommendations": {
"upsells": [...],
"crossSells": [...],
"addOns": [...]
}
}
}
Note: The recommendations block lists the available recommendations.
HTTP Status Code
Same as the standard GET Subscriptions API.
Get Order
Use the GET Order API call with appropriate query parameters to fetch relevant recommendations:
/v3/customers/<customerId>/ordersQuery Parameters
You can use the following query parameters as shown in this request URL: GET <cpapi-host>/v3/customers/<customerId>/orders?fetch-recommendations=true&recommendation-country=US&recommendation-language=EN
Request header
See Headers section.
Request body
None.
Response
{
"totalCount":2,
"count":2,
"offset":0,
"limit":25,
"items":[
{
"referenceOrderId":"",
"externalReferenceId":"240505012402240931",
"orderId":"9203400470",
"customerId":"1005513019",
"currencyCode":"USD",
"orderType":"NEW",
"status":"1000",
"lineItems":[
{
"extLineItemNumber":1,
"offerId":"65322587CA12A12",
"quantity":5000,
"subscriptionId":"d76634e0c34cb2bb1057380b998cd2NA",
"status":"1000"
},
{
"extLineItemNumber":2,
"offerId":"65322474CATAA12",
"quantity":5000,
"subscriptionId":"73d39c59a04e0f8f93fc5449e63721NA",
"status":"1000"
}
],
"creationDate":"2024-07-18T12:32:33Z",
"links":{
"self":{
"uri":"/v3/customers/1005513019/orders/9203400470",
"method":"GET",
"headers":[
]
}
}
},
{
"referenceOrderId":"",
"externalReferenceId":"240717011236827259",
"orderId":"9203398779",
"customerId":"1005513019",
"currencyCode":"USD",
"orderType":"NEW",
"status":"1000",
"lineItems":[
{
"extLineItemNumber":1,
"offerId":"65322651CA01A12",
"quantity":9,
"subscriptionId":"023b7bb4774e6fa0f597e25624b7f2NA",
"status":"1000"
},
{
"extLineItemNumber":2,
"offerId":"65322587CA01A12",
"quantity":9,
"subscriptionId":"d76634e0c34cb2bb1057380b998cd2NA",
"status":"1000"
}
],
"creationDate":"2024-07-17T01:12:39Z",
"links":{
"self":{
"uri":"/v3/customers/1005513019/orders/9203398779",
"method":"GET",
"headers":[
]
}
}
}
],
"links":{
"self":{
"uri":"/v3/customers/1005513019/orders?status=1000&start-date=2024-01-01T03%253A43%253A07Z&end-date=2025-01-31T00%253A00%253A00Z&limit=25&offset=0",
"method":"GET",
"headers":[
]
}
}
"recommendations": {
"productRecommendations": {
"upsells": [...],
"crossSells": [...],
"addOns": [...]
}
}
}
Note: The recommendations block lists the available recommendations.
HTTP Status Codes
Same as the standard GET Order API.
Provide tracking data to Adobe to get improved recommendations
The following response header that is added to all responses provides data to understand how recommendations are working: x-recommendation-tracker-id: <Some String identifier>.
Adobe can get more insight and provide better recommendations based on the data collected from the tracker. Partners need to send the x-recommendation-tracker-id as a header in the Create Order and Create Subscription APIs. A sample CURL command for Create Order API with tracker ID in the header is as follows:
curl --location 'https: //partners.adobe.io/v3/customers/1005513019/orders' \
--header '.... Existing headers ....' \
--header 'x-recommendation-tracker-id: 85v9S4NAv2eLKmJ11LY7yxDwGrIvU94S' \
--data '{
"externalReferenceId": "6a6023e0-7b11-470a-8444-be3d0099639",
"orderType": "NEW",
"currencyCode": "USD",
"lineItems": [
{
"extLineItemNumber": 1,
"offerId": "65304479CA01A12",
"quantity": 20
}
]
}'