Skip to main content
RichRelevance

Omnichannel Order API

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.

Note:- For the Omnichannel Order API service, the bearer token TTL will be set to 8 hours i.e. 28800 seconds. Once every 8 hours, you are advised to request a new bearer token to continue using the service without any authorization failure.

Creating Tokens

Hosts

Production

https://gateway.richrelevance.com/

QA  

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/api/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/api/v1/oauth2/token?grant_type=client_credentials&client_id=5934de97c95e1ced&client_secret=2l9dr0jkink11ad49hg93it52d

Sample Response

    
{
    "token_type": "bearer",
    "access_token": "TD7IOngu6HBX9bNq8c8nnZzC64Ctg9rL",
    "expires_in": 28800
}
  

Note: The "expires_in" value returned in the OAuth token response indicates the duration of the bearer token's validity in seconds. This directly corresponds to the token's Time to Live (TTL). For example, if "expires_in" is set to 28,800 seconds, the token remains valid for exactly 28,800 seconds, which is 8 hours. After 8 hours, the token will expire, and a new token will need to be requested to continue accessing the API.

Example with cURL:

curl -X POST https://qa-gateway.richrelevance.com/omnichannel/api/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 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

Omnichannel Order Information (API Body)

Element

Description

Data Type

Optional/ Mandatory

Values

id

Alpha-Numeric value for each order. At least unique by channel

string

Mandatory

1723ABC

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.

string

Mandatory

skuId

SKU for the line item. Should correspond to a value provided in the SKU Feed

string

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 MethodPOST

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

Payload:

[{
  "id": 123,
  "channel": "6a700f55b7059e38",
  "userId": "userA2",
  "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 MethodPUT

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 MethodPUT

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 MethodPOST

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

Omnichannel Return(s) Import 

Edit section

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

Omnichannel Returns syntax for offline order import 

Edit section

Import Multiple Returns Full URL: POST https://<host>/omnichannel/api/v1/<apiKey>/returns

'Authorization:Bearer <tokenValue>’

Parameters 

Edit section

Parameter

Mandatory/Optional

Description

apiKey

Mandatory

apiKey

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

'Authorization:Bearer <tokenValue>’

Parameters 

Edit section

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.

 Action and Syntax 

Edit section

Action

Syntax

Import single order

 

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

Update multiple orders

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

Omnichannel Order Information (API Body) 

Edit section

Element

Description

Data Type

Optional/ Mandatory

Values

orderId

Alpha-Numeric value for each order. At least unique by channel

string

Mandatory

1723bcv

returnId Alpha-Numeric value corresponding to each return. string Mandatory 1989qwe

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.

string

Optional

6a700f55b7059e38

userId

Global Unique Shopper/User ID. Shopper IDs in the returns payload 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

returnValue

Monetary value of all the returns applicable 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.

string

Mandatory

skuId

SKU for the line item. Should correspond to a value provided in the SKU Feed

string

Optional

quantity

Quantity of the items returned

integer

Mandatory

unitPrice

Monetary value paid per unit returned

integer

Mandatory

creditType Did this result in chargeback, cash back, store credit, etc. string Optional

 

Array

Mandatory

{

      "productId": 4556,

      "skuId": "123",

      "quantity": 10,

      "unitPrice": 256.678

    }

 

Example #1

Importing Multiple offline returns

Apikey:- 12345

HTTP MethodPOST

URL: https://gateway.richrelevance.com/omnichannel/api/v1/12345/returns

Payload:

[
  {
    "orderId": 13,
    "returnId": 15,
    "channel": "offline",
    "userId": "user200322Z10",
    "dateTime": "2023-03-09T14:30:00+09:00",
    "emailHash": "emailHash",
    "ccHash": "r4321weetgg",
    "storeId": "Store 234",
    "regionId": -1,
    "returnValue": 100.25,
    "segmentIds": [
      "44",
      "55",
      "3"
    ],
    "segmentNames": [
      "seg1",
      "seg2",
      "seg3"
    ],
    "currency": "EUR",
    "lineItems": [
      {
        "productId": "content__662",
        "skuId": "sku1",
        "quantity": 2,
        "unitPrice": 256.678,
        "creditType": "cash back"
      },
      {
        "productId": "content__680",
        "skuId": "sku2",
        "quantity": 2,
        "unitPrice": 356.678,
        "creditType": "cash back"
      },
      {
        "productId": "content__122",
        "skuId": "sku3",
        "quantity": 2,
        "unitPrice": 456.678,
        "creditType": "cash back"
      }
    ]
  }
]

Example #2

Return a single offline order

Apikey:- 12345

HTTP MethodPUT

URL: https://gateway.richrelevance.com/omnichannel/api/v1/12345/orders/users/userC2

Payload:


{
  "orderId": 13,
  "returnId": 15,
  "channel": "offline",
  "dateTime": "2023-03-09T14:30:00+09:00",
  "emailHash": "emailHash",
  "ccHash": "r4321weetgg",
  "storeId": "Store 234",
  "regionId": -1,
  "returnValue": 100.25,
  "segmentIds": [
    "44",
    "55",
    "3"
  ],
  "segmentNames": [
    "seg1",
    "seg2",
    "seg3"
  ],
  "currency": "EUR",
  "lineItems": [
    {
      "productId": "content__662",
      "skuId": "sku1",
      "quantity": 2,
      "unitPrice": 256.678,
      "creditType": "cash back"
    },
    {
      "productId": "content__680",
      "skuId": "sku2",
      "quantity": 2,
      "unitPrice": 356.678,
      "creditType": "cash back"
    },
    {
      "productId": "content__122",
      "skuId": "sku3",
      "quantity": 2,
      "unitPrice": 456.678,
      "creditType": "cash back"
    }
  ]
}

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/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. 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/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/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.

  • Was this article helpful?