Skip to main content
RichRelevance

Omnichannel Order API

  1. Last updated
  2. 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 a dedicated channel associated with each order payload. For example Mobile POS, in-Store POS, etc. This will help link specific orders to a specific channel per customer preferences, which will help with reporting.

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/

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/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 previous 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, use the below API request.

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

Example with cURL:

curl -H 'Authorization:Bearer <tokenValue>' https://qa-gateway.richrelevance.com/omnichannel/api/v1/<apiKey>/orders?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

Full URL: https://<host>/omnichannel/api/v1/<apiKey>/orders

'Authorization:Bearer <tokenValue>’

Parameters

Parameter

Mandatory/Optional

Description

apiKey

Mandatory

Unique identifier for a customer's environment - For example, if a customer has multiple environments in production or staging, each will have a unique 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.

 Action and Syntax

Action

Syntax

Import single order

 

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

Update multiple orders

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

 

Omnichannel Order Information (API Body)

Element

Description

Data Type

Optional/ Mandatory

Values

id

Numeric value for each order. At least unique by channel

integer

Mandatory

1723 

channel

The identifier for the channel of this shopper mapping, example, “Store”.  If you are mapping website shopper guids to shopper IDs, the channel ID should be provided that matches the channel ID in the Shopper Guid mapping file. 

string

Optional

store

userId

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

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. 

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.

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": "instore",
  "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": "instore",
  "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?mode=offline

Payload:

{
  "id": 123,
  "channel": "offline",
  "userId": "userC2",
  "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?mode=online

Payload:

{
  "id": 123,
  "channel": "POS",
  "userId": "userC2",
  "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": "POS",
  "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": "mPOS",
  "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
    }
  ]
}
]
 }
  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Reference
  2. Tags
    This page has no tags.