The Omni API

Overview

The Omni API supports store associate activities for the following features: ISPU (In-Store PickUp), SFS (Ship-from Store), and STS (Ship-to Store). The API is based on a concept of queues and physical stores. Orders are assigned to physical stores and are in queues.

The relevant default queues are:

• WAITING_FOR_PICK_ISPU
• WAITING_FOR_CUSTOMER_PICK (both ISPU and STS orders)
• WAITING_FOR_PICK_SFS
• WAITING_FOR_PACK_SFS
• WAITING_FOR_CHECKIN_STS
• WAITING_FOR_INSTORE_CHECKIN_STS (STS orders processed as ISPU)
• WAITING_FOR_PICK_DEL
• WAITING_FOR_PACK_DEL
• WAITING_FOR_DELIVERY

While there is a natural flow of orders through these queues for each feature, each queue is completely independent. There is no assumption that a Store Associate will process an order end to end without interruption. For example, an ISPU order could first appear in the WAITING_FOR_PICK_ISPU queue and then the WAITING_FOR_CUSTOMER_PICK queue. An individual Store Associate could process a WAITING_FOR_PICK_ISPU order and then process a different WAITING_FOR_CUSTOMER_PICK order because the customer arrived at the store to pick up an order. Or, in a large store, a single Store Associate could be assigned to process all of the orders in each queue.

Notes

Throughout this API documentation:

• storeId refers to the identifier for your webstore and will probably always be the same.
• nodeId refers to a physical store that was loaded through the ROM UI or the Facility Feed.
• queueId refers to the queue.
• $apiurl is a placeholder; Radial provides the value to you. It is the same for all of your API calls.

The following examples show minimum viable usage of the API. The API reference section lists more calls with additional payload detail.

Retrieve Orders in Queues by Retail Store and Queue

The fulfillmentOrders?queueId API returns all orders in a single queue for a single physical store.

• Call: POST
• URL: (“$apiurl/fulfillmentOrders?queueId=Z”
• JSON Payload: {“storeId”: “X”, “nodeId”: “Y”, “queueId:” “Z”}
• Return Payload (JSON array): [{“storeId”:, “X”, “fulfillmentOrder”: {“storeId”: “X”, “fulfillmentOrderId”: “I”, “carrier”: “C”, “service”: “S”}, “webOrderId”: “B”, “nodeId”: “Y”, “queueId”: “Z”}]

The queueId Z in the URL and queueId Z in the JSON payload must be the same.

You can use this API to create:

• A summary page for all queues and all stores.
• A summary of all queues for one store.
• A list of orders in a queue for a store.

This API also allows you to specify pagination: a number of items per page, and a page number to retrieve.

A standard flow for store fulfillment is to drill down from a page listing counts of orders per store or queue, to a page with counts of orders for each queue within a store, to a page listing orders within a particular queue for a particular store, to the processing of a particular order. Administrators have access to all these pages and associates have access to pages for their particular stores.

• To create a summary of all queues for all stores, loop through all your physical stores and all relevant queues, calling the API once for each queueId and nodeId combination and aggregating or counting the responses.
• To create a summary of all queues in one physical store, call the API once for each queue with the same nodeId, aggregating or counting the responses.
• To create a summary of all physical stores for one queue, call the API once for each store, using the same queueId, aggregating or counting the responses.
• To create a list of all orders in a particular queue assigned to a particular store, call the API once with the queueId and nodeId.

Process Individual Orders in a Queue

All Queues

This API returns details on a single order in a queue.

• Call: POST
• URL: $apiurl/fulfillmentOrders/Y
• JSON Payload: {"storeId": "X", "fulfillmentOrderId": "Y”}
• JSON Return Payload: {“fulfillmentOrder”: {“status”: “X”, “packages”: [], }

The fulfillmentOrderId Y in the URL and the fulfillmentOrderId Y in the JSON payload must match and must be a fulfillmentOrderId returned by the queueId API call.

When a Store Associate decides to process an individual order, you first need to get the detail on that order because:

• The state of the order may have changed, and
• Some of the information returned by the order detail call may be needed for subsequent calls.

The following conditions indicate that the order has been advanced by another Store Associate or is in an error state. Your application should inform the Store Associate if these conditions occur:

• Status is 9000: shipment is canceled.
• Status is 1600.002: shipment is invoiced. If the queue WAITING_FOR_PICK_ISPU, then the order is complete.
• Status is 1600.002.10: The order has been picked up by the customer and is complete.

WAITING_FOR_PICK_ISPU, WAITING_FOR_PICK_SFS, WAITING_FOR_PICK_DEL

To retrieve fulfillment orders from these queues, use PickTicketGenerate and PickTicketUpdate.

1. Make an API call to generate a pick ticket.
   • Call: POST
   • URL: $apiurl/nodes/Y/pickTicket/generate
   • JSON Payload {"storeId": “X '", "nodeId": “Y”, “queueId”: “Z”, "userId": "U", "fulfillmentOrderIds": [“O”]}

     The nodeId Y in the URL and JSON must match, and UserId U must be created in the ROM UI or loaded using the User Feed.

   • Return Payload: {“pickTicketDetails”: [{“pickTicketId”: “A”, “storeId”: “X”, “nodeId”: “Y”, “userId”: “U”, “pickTicketItems”: [{“id”: “I”, “itemDetails”: {“itemId”:“J”}, “quantity”: “K”},…]}]}
2. Make an API call to confirm the pick ticket using values that were returned by the pick ticket generation call.
   • Call: PUT
   • URL: $apiurl/nodes/Y/pickTicket/update
   • JSON Payload: {“pickTicketDetails“: {“pickTicketId”: “A”, “action”: “CONFIRM”, “storeId”: “X”, “nodeId”: “Y”, “userId”: “U”, “holdLocation”: “H”, “pickTicketItems”: [{canceledQuantity”: “L”, “cancellationReasonCode”: “M”, “id”: “I”, “itemId”: “J”, “pickedQuantity”: “N”},…]}

WAITING_FOR_CUSTOMER_PICK

CustomerPickupDetails and CustomerPickupConfirm enable you to get the details on ISPU orders and confirm that the customer has picked them up.

1. Make an API call to get customer pickup details, specifically ordered, picked, and canceled counts for each web line ID in the order.
   • Call: POST
   • URL: $apiurl/nodes/Y/customerPickups/Z
   • JSON Payload: {“storeId”: “X”, “nodeId”: “Y”, “fulfillmentOrderId”: “Z”}

     The nodeId Y in the URL and JSON must match, and the fulfillmentOrderId Z in the URL and JSON must match.

   • JSON Return: {“customerPickUpDetails”: [“customerPickupItems”: [{“webLineId”: “W”, “orderedQuantity”: “Q”, “pickedQuantity”: “QY”, “canceledQuantity”: “QN”, “cancellationReasonCode”, “R”}]]}

   Depending on the programming language you’re using, you may want to put this information into a hash table with the webLineId as the primary key.

2. Make an API call to confirm customer pickup.
   • Call: PUT
   • URL: $apiurl/nodes/Y/customerPickUp/confirm
   • JSON Payload {“customerPickupDetails”: {“fulfillmentOrderId”: “Z”, “storeId”: “X”, “nodeId”: “Y”, “customerPickupItems”: [{“webLineId”: “W”, “itemId”: “I”, “customerPickedQuantity”: “QZ”, “canceledQuantiy”: “QN”, “cancellationReasonCode”: “R”, “backroomPickedQuantity”: “QY”}]}}

   The nodeId Y in the URL and JSON must match.

WAITING_FOR_PACK_SFS and WAITING_FOR_PACK_DEL

Once an order SFS or Associate Delivery order has been successfully picked and confirmed, the Store Associate must pack it and include a pack slip, then ship or deliver it to the customer. PackDetails provides the details on packed orders and PackSlipGenerate creates the pack slip. PackConfirm confirms that the order is packed. Finally, ShipmentConfirm confirms that the package has been shipped.

1. If there are no packages in the details JSON, make an API call to create the packages, and then call details again as described above. This call should be made after the Store Associate has put the items into the cartons and recorded which cartons contain the items in your application.
   • Call: PUT
   • URL: $apiurl/fulfillmentOrders/Z/package/update
   • JSON Payload {“packDetails”: {“storeId”: “X”, “nodeId”: “Y”, “fulfillmentOrderId”: “Z”, “packages”: [{“action”: “CREATE”, “tracking number”: “T”, “boxId”: “B”, “boxWeight”: {“unit”: “LBS”, “value”: “V1”}, “packagingMaterialWeight”: {“unit”: “LBS”, “value”: “V2”}, “packageItems”: [{“itemId”: “I”, “webLineId”: “W”, “quantity”: “Q”}]}]}}

   The fulfillmentOrder Z values in the URL and payload must match

2. Make an API call to generate a pack slip.
   • Call: POST
   • URL: $apiurl/fulfillmentOrders/Z/packslip/generate
   • JSON Payload: {“storeId”: “X”, “nodeId”: “Y”, “modifyAssociateId”: “M”, “fulfillmentOrderId”: “Z”}

   The fulfillmentOrder Z values in the URL and payload must match.

3. Make an API call to confirm packing.
   • Call: POST
   • URL: $apiurl/fulfillmentOrders/Z/packageConfirm
   • JSON Payload {“storeId”: “X”, “nodeId”: “Y”, “fulfillmentOrderId”: “Z”}

   The fulfillmentOrder Z values in the URL and payload must match.

4. Make an API call to confirm shipment.
   • Call: POST
   • URL: $apiurl/fulfillmentOrders/Z/shipmentConfirm
   • JSON Payload {“storeId”: “X”, “nodeId”: “Y”, “fulfillmentOrderId”: “Z”, “carrier”: “C”, “service”: “S”, “packages:” [{“packageId”: “P”, “trackingNumber”: “T”}]}

   The fulfillmentOrder Z values in the URL and payload must match.

WAITING_FOR_CHECKIN_STS and WAITING_FOR_INSTORE_CHECKIN_STS

STS orders must be checked in, whether they are shipped from another store or picked from a single store.

• Make an API call to confirm checkin.
  • POST
  • URL: $apiurl/nodes/Y/fulfillmentOrders/Z/checkin
  • JSON Payload: {“fulfillmentOrder”: {“action”: “CONFIRM”, “storeId”: “X”, “nodeId”: “Y”, “fulfillmentOrderId”: “Z”, “holdLocation:” “H”, “checkInPackages”: [{“checkInPackageId”: “P”, “checkInPackageItems”: [{“itemId”: “I”, “webLineId”: “W”, “quantity”: “Q”, “checkInQuantity”: “QY”, “checkInCanceledQuantity”: “QN”, “checkInCancellationReasonCode”: “R”}]}}}

  The nodeId Y in the URL and JSON must match, and the fulfillmentOrderId Z in the URL and JSON must match.

WAITING_FOR_DELIVERY

When orders are delivered to customers, call the DeliveryConfirm API to confirm the delivery.

• Make an API call to confirm delivery.
  • Call: POST
  • URL: $apiurl/fulfillmentOrders/Z/deliveryConfirm
  • JSON Payload: {“storeId”: “X”, “nodeId”: “Y”, “fulfillmentOrderId”: “Z}

  The nodeId Y in the URL and JSON must match, and the fulfillmentOrderId Z in the URL and JSON must match.

URI Summaries

Customer Pickup API

Fulfillment Order API

Hold Ticket API

Pick Ticket API

Putaway API

Alert API

Pack Slip API

Delivery API

Shipment API

Check-In API (STS)

URI domain name: Radial recommends using the new domain at apg.radial.com. To connect to production Radial APIs, use the following form of the URL:

https://apg.radial.com/v1.0/proxyname/storecode/function

You should have received the applicable information for proxyname, storecode, and function from your Radial representative.

Note: The old domain will still be in operation until further notice from Radial. For more information on Radial API URIs, see API Requests and Responses.

Error Definitions

Order Error

Order Error Codes and HTTP Error Statuses

Error Payload Example

{
    "code": "MISMATCHED_IDENTIFIERS",
    "description": "Mismatched path and body identifiers.",
    "causes": [
        "Mismatched path and body identifiers. storeId: TMSUS vs PETUS"
    ]
}