Omnichannel Order API

Last updated
Save as PDF

Reference information for the Omnichannel Order API

Introduction

The personalization platform now has the ability to accept offline orders via REST API. Using the API, it’s now possible to import both offline and online orders into the platform. The API enables the ability to import either multiple orders or a single order per API request.

Supported Modes & Channel

With the Omnichannel Order API, orders can be imported by specifying any of the following modes:

Offline: Default, If no mode is provided in the JSON payload, the platform will import orders as offline orders.
Online: The submitted orders will be imported as online orders. Such orders will be treated at par with the orders synchronized with the platform via Runtime API i.e. Recsforplacement API.
Channel: It is also possible to specify an Apikey mapped to a specific channel with each order payload. Please refer to this page to get more details on how the channel information gets mapped inside reports. For example, dedicated API keys can be associated with different channels such as Mobile POS, in-Store POS, etc. This will help to link specific orders to a specific channel per customer preferences, which will be visible in the Sales by channel report.

Authentication to Algonomy Gateway

The authentication to the Algonomy API gateway is facilitated using Oauth2.0- grant-type client credentials. Please reach out to your Personalization consultant to request a client_ID & client_secret for your exclusive use.

Algonomy will create client_ID and client_secret for each site (configured for each customer) and will share them in the requested method.

The client_ID and client_secret are required to obtain bearer tokens for accessing the Omnichannel Order API. Bearer tokens have TTL (time to live) & once TTL is reached, customer systems need to request a new bearer token with the provided client_ID & client_secret.

Creating Tokens

Hosts

Production

https://gateway.richrelevance.com/

https://qa-gateway.richrelevance.com/

Staging

https://staging-gateway.richrelevance.com/

Note: You need to create different tokens for each environment. For example, you cannot use the token created for the QA environment in the production environment.

To create tokens, use the request syntax below:

POST https://<host>/omnichannel/v1/oauth2/token?grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>

Note: Replace client_id and client_secret with the corresponding values provided to you by the Algonomy consultant.

Sample Request

To obtain a token for the Omnichannel Order API service in the QA environment.

In this example, the client_id is5934de97c95e1ced and the client_secret is 2l9dr0jkink11ad49hg93it52d. Each customer will have a unique client_id and client_secret.

POST-https://qa-gateway.richrelevance.com/omnichannel/v1/oauth2/token?grant_type=client_credentials&client_id=5934de97c95e1ced&client_secret=2l9dr0jkink11ad49hg93it52d

Sample Response

    
{
      
"token_type": "bearer"
      
"access_token": "M6w0M0K9QbQGHC8xgvb91ZgLMKaW4xOd",
      
}

Example with cURL:

curl -X POST https://qa-gateway.richrelevance.com/omnichannel/v1/oauth2/token -d "grant_type=client_credentials" -d "client_id=5934de97c95e1ced" -d "client_secret=2l9dr0jkink11ad49hg93it52d"

Requests to Algonomy Gateway Require the Bearer Token

For every Omnichannel Order API call, the bearer token value that was obtained in the Creating Tokens step should be included as part of the Authorization header.

https://<host>/<omnichannel>/api/v1/<apiKey>      
'Authorization:Bearer <tokenValue>'

Example: To update a list of offline orders against a user id, use the below API request.

PUT https://qa-gateway.richrelevance.com/omnichannel/api/v1/<apiKey>/orders/users/<userid>?mode=offline'Authorization:Bearer M6w0M0K9QbQGHC8xgvb91ZgLMKaW4xOd’

Example with cURL:

curl -H 'Authorization:Bearer <tokenValue>' PUT https://qa-gateway.richrelevance.com/omnichannel/api/v1/<apiKey>/orders/users/<userid>?mode=offline

Omnichannel API service Health check

To check the health of Omnichannel API service, you can use the following end point with the Bearer token that was obtained in the Creating Tokens step.

GET https://<host>/omnichannel/health      
'Authorization:Bearer <tokenValue>'

Example with cURL:

curl -H 'Authorization:Bearer <tokenValue>'GET https://host/omnichannel/health

Omnichannel Order Import

Below are actions and syntax for importing orders either as offline or online to the Personalization platform.

Omnichannel Order syntax for offline order import

Import Multiple Orders Full URL: POST https://<host>/omnichannel/api/v1/<apiKey>/orders

'Authorization:Bearer <tokenValue>’

Parameters

Parameter	Mandatory/Optional	Description
apiKey	Mandatory	apiKey
Mode	Optional	Supported values as offline or online. This denotes whether orders are to be tagged as online orders or offline orders while being imported into the platform. If not specified the system will default to offline mode.

Import Single Order Full URL: PUT https://<host>/omnichannel/api/v1/<apiKey>/orders/users/<userid>

'Authorization:Bearer <tokenValue>’

Parameters

Parameter	Mandatory/Optional	Description
apiKey	Mandatory	apiKey
userid	Mandatory	Global Unique Shopper/User ID. Shopper IDs in the offline feed must match shopper IDs received through site instrumentation.
Mode	Optional	Supported values as offline or online. This denotes whether orders are to be tagged as online orders or offline orders while being imported into the platform. If not specified the system will default to offline mode.

Action and Syntax

Action	Syntax
Import single order	PUT {baseURL}/omnichannel/api/v1/{apikey}/orders/users/<userid>
Update multiple orders	POST {baseURL}/omnichannel/api/v1/{apikey}/orders

Action

Syntax

Import single order

PUT {baseURL}/omnichannel/api/v1/{apikey}/orders/users/<userid>

Update multiple orders

POST {baseURL}/omnichannel/api/v1/{apikey}/orders

Omnichannel Order Information (API Body)

Element

Description

Data Type

Optional/ Mandatory

Values

Numeric value for each order. At least unique by channel

integer

Mandatory

1723

channel

Client API key associated with the preferred channel.

Please reach out to your Algonomy consultant to receive the specific client key to be used here.

If certain orders are to be reported as 'online' channel then a dedicated key should be created against channel key 'online' and in cases where orders are supposed to show up under 'offline' channel under Reports, then please use the specific API key created for the channel key 'offline'.
For more details refer to this page.

string

Optional

6a700f55b7059e38

userId

Global Unique Shopper/User ID. Shopper IDs in the offline feed must match shopper IDs received through site instrumentation.

Note: User ID should be specified as part of the API URL if the objective is to import a single order against a single User ID.

string

Mandatory

87d5f6ead7723d4703bce2a34d72e4a697dec82b5fbbcda755dde4a1e16ba16d

dateTime

A date and time of the transaction in ISO 8601 compatible format.

ISO DATETIME

Mandatory

2007-04-25T14:30:00+09:00

paymentMethod

cash, credit, check, digital, other. Useful for segmentation and targeting

string

Optional

Cash, Credit

emailHash

A hash of the customer’s email address, if POS captures email at transaction time. Hashed out for PII standards.

string

Optional

ccHash

A fully obfuscated credit card identifier

string

Optional

regionId

The region_id in which the transaction occurred as specified in the region full feed.

long

Optional

storeId

ID of the store in which transaction occurred

string

Optional

segmentId

A unique identifier for the segment the shopper belongs to. A segment is a group of shoppers with a common demographic or demonstrated pattern to which promotions can be targeted based on affinities and patterns specific to that group.

Multiple values in double quotes can be sent as an array of strings– comma separated

Array of string

Optional

["44", "55", "3"],

segmentNames

A human-friendly name for the segment.

Multiple values in double quotes can be sent as an array – comma separated

Array of string

Optional

["seg1", "seg2", "seg3"]

currency

The ISO currency code representing the currency used for the order.

To facilitate appropriate reporting, please ensure that the 'default site currency in the report' is set to the appropriate currency to ensure the correct currency is showing up in Reports.

Note: If not specified, this defaults to US currency (USD).

ISO currency code

Optional

USD

couponCode

The coupon applied to the entire order (if applicable)

string

Optional

couponValue

Monetary value of the coupon applied to the entire order.

integer

Optional

lineItems

Line items to be associated with the specified order ID. To be specified as an array.

Field	Description	Type	Mandatory/Optional
productId	Unique ID for a product. This should be a key to look up into the catalog. Note: If the specified Product ID is not present in the Personalization catalog, system will not accept the request.	integer	Mandatory
skuId	SKU for the line item. Should correspond to a value provided in the SKU Feed	integer	Optional
quantity	Quantity of the items purchased	integer	Mandatory
unitPrice	Monetary value paid per unit	integer	Mandatory

Array

Mandatory

{

"productId": 4556,

"skuId": "123",

"quantity": 10,

"unitPrice": 256.678

}

Example #1

Importing Multiple offline orders i.e. mode=offline

Apikey:- 12345

HTTP Method: POST

URL: https://gateway.richrelevance.com/omnichannel/api/v1/12345/orders?mode=offline

Payload:

[{
  "id": 123,
  "channel": "6a700f55b7059e38",
  "dateTime": "2022-04-25T12:21:55+09:00",
  "paymentMethod": "Credit card",
  "emailHash": "d12345gf345",
  "ccHash": "q1234rfgth",
  "storeId": "Store123",
  "regionId": -1,
  "segmentIds": ["44", "55", "3"],
  "segmentNames": ["seg1", "seg2", "seg3"],
  "currency": "USD",
  "couponCode": "RR01",
  "couponValue": 23.76,
  "lineItems": [
    {
      "productId": 4556,
      "skuId": "sku1",
      "quantity": 10,
      "unitPrice": 256.678
    },
    {
      "productId": 4557,
      "skuId": "sku2",
      "quantity": 10,
      "unitPrice": 356.678
    },
    {
      "productId": 4558,
      "skuId": "sku3",
      "quantity": 10,
      "unitPrice": 456.678
    }
  ]
},
{
  "id": 1234,
  "channel": "6a700f55b7059e38",
  "userId": "userA2",
  "dateTime": "2022-04-25T14:30:25+09:00",
  "paymentMethod": "Credit card",
  "emailHash": "d123fgbnht545",
  "ccHash": "r4321weetgg",
  "storeId": "Store 234",
  "regionId": -1,
  "segmentIds": ["44", "55", "3"],
  "segmentNames": ["seg1", "seg2", "seg3"],
  "currency": "USD",
  "couponCode": "RR01",
  "couponValue": 23.76,
  "lineItems": [
    {
      "productId": 4556,
      "skuId": "sku1",
      "quantity": 10,
      "unitPrice": 256.678
    },
    {
      "productId": 4557,
      "skuId": "sku2",
      "quantity": 10,
      "unitPrice": 356.678
    },
    { 
    "productId": 4558,
      "skuId": "sku3",
      "quantity": 10,
      "unitPrice": 456.678
    }
  ]
}
]

Example #2

Importing a single offline order i.e. with the offline mode

Apikey:- 12345

HTTP Method: PUT

URL: https://gateway.richrelevance.com/omnichannel/api/v1/12345/orders/users/userC2?mode=offline

Payload:

{
  "id": 123,
  "channel": "6a700f55b7059e38",
  "dateTime": "2022-04-25T14:30:00+09:00",
  "paymentMethod": "Credit card",
  "emailHash": "emailHash",
  "ccHash": "credit card hash",
  "storeId": "Store ID",
  "regionId": -1,
  "segmentIds": ["44", "55", "3"],
  "segmentNames": ["seg1", "seg2", "seg3"],
  "currency": "USD",
  "couponCode": "RR01",
  "couponValue": 23.76,
  "lineItems": [
    {
      "productId": 4556,
      "skuId": "sku1",
      "quantity": 10,
      "unitPrice": 256.678
    },
    {
      "productId": 4557,
      "skuId": "sku2",
      "quantity": 10,
      "unitPrice": 356.678
    },
    {
      "productId": 4558,
      "skuId": "sku3",
      "quantity": 10,
      "unitPrice": 456.678
    }
  ]
}

Example #3

Importing a single online order i.e. with the online mode

Apikey:- 12345

HTTP Method: PUT

URL: https://gateway.richrelevance.com/omnichannel/api/v1/12345/orders/users/userC2?mode=online

Payload:

{
  "id": 123,
  "channel": "6a700f55b7059e38",
  "dateTime": "2022-04-25T14:30:00+09:00",
  "paymentMethod": "Credit card",
  "emailHash": "emailHash",
  "ccHash": "credit card hash",
  "storeId": "Store ID",
  "regionId": -1,
  "segmentIds": ["44", "55", "3"],
  "segmentNames": ["seg1", "seg2", "seg3"],
  "currency": "USD",
  "couponCode": "RR01",
  "couponValue": 23.76,
  "lineItems": [
    {
      "productId": 4556,
      "skuId": "sku1",
      "quantity": 10,
      "unitPrice": 256.678
    },
    {
      "productId": 4557,
      "skuId": "sku2",
      "quantity": 10,
      "unitPrice": 356.678
    },
    {
      "productId": 4558,
      "skuId": "sku3",
      "quantity": 10,
      "unitPrice": 456.678
    }
  ]
}

Example #4

Importing Multiple online orders i.e. mode=online

Apikey:- 12345

HTTP Method: POST

URL: https://gateway.richrelevance.com/omnichannel/api/v1/12345/orders?mode=online

Payload:

[{
  "id": 123,
  "channel": "6a700f55b7059e38",
  "userId": "userA1",
  "dateTime": "2022-04-25T12:21:55+09:00",
  "paymentMethod": "Credit card",
  "emailHash": "d12345gf345",
  "ccHash": "q1234rfgth",
  "storeId": "Store123",
  "regionId": -1,
  "segmentIds": ["44", "55", "3"],
  "segmentNames": ["seg1", "seg2", "seg3"],
  "currency": "USD",
  "couponCode": "RR01",
  "couponValue": 23.76,
  "lineItems": [
    {
      "productId": 4556,
      "skuId": "sku1",
      "quantity": 10,
      "unitPrice": 256.678
    },
    {
      "productId": 4557,
      "skuId": "sku2",
      "quantity": 10,
      "unitPrice": 356.678
    },
    {
      "productId": 4558,
      "skuId": "sku3",
      "quantity": 10,
      "unitPrice": 456.678
    }
  ]
},
{
  "id": 1234,
  "channel": "6a700f55b7059e38",
  "userId": "userA2",
  "dateTime": "2022-04-25T14:30:25+09:00",
  "paymentMethod": "Credit card",
  "emailHash": "d123fgbnht545",
  "ccHash": "r4321weetgg",
  "storeId": "Store 234",
  "regionId": -1,
  "segmentIds": ["44", "55", "3"],
  "segmentNames": ["seg1", "seg2", "seg3"],
  "currency": "USD",
  "couponCode": "RR01",
  "couponValue": 23.76,
  "lineItems": [
    {
      "productId": 4556,
      "skuId": "sku1",
      "quantity": 10,
      "unitPrice": 256.678
    },
    {
      "productId": 4557,
      "skuId": "sku2",
      "quantity": 10,
      "unitPrice": 356.678
    },
    {
      "productId": 4558,
      "skuId": "sku3",
      "quantity": 10,
      "unitPrice": 456.678
    }
  ]
}
]
 }

Omni-channel Order Import Status

The Personalization platform provides an API endpoint to check the status details of each import process. After each ingestion, the system generates an automated response according to the specifications outlined below. The Success and Failure counts in the response indicate whether the platform accepted the import request after performing basic data validations.

{
    "message": "Total records = 1. Success = 1. Failed = 0",
    "time": 1685718344543,
    "jobId": "f29dd805-0156-11ee-ad68-7d780afc9f2c"
}

If you receive a Failed response, you can use the following API endpoint to determine the reason for the data validation failure.

Note: The processing of imported orders does not occur in real-time, so there will be a delay before the ingested orders are reflected against the userId in the Portal.

This API requires a different bearer token compared to the one used during the importing process. For more information, refer to the Creating Token section. To create a bearer token that can be used with the status service, use the request syntax provided below:

POST https://<host>/common-status/v1/ouath2/token?grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>

Note: Replace client_id and client_secret with the corresponding values provided to you by the Algonomy consultant. You can use the same client_id and client_secret used to generate the bearer token for the Omnichannel API service.

For each Status API call, include the bearer token value obtained in the previous step as part of the Authorization header.

https://<host>/common-status/api/v1/<apiKey>/job/<jobId>/events      
'Authorization:Bearer <tokenValue>'

Example: To get the detailed status information for an import job using a jobId, use the following format:

GET https://qa-gateway.richrelevance.com/common-status/api/v1/<apiKey>/job/f29dd805-0156-11ee-ad68-7d780afc9f2c/events?showAll=True

Parameters

Parameter	Mandatory/Optional	Description
showAll	Optional	True/False.

Pagination Parameters

Pagination is conditional and is invoked only when the number of "rows" returned by the status service exceeds a specified number or when the "showAll" parameter is included in the API call. By default, the service will return 5000 rows on a single page.

If the “rows” parameter is included, the list of status messages will be paginated, and a pagination JSON is included at the beginning of the response. The pagination response will contain the number of status messages returned as well as the next page token.

Status Examples

Processing Status: When the platform successfully accepts all the ingested orders, the status endpoint will respond with a Processing message in the summary section.

{
    "summary": {
        "owner": {
            "ownerType": "SITE",
            "id": 608
        },
        "job-id": "b75e76f7-0165-11ee-b91c-b9178e343914",
        "job-status": "PROCESSING",
        "job-batches": 1,
        "job-tasks": 1,
        "total-events": 0,
        "query-param": "showAll=false&rows=5000",
        "job": {
            "owner": {
                "ownerType": "SITE",
                "id": 608
            },
            "jobId": "b75e76f7-0165-11ee-b91c-b9178e343914",
            "appId": {
                "appType": "MISC",
                "id": 1078
            },
            "batches": 1,
            "tasks": 1,
            "name": "Total records = 1. Success = 1. Failed = 0",
            "childJobs": 0,
            "rootSource": "omnichannel-api/qa",
            "apps": [
                "omnichannel-api"
            ],
            "datacenters": [
                "qa"
            ],
            "baggage": {
                "records": {
                    "total": 1,
                    "failed": 0,
                    "success": 1
                }
            },
            "attributes": {
                "mode": "offline",
                "type": "orders"
            },
            "restarts": 0,
            "status": "PROCESSING",
            "jobCreated": "2023-06-02T16:51:27.481010300Z",
            "lastModified": "2023-06-02T16:51:27.503Z",
            "duration": "00:00:00"
        }
    },
    "result": []
}

Processing with Warning: If a subset of the ingested orders fails during validation, you will receive a Processing with Warning status.

{
    "summary": {
        "owner": {
            "ownerType": "SITE",
            "id": 608
        },
        "job-id": "63d13c0d-0167-11ee-b91c-b9178e343914",
        "job-status": "PROCESSING_WITH_WARNING",
        "job-batches": 1,
        "job-tasks": 1,
        "total-events": 1,
        "query-param": "showAll=false&rows=5000",
        "WARNING": 1,
        "job": {
            "owner": {
                "ownerType": "SITE",
                "id": 608
            },
            "jobId": "63d13c0d-0167-11ee-b91c-b9178e343914",
            "appId": {
                "appType": "MISC",
                "id": 1078
            },
            "batches": 1,
            "tasks": 1,
            "name": "Total records = 2. Success = 1. Failed = 1",
            "childJobs": 0,
            "rootSource": "omnichannel-api/qa",
            "apps": [
                "omnichannel-api"
            ],
            "datacenters": [
                "qa"
            ],
            "baggage": {
                "records": {
                    "total": 2,
                    "failed": 1,
                    "success": 1
                }
            },
            "attributes": {
                "mode": "online",
                "type": "orders"
            },
            "restarts": 0,
            "status": "PROCESSING_WITH_WARNING",
            "jobCreated": "2023-06-02T17:03:26.298010900Z",
            "lastModified": "2023-06-02T17:03:26.313Z",
            "duration": "00:00:00"
        }
    },
    "result": [
        {
            "taskId": "63d35eee-0167-11ee-b91c-053281f45a51",
            "statusId": "63d385ff-0167-11ee-b91c-1356fa5162e4",
            "batch": 1,
            "type": "Application",
            "message": "No product is found for product ID product3",
            "level": "WARNING",
            "attributes": {
                "mode": "online",
                "type": "orders",
                "orderId": "1234"
            },
            "source": "omnichannel-api",
            "datacenter": "qa",
            "timestamp": "2023-06-02T17:03:26.313011100Z"
        }
    ]
}

Failed:- If the platform is unable to process the entire payload that was ingested, a Failed status message will be returned. As shown in the example, the response includes a result section that provides details about the reason for the failure.

{
    "summary": {
        "owner": {
            "ownerType": "SITE",
            "id": 608
        },
        "job-id": "08ec06c1-0163-11ee-b91c-b9178e343914",
        "job-status": "FAILED",
        "job-batches": 1,
        "job-tasks": 1,
        "total-events": 1,
        "query-param": "showAll=false&rows=5000",
        "WARNING": 1,
        "job": {
            "owner": {
                "ownerType": "SITE",
                "id": 608
            },
            "jobId": "08ec06c1-0163-11ee-b91c-b9178e343914",
            "appId": {
                "appType": "MISC",
                "id": 1078
            },
            "batches": 1,
            "tasks": 1,
            "name": "Total records = 1. Success = 0. Failed = 1",
            "childJobs": 0,
            "rootSource": "omnichannel-api/qa",
            "apps": [
                "omnichannel-api"
            ],
            "datacenters": [
                "qa"
            ],
            "baggage": {
                "records": {
                    "total": 1,
                    "failed": 1,
                    "success": 0
                }
            },
            "attributes": {
                "mode": "offline",
                "type": "orders"
            },
            "restarts": 0,
            "status": "FAILED",
            "jobCreated": "2023-06-02T16:32:15.814009700Z",
            "lastModified": "2023-06-02T16:32:15.838Z",
            "duration": "00:00:00"
        }
    },
    "result": [
        {
            "taskId": "08ef8932-0163-11ee-b91c-053281f45a51",
            "statusId": "08efb043-0163-11ee-b91c-1356fa5162e4",
            "batch": 1,
            "type": "Application",
            "message": "No product is found for product ID 6024383",
            "level": "WARNING",
            "attributes": {
                "mode": "offline",
                "type": "orders",
                "orderId": "95189138"
            },
            "source": "omnichannel-api",
            "datacenter": "qa",
            "timestamp": "2023-06-02T16:32:15.838009900Z"
        }
    ]
}

Throttling of API requests

The maximum number of concurrent API calls with HTTP method PUT i.e., one order per API request, is 100 calls per second. If using the HTTP method POST, where multiple orders are sent in a single API call, one POST API call can be made with 100 orders per second. Customers are required to throttle the requests made to Omni channel Order API at the rate of 100 orders per second. If the system receives requests above the specified throughput, the API will respond with HTTP 429 Too Many Requests.

When multiple orders (i.e., orders are batched) are sent via POST calls, it is required to gzip the payload where the max payload size is not beyond 100 KB. So, the system will accept up to 100 orders in a batch POST payload as long as the overall compressed payload size is 100 KB or less. In case the system receives an API request payload that has a larger payload than 100 KB, API will respond with HTTP 413 Request Entity Too Large.