The Order API provides the main interaction for placing an order, retrieving order information, and performing actions on an existing order.

URI Summary

Order URIs use the service identifier orders.

Operation

Action

URI Template

URI Example

Transaction Type

Unique RequestID Needed for Duplicate Detection?

Non-URI Request Payload

Create Order (XML)

POST

/vM.m/stores/STOREID/orders/create.format

/v1.0/stores/ABCD/orders/create.xml

Create new order.

Yes

Order-Service-Create-1.0.xsd

Get Order Detail

POST

/vM.m/stores/STOREID/orders/get.format

/v1.0/stores/ABCD/orders/get.xml

Search for order by shopper's order number.

No

Order-Service-Detail-1.0.xsd

Get Related Orders

POST

/vM.m/stores/STOREID/orders/relatedOrders/get.format

/v1.0/stores/ABCD/orders/relatedOrders/get.xml

Search for all orders related to a specified order number.

No

Order-Service-RelatedOrderSearch-1.0

Cancel Order

POST

/vM.m/stores/STOREID/orders/cancel.format

/v1.0/stores/ABCD/orders/cancel.xml

Cancel existing order.

No

Order-Service-Cancel-1.0

Get Orders by Customer ID

POST

/vM.m/stores/STOREID/customers/orders/get.format

/v1.0/stores/ABCD/customers/orders/get.xml

Search for order by customer ID.

No

Order-Service-Search-1.0

Order Price Adjustment

POST

/vM.m/stores/STOREID/orders/priceadjustment/get.format

/v1.0/stores/ABCD/orders/priceadjustment/get.xml

Adjust order price.

No

Order-Service-PriceAdjustment-1.0.xsd

Order Line Cancel

POST

/vM.m/stores/STOREID/orders/linecancel/get.format

/v1.0/stores/ABCD/orders/linecancel/get.xml

Cancel line item on order.

No

Order-Service-LineCancel-1.0.xsd

Get Return Labels

POST

/vM.m/stores/STOREID/orders/returnlabels/get.format

/v1.0/stores/ABCD/orders/returnlabels/get.xml

Create return labels for an order.

No

Order-Service-ReturnLabels-1.0.xsd

Gift Search

POST

/vM.m/stores/STOREID/orders/giftsearch.format

/v1.0/stores/ABCD/orders/giftsearch/get.xml

Search for a gift order.

No

Order-Service-GiftSearch-1.0.xsd

Create Reship

POST

/vM.m/sellers/{sellerId}/orders/{orderId}/reship

/v1.0/stores/TMSUS/order-manage/orders/1234/reship.json

Create zero cost reship request.

No

Reship-Create-1.0.xsd

Get Reship Details

GET

/vM.m/sellers/{sellerId}/orders/{orderId}/reshipInfo

/v1.0/stores/TMSUS/order-manage/orders/1234/reshipInfo.json

Return information for existing reship request.

No

Reship-Info-1.0.xsd

Hold Order

POST

/vM.m/stores/STOREID/orders/hold.format

/v1.0/stores/ABCD/orders/hold.xml

Place hold on order, or release hold on order.

No

Order-Service-Hold-Request-1.0.xsd

Update Order

POST

/vM.m/stores/STOREID/orders/update.format

/v1.0/stores/ABCD/orders/update.xml

Submit a modified order to replace a previous order that was placed on hold.

No

Order-Service-Update-Request-1.0.xsd

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.

Best Practices

The following best practices help ensure that the Order API processes orders properly.

Order Number Prefix

A unique five-digit numeric channel (order) identifier is assigned to each Radial client. You must add this identifier as a prefix to each order number before the order is submitted to the Order API for processing. The prefix ensures that order numbers are unique among Radial clients. Orders without a valid five-digit prefix on the order number fail.

Customer Number Prefix

A unique five-digit numeric customer (shopper) identifier is assigned to each Radial client. You must add this identifier as a prefix to each customer identifier before you submit the order to the Order API. The prefix ensures that customer identifiers are unique among Radial clients. Once created, the prefixed customer number should be reused for the following reasons:

  • Maintain consistency through the system.
  • Coordinate order history through the system.
  • Help customer service representatives easily and securely look up information for individual customers.

Order Line Numbers

To correlate order line numbers in your e-commece application with order line numbers in the Radial order management system, use the WebLineID parameter and provide a positive integer for each line. These integers are retained and returned in the Order Detail Responses for those items. This allows multiple line items containing products with the same SKU (such as differently valued gift cards) to be reconciled with any order data such as promotions, and to rebuild the shopping cart view in the customer history.

Estimated Delivery Date

Estimated delivery date information received from the Inventory Details Response message is not required and does not have to pass validation to accept an order. The Federal Trade Commission (FTC), however, requires this information for email triggering if a shipment is delayed past a committed time frame.

Order Create Requests

Order create requests for PayPal orders must provide the following values:

Element or Attribute Value
<PaymentAccountUniqueId> PAYPAL
isToken true
<Authorization><ResponseCode> AUTHORIZED (for approved PayPal authorizations)

Order create requests for all other payment types, where an order is eligible for submission, should provide the following values:

Element or Attribute Value
<PaymentAccountUniqueId> Tokenized value returned by the payment authorization response
isToken true
<Authorization><ResponseCode> APPROVED, DECLINE, or TIMEOUT (depending on the payment authorization response)

Fraud Protection

Several required elements in an order create request provide fraud protection. One required element is the <JavaScriptData> element. This element provides a repository for the response from the 41st Parameter’s JavaScript collector code. This collector code must be implemented on the last page of the order completion process. Documentation for the implementation of the JavaScript collector code is included in the file 41stcollectordeployguide.pdf.

JavaScript code components are included in a .zip file provided by Radial. Each code component has examples to demonstrate the correct implementation. The best implementation is to install all collectors on the server page and randomly fire one at run-time. This minimizes the potential for spoofing the collector and making false credit card orders.

Example: Implementation of the JavaScript collector code during the OnSubmit event

Copy this code sample.

<jsp:useBean id="fraudnetScriptProvider"
class="com.foundryinc.cust.gsi.frameworks.webstore_oracle.util.FraudnetScriptProvider"
scope="session"
/>
<% String fraudnetScriptName = fraudnetScriptProvider.getFraudnetScriptName(); %>
...
...
...
<script language="JavaScript" style="behavior:url(#default#clientcaps)" id="clientCapsRef">
<%= fraudnetScriptProvider.getFraudnetScript(fraudnetScriptName) %>
</script>
<script type="text/javascript">
document.observe("dom:loaded", function(e){
Element.observe($('reviewForm'),"submit",function()
{
<%= fraudnetScriptProvider.getFraudnetScriptInvocation(fraudnetScriptName,
"userPrefs") %>
return true;
});
$$('.shipOpt').each(function(v){
v.observe('change', function(e) {
$('reviewForm').insert(new Element('input',
{type:'hidden',name:'_eventId_shippingOptionSelected',value:'1'}));
//disable buttons so IE6 doesn't submit them
$$('button').each(function(v) {
v.disabled = true;
});
$('reviewForm') .submit();
});
});
});
</script>
...
...
<%-- Setting up a hidden form field so as to capture the collected customer browser 
data on the server side for the 41st javascript collector implementation --%>
<input type="hidden" name="userPrefs" id="userPrefs" value="">

Order Status in Response Messages

Order response messages provide two levels of order status:

  • Order detail calls return responses with line-level status (single line for multi-quantity items).
  • Order search and order detail calls return responses with header status. This status provides an overall aggregated status of the entire order, calculated and derived based on the status of individual line items in the order. For a list of commonly used header-level order status values, see Order Fulfillment Workflow and Order Status Values.

An order response message can include one of the following order status response strings:

Response String Status Phase (Informational Only)
Draft Order Created In Process
Created In Process
Pre-Sell Line Created In Process
OGC Line Created In Process
Warranty Line Created In Process
OrderLine Invoiced In Process
Pre-Fulfilled Line Created In Process
Reserved Awaiting Acceptance In Process
Reserved In Process
Being Negotiated In Process
Accepted In Process
Backordered Backordered
Unexected Backorder Backordered
Awaiting Scheduling In Process
Companion Backorder In Process
Accessory Backorder In Process
Unscheduled In Process
Scheduled In Process
Awaiting Chained Order Creation In Process
Chained Order Created In Process
Released In Process
Included In Shipment In Process
Shipped Fulfilled
Ready For Pickup Awaiting Consumer (In-Store pickup only)
Pickup Complete Fulfilled
Pending Pickup Cancel In Process
OrderLineInvoiced Fulfilled
PO Shipped Fulfilled
GC Shipped Fulfilled
GC Activated Fulfilled
Warranty Line Processed Fulfilled
OGC Activated Fulfilled
Fulfilled and Invoiced Fulfilled
Return Created Return In Progress
In-Store Return Created Return In Progress
Dummy Return Created n/a
Return Received Returned
STS Order Cancelled Cancelled (Ship to Store only)
ISPU Order Cancelled Cancelled (In-Store pickup only)
OrderLine Invoiced Fulfilled
PO Shipped higher than fulfilled and invoiced Fulfilled
GC Activated higher than fulfilled and invoiced Fulfilled
GC Shipped higher than fulfilled and invoiced Fulfilled
OGC Activated higher than fulfilled and invoiced Fulfilled
Unreceived In Process
Received Returned
Receipt Closed In Process
Cancelled Cancelled