Deliver offers using the Batch Decisioning API

The Batch Decisioning API allows organizations to use offer decisioning functionality for all profiles in a given segment in one call. The offer content for each profiles in the segment is placed in an Adobe Experience Platform dataset where it is available for custom batch workflows.

With the Batch Decisioning API, you can populate a dataset with the best offers for all profiles in an Adobe Experience Platform segment for decision scopes. For example, an organization may want to run Batch Decisioning so they can send offers to a message delivery vendor. Those offers are then used as content that is sent out for batch message delivery to the same segment of users.

To do this, the organization would:

• Run the Batch Decisioning API, which contains two requests:

  1. A Batch POST request to start a workload to batch process offer selections.

  2. A Batch GET request to get batch workload status.

• Export the dataset to the message delivery vendor API.

Getting started

Before using this API, make sure you complete the following pre-requisite steps.

Prepare the decision

Follow the steps below to prepare one or more decisions:

• In order to export the decision result, create a dataset using the “ODE DecisionEvents” schema.

• Create a Platform segment which should be evaluated and then updated. Refer to the segmentation documentation to learn more about how to update segment membership evaluation.

• Create a decision (which has a decision scope that consists of a Decision ID and a Placement ID) in Adobe Journey Optimizer. Refer to the section on defining decision scopes of the guide on creating decisions to learn more.

API requirements

All Batch Decisioning requests require the following headers in addition to the ones referred to in the Decision Management API developer guide:

• Content-Type: application/json
• x-request-id: A unique string that identifies the request.
• x-sandbox-name: The sandbox name.
• x-sandbox-id: The sandbox ID.

Start a batch process

To start a workload to batch process decisions, make a POST request to the /workloads/decisions endpoint.

API format

POST {ENDPOINT_PATH}/{CONTAINER_ID}/workloads/decisions

Request

curl -X POST 'https://platform.adobe.io/data/core/ode/0948b1c5-fff8-3b76-ba17-909c6b93b5a2/workloads/decisions' \
-H 'x-request-id: f671a589-eb7b-432f-b6b9-23d5b796b4dc' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'x-sandbox-id: {SANDBOX_ID}' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-d '{
  "xdm:segmentIds": [
    "609028e4-e66c-4776-b0d9-c782887e2273"
  ],
  "xdm:dataSetId": "6196b4a1a63bd118dafe093c",
  "xdm:propositionRequests": [
        {
            "xdm:activityId": "xcore:offer-activity:1410cdcda196707b",
            "xdm:placementId": "xcore:offer-placement:1410c4117306488a",
            "xdm:itemCount": 1
        }
  ],
  "xdm:includeContent": false
}'

Refer to the Decision Management documentation for an overview of the main concepts and properties.

Response

{
    "@id": "47efef25-4bcf-404f-96e2-67c4f784a1f5",
    "xdm:imsOrgId": "9GTO98D5F@AdobeOrg",
    "xdm:containerId": "0948b1c5-fff8-3b76-ba17-909c6b93b5a2",
    "ode:createDate": 1648078924834,
    "ode:status": "QUEUED"
}

Retrieve information on a batch decision

To retrieve information on a specific decision, make a GET request to the /workloads/decisions endpoint while providing the corresponding workload ID value for your decision.

API format

GET  {ENDPOINT_PATH}/{CONTAINER_ID}/workloads/decisions/{WORKLOAD_ID}

Request

curl -X GET 'https://platform.adobe.io/data/core/ode/0948b1c5-fff8-3b76-ba17-909c6b93b5a2/workloads/decisions/f395ab1f-dfaf-48d4-84c9-199ad6354591' \
-H 'x-request-id: 7832a42a-d4e5-413b-98e8-e49bef056436' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H'x-sandbox-id: {SANDBOX_ID}' \
-H 'Authorization: Bearer {ACCESS_TOKEN}'

Response

{
    "@id": "f395ab1f-dfaf-48d4-84c9-199ad6354591",
    "xdm:imsOrgId": "{IMS_ORG}",
    "xdm:containerId": "0948b1c5-fff8-3b76-ba17-909c6b93b5a2",
    "ode:createDate": 1648076994405,
    "ode:status": "COMPLETED"
}

Service levels

The end-to-end time for every batch decision is the duration from the time the workload is created to the time when the decision result is available in the output dataset. The segment size in the POST request payload is the main factor that affects the end-to-end batch decision time. If the eligible offer has a global frequency cap enabled, then batch decisioning takes additional time to complete. Below are some approximations of end-to-end processing time for their respective segment sizes, both with and without frequency capping for eligible offers:

With frequency cap enabled for eligible offers:

Without frequency cap for eligible offers:

Limitations

When using the Batch Decisioning API, keep the following limitations in mind:

• The number of running batch jobs per dataset: Up to five batch jobs can be run at a time, per dataset. Any other batch requests with the same output dataset are added to the queue. A queued job is picked up to process once the previous job has finished running.
• Frequency capping: A batch runs off of the profile snapshot that occurs once a day. The Batch Decisioning API caps the frequency and always loads profiles from the most recent snapshot.

Next steps

By following this API guide, you have checked for the workload status and delivered offers using the Batch Decisioning API. For more information, see the overview on Decision Management.