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