Orders
An Order represents a Consumer's request to purchase one or more items. After the Consumer completes the checkout process, we expect that you will send the Order to RevCascade. Once received and validated by RevCascade, Orders may be accessed by Suppliers for fulfillment.
Relationships
- Retailer • Orders belong to Retailers.
- Order Lines • Orders can have many Order Lines.
Operations
Click on an Operation to view requirements, options, & examples.
| POST | /v1/retailers/{retailer_id}/orders/ | Create a new Order |
|---|---|---|
| GET | /v1/retailers/{retailer_id}/orders/ | Get a list of Orders |
| GET | /v1/retailers/{retailer_id}/orders/{id}/ | Get a single Order |
Order Properties
| id | A static id assigned by RevCascade. Can be used as the primary key in the url of other Order endpoints. |
|---|---|
| retailer |
The retailer that owns the purchase order. {
"id": 1000,
"name": "Demo Retailer"
}
|
| brands |
Array of suppliers that must fulfill the purchase order. In most cases, this array will contain a single supplier. [{
"id": 1050,
"name": "Demo Vendor"
}]
|
| purchase_order_number | The purchase order number from the Retailer's Order Management System. |
| customer_order_number | The customer order number (e.g. from eCommerce system). Should be present if the number needs to be printed on the packing slip. |
| retailer_order_number (optional) |
Additional reference id from an internal retailer platform (e.g. a primary key to a retailer system) |
| sold_to (optional) |
The contact information of the consumer that was billed for the order. While optional, this field is usually passed in so that it may be printed on the packing slip. {
"name1": "Manchester",
"name2": null,
"street1": "1522 Manchester Rd",
"street2": null,
"city": "",
"province": "OH",
"postal_code": "45458",
"country": "US",
"phone1": null,
"phone2": null,
"fax": null,
"email": null
}
|
| ship_to |
The destination address for the order. {
"type": "residential"",
"name1": "Manchester",
"name2": null,
"street1": "1522 Manchester Rd",
"street2": null,
"city": "West Carrollton",
"province": "OH",
"postal_code": "45458",
"country": "US",
"phone1": null,
"phone2": null,
"fax": null,
"email": null
}
Note: type, name2, street2, phone1, phone2, fax, & email are optional fields |
| shipping_method |
A specific shipping service level requested by the consumer. Used when carrier choice is pre-determined by the retailer. Shipping carrier is nested within the shipping method object. {
"id": 3,
"name": "FedEx Ground",
"code": "FEDEX_GROUND",
"carrier": {
"id": 1
"name": "FedEx",
"code": "FDEG"
}
|
| requested_shipping_method |
A generic shipping service level requested by the consumer. Used when carrier choice is not pre-determined and may be selected by Supplier. {
"id": 1,
"name": "Expedited",
"description": "Should arrive within 2-3 days after processing time."
}
|
| gift_message (optional) |
A message that may be printed on packing slips or other materials. The message is divided into lines with a maximum 64 characters per line. [ "Hello Mary!", "Saw this and thought of you.", "- Will" ] |
| status |
The current status of the order: open - One or more line items are outstanding. closed - All line items and quantities have been fulfilled. canceled - The entire order was canceled. |
| is_acknowledged | Boolean flag that indicates whether the order has been Acknowledged by the Supplier. When a Supplier acknowledges an Order, that indicates to the Retailer that the Supplier intends to fulfill the Order. |
| acknowledge_by | The date & time when the Order is expected to be acknowledged or canceled. This field is determined automatically by RevCascade based on the SLA set by the Retailer. |
| fulfill_by | The date & time when all Line Items on an Order are expected to be completely fulfilled. This field is determined automatically by RevCascade based on a combination of item lead time and the connection's SLA. |
| received_at | The timestamp when the Order was received by RevCascade. Lead time calculations are based on this date and time. |
| ordered_at | The timestamp when the Order was placed by the Consumer. |
| acknowledged_at | The timestamp when the Order was acknowledged by the Supplier. This field is null if the Order has not been acknowledged. |
| closed_at | The timestamp when the Order was closed (i.e. when all items have been completely fulfilled). This field is null if the Order has not been closed. |
| canceled_at | The timestamp when the Order was canceled. This field is null if the Order has not been canceled. |
| order_lines |
An array or Order Line Items attached to the Order. {
"id": "10000",
"variant": {
"id": "100084",
"brand": {
"id": "501",
"name": "Marla Cielo",
},
"name": "Contemporary Nightstand",
"description": "Black"
"identifier": "1234",
"upc": "123456789456",
"attributes": [{
// subset of attributes
}]
},
"quantity": 1,
"quantity_shipped": 0,
"quantity_returned": 0,
"quantity_canceled": 0,
"net_price": "39.00",
"price": "68.00",
"subtotal": "68.00",
"status": "open",
"canceled_at": null,
}
id - RevCascade's static identifier for the Order Line. variant - The exact item that was sold. quantity - The number of items ordered. quantity_shipped - Items that have shipped to date. quantity_returned - Items that have been fully returned to date. quantity_canceled - Items that have been canceled to date. net_price - The price that the supplier expects to be paid for the item. price - The price the consumer was charged for the item(s). subtotal - The subtotal the consumer was charged for the item(s). status - The current status of the Line Item ("open","closed") |
| shipments | An array of Shipments currently attached to the order. |
| cancels | An array of Cancellations attached to the order. |
| invoices | An array of Invoices attached to the order. |
Examples
| POST | /v1/retailers/{retailer_id}/orders/ | Create a new Order |
|---|
| Input Parameters - All fields required unless otherwise marked. | |
| purchase_order_number | A unique PO # from the Retailer's OMS. |
|---|---|
| customer_order_number (optional) | Reference to the customer's order number. Should be passed in if the value needs to appear on the packing slip. |
| ordered_at | ISO-8601 Timestamp (in UTC) when the order was placed by consumer. |
| sold_to (optional) |
The consumer that purchased the items. Optional, but can be occasionally useful for customer service issues. "sold_to": {
"type": "residential"",
"name1": "Manchester",
"name2": null,
"street1": "1522 Manchester Rd",
"street2": null,
"city": "West Carrollton",
"province": "OH",
"postal_code": "45458",
"country": "US",
"phone1": null,
"phone2": null,
"fax": null,
"email": null
}
|
| ship_to |
The destination address. "ship_to": {
"type": "residential"",
"name1": "Manchester",
"name2": null,
"street1": "1522 Manchester Rd",
"street2": null,
"city": "West Carrollton",
"province": "OH",
"postal_code": "45458",
"country": "US",
"phone1": null,
"phone2": null,
"fax": null,
"email": null
}
Note: type, name2, street2, phone1, phone2, fax, & email are not required. |
| gift_message |
An optional gift message that can be printed on packing slip. Each line has a 64 character limit, and should be passed in as an element of an array. "gift_message": [
"Hi Mary,",
"Saw this and thought of you.",
"- Will"
]
|
| shipping_method |
The shipping method that should be used by the supplier to ship the order. Shipping methods that are allowed for this connection can be looked up using the Connections endpoint. "shipping_method": {
"id": 3,
"name": "FedEx Ground",
"code": "FEDEX_GROUND",
"carrier": {
"id": 1
"name": "FedEx",
"code": "FDEG"
}
|
| order_lines |
An array of objects representing the items that are in the order. Please send one Order Line per unique item. "order_lines": [{
"variant": {
"id": 1000065,
"identifier": "GBD34315",
"upc": "123456789012",
}
"quantity": 1,
"net_price": "250.00",
"price": "450.00"
}]
variant - an object that identifies the exact item that sold.
quantity - The number of items included in the shipment. net_price - The price that the supplier expects to be paid for the item. price - The gross per unit selling price of the item. Please note... Either an 'id', 'identifier', or a 'upc' is required in the variant object when creating an order line. However, if multiple are passed, 'id' will take priority over 'identifier' and 'upc'. |
|
Response On a successful POST, a full Order object will be returned. POST https://api.revcascade.com/v1/retailers/500/orders/ (POST body redacted for brevity) HTTP/1.1 201 CREATED {
"id": 13544,
"customer_order_number": "1267572387",
"purchase_order_number": "123456-76",
"retailer_order_number": null,
"retailer": {
"id": 1121,
"name": "Crate & Barrel",
"code": "crate-and-barrel"
},
"brands": [
{
"id": 1028,
"name": "Sample CB Vendor",
"code": "sample-cb-vendor"
}
],
"shipping_method": {
"id": 1,
"name": "UPS Ground",
"code": "Ground",
"type": "small_parcel",
"carrier": {
"id": 2,
"name": "UPS",
"code": "UPSN"
},
"generic_shipping_method": null
},
"requested_shipping_method": null,
"shipment_count": 0,
"bill_to": {
"type": null,
"name1": "",
"name2": "",
"street1": "",
"street2": "",
"city": "",
"province": "",
"postal_code": "",
"country": "",
"phone1": "",
"phone2": "",
"fax": "",
"email": ""
},
"sold_to": {
"id": 6040,
"type": null,
"name1": "Kyle Stainer",
"name2": null,
"street1": "1182 Broadway",
"street2": "#10C",
"city": "New York",
"province": "NY",
"postal_code": "10001",
"country": "US",
"phone1": null,
"phone2": null,
"fax": null,
"email": null
},
"ship_to": {
"id": 6041,
"type": null,
"name1": "Kyle Stainer",
"name2": null,
"street1": "1332 Hermosa Ave.",
"street2": "Suite 14",
"city": "Hermosa Beach",
"province": "CA",
"postal_code": "90254",
"country": "US",
"phone1": null,
"phone2": null,
"fax": null,
"email": null
},
"gift_message": [],
"ship_from": null,
"subtotal_charged": "84.00",
"status": "open",
"is_acknowledged": false,
"ordered_at": "2016-07-07T01:25:00Z",
"acknowledged_at": null,
"fulfill_by": "2016-07-09T01:25:00Z",
"closed_at": null,
"received_at": "2016-07-11T16:59:46.901008Z",
"pickup_on": null,
"canceled_at": null,
"updated_at": "2016-07-11T16:59:46.937182Z",
"order_lines": [
{
"id": 2588,
"order_line_number": "",
"quantity": 2,
"quantity_shipped": 0,
"quantity_returned": 0,
"quantity_canceled": 0,
"price": "42.00",
"fulfill_by": "2016-07-09T01:25:00Z",
"net_price": "21.00",
"shipping_charged": "0.00",
"subtotal_charged": "84.00",
"subtotal": "84.00",
"tax_charged": "0.00",
"status": "open",
"canceled_at": null,
"variant": {
"id": 31384,
"name": "WoodLeg Dining Side Chair, Black",
"brand": {
"id": 1028,
"name": "Sample CB Vendor",
"code": "sample-cb-vendor"
},
"identifier": "CB12339",
"upc": "0703610285965",
"media": [
{
"media": "5f84940f437a4d98b79b92ccc84d71d2",
"priority": 1,
"url": "https://images.revcascade.com/media/5100/original"
}
],
"attributes": [
// redacted for brevity
],
"description": "Black Contemporary/Modern"
}
}
],
"cancels": [],
"shipments": [],
"attachments": []
}
|
|
| GET | /v1/retailers/orders/ | Get a list of Orders |
|---|
| Optional Query String Parameters | |
| purchase_order_number | Filter orders based on a purchase order number. |
|---|---|
| status | Filter orders based on their current status ("open","closed" or "canceled"). Multiple values may be passed in as different parameters (e.g. status=open&status=closed) |
| is_acknowledged |
Boolean filter that returns orders based on whether or not they have been acknowledged.
1 - show only only orders that have been acknowledged. 0 - show orders that have not been acknowledged. |
| ordered_at_{operator} |
Filter orders placed before or after an epoch timestamp in UTC.
Please substitute {operator} with "lt" (less than),"lte" (less than or equal), "gt" (greater than), or "gte" (greater than or equal). |
| received_at_{operator} |
Filter orders received by RevCascade before or after an epoch timestamp in UTC.
Please substitute {operator} with "lt" (less than),"lte" (less than or equal), "gt" (greater than), or "gte" (greater than or equal). |
| acknowledged_at_{operator} |
Filter orders that were acknowledged before or after an epoch timestamp in UTC.
Please substitute {operator} with "lt" (less than),"lte" (less than or equal), "gt" (greater than), or "gte" (greater than or equal). |
| closed_at_{operator} |
Filter orders closed (i.e. completely fulfilled) before or after an epoch timestamp in UTC.
Please substitute {operator} with "lt" (less than),"lte" (less than or equal), "gt" (greater than), or "gte" (greater than or equal). |
| limit | Customize the number of results return (max 250). Requests that return more records than the limit will be paginated. |
|
Get all new Orders GET https://api.revcascade.com/v1/retailers/500/orders/?is_acknowledged=0 |
|
|
Get all open Orders that have been acknowledged by Suppliers GET https://api.revcascade.com/v1/retailers/500/orders/?status=open&is_acknowledged=1 |
|
| GET | /v1/retailers/{retailer_id}/orders/{id}/ | Get a single Order |
|---|
|
Get a single Order by its ID. GET https://api.revcascade.com/v1/retailers/500/orders/100000/ |
