1. Retailers
  2. API
  3. Orders

Orders

An order represents a consumer's request to purchase one or more items from a retailer. After the consumer completes the checkout process on the retailer's website, we expect that the retailer will send the order to RevCascade. Once received and validated by RevCascade, orders may be accessed by vendors for acknowledgement and fulfillment.

Operations

Click on an operation (or scroll down) to view requirements, options, & examples for each operation.

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

The following is a list of ALL order properties. For a list of properties required for a specific request (e.g. a POST), please review the example operations below.

Name Description

id

integer (11)

 A static id assigned to the order by RevCascade. Can be used as the primary key in the url of other order endpoints.

retailer

retailer

The retailer that owns the purchase order (that's probably you!). 

"retailer": {
    "id": 1000,
    "name": "Demo Retailer",
    ...
}

brand

array of brand

The brand or vendor that must fulfill the purchase order. 

"brand": {
    "id": 1000,
    "name": "Demo Brand"
    ...
}

brands

array of brands

deprecated

Array of brands (aka vendors) that must fulfill the purchase order. As of August 2016, this field has been deprecated in favor of a single "brand" field. 

"brands": [{
    "id": 1050,
    "name": "Demo Vendor"
    ...
}]

purchase_order_number

string (32)

 The purchase order number from the retailer's Order Management System.

customer_order_number

string (32)

may be null

 The customer order number (e.g. from eCommerce system) that was shared with the consumer upon checkout. The customer order number may be different than the purchase order number, and should be present if the number is expected to be printed on the packing slip or shipping label.

retailer_order_number

string (32)

may be null

 Additional reference id from an internal retailer platform (e.g. a primary key to a retailer system). Generally only used if the retailer OMS operates on ids other than the PO #.

sold_to

address

may be null

The contact address 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.

"sold_to": {
    "id": "326522",
    "type": "residential",
    "name1": "Thomas K. Bryant ",
    "name2": null,
    "street1": "1332 Hermosa Ave",
    "street2": "Suite #14",
    "city": "Hermosa Beach",
    "province": "CA",
    "postal_code": "90254",
    "country": "US",
    "phone1": "3108675309",
    "phone2": null,
    "fax": null,
    "email": null
}

Note type, name2, street2, phone1, phone2, fax, & email are optional fields, so their values may be null. However, even if the value of a field is null, the field key will still be present. Please review the address documentation for more details.

ship_to

address

The destination address for the order. 

"ship_to": {
    "id": "326523",
    "type": "residential",
    "name1": "Jack Avery",
    "name2": null,
    "street1": "1332 Hermosa Ave",
    "street2": "Suite #14",
    "city": "Hermosa Beach",
    "province": "CA",
    "postal_code": "90254",
    "country": "US",
    "phone1": "3108675309",
    "phone2": null,
    "fax": null,
    "email": null
}

Note type, name2, street2, phone1, phone2, fax, & email are optional fields, so their values may be null. However, even if the value of a field is null, the field key will still be present. Please review the address documentation for more details.

bill_to

address

deprecated

The retailer address where the vendor should send the invoice. Deprecated in favor of a global retailer setting.

ship_from

address

deprecated

The vendors's origin address for fulfillment. Deprecated in favor of shipment-level setting.

shipping_method

object

may be null

A specific shipping service level requested by the consumer. Used when carrier choice and service level is collected and/or pre-determined by the retailer. The carrier object and the generic shipping method object that the shipping method maps to are always nested within the shipping_method. 

"shipping_method": {
    "id": 3,
    "name": "FedEx Ground",
    "code": "FEDEX_GROUND",
    "carrier": {
        "id": 1
        "name": "FedEx",
        "code": "FDEG"
    },
    "generic_shipping_method": {
        "name": "Ground",
        "description": "Should arrive within 3-7 days after processing time",
        "type": "small_parcel"
    }
}

requested_shipping_method

object

may be null

A generic shipping service level requested by the consumer. Used when carrier choice and method is determined by the vendor. Note: This field will be present if shipping_method is not specified. 

"requested_shipping_method": {
    "id": 1,
    "name": "Expedited",
    "description": "Should arrive within 2-3 days after processing time."
}
  • id - static id assigned by RevCascade.
  • name - requested shipping method:
      •   Next Day - should arrive within 1 day after processing time.
      •   Expedited - should arrive within 2-3 days after processing time.
      •   Ground - should arrive within 3-7 days after processing time.
      •   LTL - will arrive via freight and delivered to threshold.
      •   White Glove - will arrive via freight and delivered to room of choice.
  • description - a short description of expected delivery window.

gift_message

array of 64-char strings

optional

A message that may be printed on packing slips or other materials. The message is divided into an arry of lines with a maximum of 64 characters per line. Empty strings may be passed as line breaks. 

"gift_message": [
    "Hello Mary!",
    "Saw this and thought of you.",
    "",
    "- Will"
]

status

string (8)

The current status of the order:

open - All line items are outstanding.

closed - All line items and quantities have been fulfilled.

partial - At least 1 line item has been fulfilled.

canceled - The entire order was canceled.

is_acknowledged

boolean

 Boolean flag that indicates whether the order has been acknowledged by the vendor. When a vendor acknowledges an order, that indicates to the retailer that the vendor intends to fulfill the order.

acknowledge_by

ISO-8601 Datetime

 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

ISO-8601 Datetime

 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

ISO-8601 Datetime

 The date & time when the order was received by RevCascade. Lead time calculations are based on this date and time.

ordered_at

ISO-8601 Datetime

 The date & time when the order was placed by the consumer. There may be a difference between when an order was placed and when an order was received by RevCascade.

acknowledged_at

ISO-8601 Datetime

 The date & time when the order was acknowledged by the vendor. This field is null if the order has not been acknowledged.

pickup_on

ISO-8601 Datetime

 The date & time when the order is scheduled for pickup by a carrier. Usually only relevant and used with LTL orders.

closed_at

ISO-8601 Datetime

 The date & time 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

ISO-8601 Datetime

 The date & time when the order was canceled. This field is null if the order has not been canceled.

order_lines

array of objects

An array or order lines attached to the order.

"order_lines": [{
    "id": "10000",
    "variant": {
        "id": "100084",
        "brand": {
            "id": "501",
            "name": "Marla Cielo",
        },
        "name": "Contemporary Nightstand",
        "description": "Black"
        "identifier": "1234",
        "upc": "123456789456",
        "attributes": [{
            // subset of variant attributes (omitted for brevity)
        }]
    },
    "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,
}]

shipments

array of shipments

 An array of shipments (if any) currently attached to the order.

cancels

array of cancels

 An array of cancels (if any) currently attached to the order.

invoices

array of invoices

 An array of invoices (if any) currently attached to the order.

rmas

array of rmas

 An array of RMAs (if any) currently attached to the order.

credits

array of credits

 An array of credits (if any) currently attached to the order.

memos

array of Memos

coming soon!

 An array of memos (if any) currently attached to the order. This feature is coming soon.

Back to Top

Operation Details & Examples
POST /v1/retailers/{retailer_id}/orders/ Create a new Order
Input Parameters

purchase_order_number

string (32)

required

 A unique PO # from the Retailer's OMS.

customer_order_number

string (32)

optional

 Reference to the customer's order number from the eCommerce system. Should be passed in if the number needs to appear on the packing slip sent to the consumer.

ordered_at

ISO-8601 Datetime

required

 ISO-8601 Timestamp (in UTC) when the order was placed by consumer.

sold_to

address

optional

The consumer was charged for the order. The "Sold To" address is optional, but should be passed to RevCascade if the address needs to appear on the packing slip or be a part of a the gift message. 

"sold_to": {
    "type": "residential"",
    "name1": "Sally Barnes",
    "name2": null,
    "street1": "1332 Hermosa Ave",
    "street2": "Suite 14",
    "city": "Hermosa Beach",
    "province": "CA",
    "postal_code": "90254",
    "country": "US",
    "phone1": "(310) 867-5309",
    "phone2": null,
    "fax": null,
    "email": null
}

Note #1: type, name2, street2, phone1, phone2, fax, & email are not required in the POST. The fields may be explicitly included and have their values set to null or they may be left out of the request altogether. Please DO NOT send empty strings as they will not be ignored.

Note #2: validations are only performed on the province code and the country code.

ship_to

address

required

The destination address. 

"ship_to": {
    "type": "residential"",
    "name1": "John Smith",
    "name2": null,
    "street1": "1332 Hermosa Ave",
    "street2": "Suite 14",
    "city": "Hermosa Beach",
    "province": "CA",
    "postal_code": "90254",
    "country": "US",
    "phone1": "(310) 867-5309",
    "phone2": null,
    "fax": null,
    "email": null
}

Note #1: type, name2, street2, phone1, phone2, fax, & email are not required in the POST. The fields may be explicitly included and have their values set to null or they may be left out of the request altogether.

Note #2: validations are only performed on the province code and the country code. We expect that retailers have performed validations that the address exists.

gift_message

array of 64-char strings

optional

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. Line breaks should be passed in as empty strings (as shown). 

"gift_message": [
    "Hi Mary,",
    "Saw this and thought of you.",
    "",
    "- Will"
]

shipping_method

Shipping Method

required

The shipping method that should be used by the vendor to ship the order. Shipping methods that are allowed for this connection can be looked up using the Connections endpoint. 

"shipping_method": {
    "code": "GROUND",
    "carrier": {
        "code": "UPSN"
    }
}

order_lines

array of Order Lines

required

An array of objects representing the line 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.

  • id - the RevCascade id for the variant. Optional if a valid 'identifier' or 'upc' is passed.
  • identifier - either the retailer sku (if set) or the brand sku. Optional if a valid 'id' or 'upc' is passed'
  • upc - the UPC of the item. Optional if a valid 'id' or 'identifier' is passed.

quantity - The number of items included in the shipment.

net_price - The price that the vendor 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 fields are passed, 'id' will take priority, then 'identifier', then 'upc'.

Example #1 - Creating a simple order

POST https://api.revcascade.com/v1/retailers/500/orders/
Returns 201 CREATED (and the full order object) on success.
{
    "purchase_order_number": "3138720",
    "ordered_at": "2016-07-06T10:25",
    "ship_to": {
        "name1": "Tammy Watkins",
        "street1": "1332 Hermosa Ave. Suite 14",
        "city": "Hermosa Beach",
        "province": "CA",
        "postal_code": "90254",
        "country": "US"
    },
    "shipping_method": {
        "code": "GROUND",
        "carrier": {
            "code": "UPSN"
        }
    },
    "order_lines": [{
        "variant": {
            "identifier": "GBD34315",
        }
        "quantity": 1,
        "net_price": "250.00",
        "price": "450.00"
    }]
}

Example #2 - Creating a more complex order (with sold_to and gift_message)

POST https://api.revcascade.com/v1/retailers/500/orders/
{
    "purchase_order_number": "3138720",
    "ordered_at": "2016-07-06T10:25",
    "sold_to": {
        "name1": "James Watkins",
        "street1": "1332 Hermosa Ave. Suite 14",
        "city": "Hermosa Beach",
        "province": "CA",
        "postal_code": "90254",
        "country": "US"
    },
    "ship_to": {
        "name1": "Tammy Watkins",
        "street1": "1332 Hermosa Ave. Suite 14",
        "city": "Hermosa Beach",
        "province": "CA",
        "postal_code": "90254",
        "country": "US"
    },
    "gift_message": [
        "Hi Tammy!",
        "This one's for you!",
        "",
        "Love Always",
        "Jim"
    ],
    "shipping_method": {
        "code": "GROUND",
        "carrier": {
            "code": "UPSN"
        }
    },
    "order_lines": [{
        "variant": {
            "identifier": "GBD34315",
        }
        "quantity": 1,
        "net_price": "250.00",
        "price": "450.00"
    }]
}

Back to Top

GET /v1/retailers/orders/ Get a list of Orders
Optional Query String Parameters

purchase_order_number

string (32)

 Filter orders based on a purchase order number.

status

string (8)

 Filter orders based on their current status ("open","closed","partial", or "canceled"). Multiple values may be passed in as different parameters (e.g. status=open&status=closed)

is_acknowledged

boolean

 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}

timestamp

 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}

timestamp

 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).

fulfill_by_{operator}

timestamp

 Filter orders by due date 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}

timestamp

 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}

timestamp

 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

integer (3)

 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 vendors.

GET https://api.revcascade.com/v1/retailers/500/orders/?status=open&is_acknowledged=1

Back to Top

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/

Back to Top

Integration
API Guides
API Reference

Products

Transactions

Misc

Monitoring