RevCascade Documentation

Shipments

A Shipment represents a package that has a carrier tracking number and contains items from its parent order.

Operations

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

GET	/v1/retailers/{retailer_id}/shipments/	Get a list of shipments
GET	/v1/retailers/{retailer_id}/shipments/{id}/	Get a single shipment
PUT	/v1/retailers/{retailer_id}/shipments/{id}/acknowledge/	Acknowledge shipment

Shipment Properties

The following is a list of ALL shipment properties. For a list of properties required for a specific request, please review the example operations.

Name	Description
id integer (11)	Static identifier for the shipment assigned by RevCascade. Should be used as the {id} in other shipment endpoints.
order_id integer (11)	The id of the order that owns the shipment.
brand brand	The brand or vendor that created the shipment. "brand": { "id": 1000, "name": "Demo Brand" ... }
purchase_order_number string (32)	The purchase order number of the order that owns the shipment.
customer_order_number string (32)	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 shipping label.
ordered_at ISO-8601 Datetime	The date & time (in UTC) when the order was placed by the consumer.
shipping_account object	The shipping account billed for the shipment. "shipping_account": { "id": 14, "nickname": "Sample Retailer FedEx", "carrier": { "id": 1, "name": "FedEx", "code": "FDEG" } }
shipping_method shipping method	The shipping method that was used for the shipment. "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" } }
ship_from address	The shipment origin address printed on the label. "ship_from": { "type": null, "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 }
signature string (16)	Indicates whether or not the carrier should collect a signature from the consumer upon delivery. This property will be set to the string "required" if a signature is required. Otherwise, the value will be null.
ship_weight decimal	The total weight of the carton (in pounds).
ship_width decimal	The width of the carton (in inches).
ship_length decimal	The length of the carton (in inches).
ship_height decimal	The height of the carton (in inches).
ship_girth decimal	The girth of the package calculated using (d1+d2)*2 + d3 where d1 & d2 are the shortest dimensions (in inches).
ship_volume decimal	The volume of the package (in cubic inches).
batch_number integer (11)	An identifier that is assigned to a group of shipments that were generated at the same time. May be disregarded in most cases.
label_reference string (30)	30 character string that may be added to shipping label by the vendor.
tracking_number string (128)	The tracking number of the package supplied by the carrier.
tracking object	Simple object of critical tracking events from the carrier. "tracking": { "picked_up_at": "2016-07-25T19:19:45Z", "delivered_at": null } When available, both values will be ISO-8601 timestamps (in UTC).
shipped_at ISO-8601 Datetime	The date and time (in UTC) that the shipment tracking number was captured and attached to the shipment. The value will be null until thea tracking number is supplied and/or generated by vendor.
acknowledged_at ISO-8601 Datetime	The date and time (in UTC) that the shipment was acknowledged by the retailer. The value will be null until the shipment has been acknowledged.
status string (32)	The status of the shipment. Shipments are "open" when they are initially created and "closed" when the vendor self-reports that the package has been picked up by the carrier. Please note that the "tracking" property is the recommended method to determine whether or not a package has actually been picked up since it leverages the carrier's API.
is_acknowledged boolean	Boolean flag that indicates whether the retailer has received and processed this shipment.
shipment_lines object	An array of shipment line items objects attached to the Shipment. "shipment_lines": [{ "id": "10000", "order_line_number": 1, "part": 1, "variant": { // variant object omitted for brevity } "quantity": 1, }] Please Note: Some items require more than one package to ship. These items will have their "part" property set to a value greater than 1. However, items with part > 1 will still have quantity set to 1. If you intend to count the quantities of items in shipments, you should ignore packages where part is greater than 1.

Name

Description

id

integer (11)

Static identifier for the shipment assigned by RevCascade. Should be used as the {id} in other shipment endpoints.

order_id

integer (11)

The id of the order that owns the shipment.

brand

The brand or vendor that created the shipment.

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

purchase_order_number

string (32)

The purchase order number of the order that owns the shipment.

customer_order_number

string (32)

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 shipping label.

ordered_at

ISO-8601 Datetime

The date & time (in UTC) when the order was placed by the consumer.

shipping_account

object

The shipping account billed for the shipment.

"shipping_account": {
    "id": 14,
    "nickname": "Sample Retailer FedEx",
    "carrier": {
        "id": 1,
        "name": "FedEx",
        "code": "FDEG"
    }
}

shipping_method

shipping method

The shipping method that was used for the shipment.

"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"
    }
}

ship_from

address

The shipment origin address printed on the label.

"ship_from": {
    "type": null,
    "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
}

signature

string (16)

Indicates whether or not the carrier should collect a signature from the consumer upon delivery. This property will be set to the string "required" if a signature is required. Otherwise, the value will be null.

ship_weight

decimal

The total weight of the carton (in pounds).

ship_width

decimal

The width of the carton (in inches).

ship_length

decimal

The length of the carton (in inches).

ship_height

decimal

The height of the carton (in inches).

ship_girth

decimal

The girth of the package calculated using (d1+d2)*2 + d3 where d1 & d2 are the shortest dimensions (in inches).

ship_volume

decimal

The volume of the package (in cubic inches).

batch_number

integer (11)

An identifier that is assigned to a group of shipments that were generated at the same time. May be disregarded in most cases.

label_reference

string (30)

30 character string that may be added to shipping label by the vendor.

tracking_number

string (128)

The tracking number of the package supplied by the carrier.

tracking

object

Simple object of critical tracking events from the carrier.

"tracking": {
    "picked_up_at": "2016-07-25T19:19:45Z",
    "delivered_at": null
}

When available, both values will be ISO-8601 timestamps (in UTC).

shipped_at

ISO-8601 Datetime

The date and time (in UTC) that the shipment tracking number was captured and attached to the shipment. The value will be null until thea tracking number is supplied and/or generated by vendor.

acknowledged_at

ISO-8601 Datetime

The date and time (in UTC) that the shipment was acknowledged by the retailer. The value will be null until the shipment has been acknowledged.

status

string (32)

The status of the shipment. Shipments are "open" when they are initially created and "closed" when the vendor self-reports that the package has been picked up by the carrier. Please note that the "tracking" property is the recommended method to determine whether or not a package has actually been picked up since it leverages the carrier's API.

is_acknowledged

boolean

Boolean flag that indicates whether the retailer has received and processed this shipment.

shipment_lines

object

An array of shipment line items objects attached to the Shipment.

"shipment_lines": [{
    "id": "10000",
    "order_line_number": 1,
    "part": 1,
    "variant": {
        // variant object omitted for brevity
    }
    "quantity": 1,
}]

Please Note: Some items require more than one package to ship. These items will have their "part" property set to a value greater than 1. However, items with part > 1 will still have quantity set to 1. If you intend to count the quantities of items in shipments, you should ignore packages where part is greater than 1.

Back to Top

Operation Details & Examples

GET	/v1/retailers/{retailer_id}/shipments/	Get a list of shipments.

Optional Query String Parameters
is_acknowledged boolean	Boolean filter that returns shipments based on whether or not they have been processed by the retailer. 1 - show only only shipments that have been acknowledged. 0 - show shipments that have not been acknowledged.
is_picked_up boolean	Boolean filter that returns shipments based on whether or not they have been picked up by the carrier. 1 - show only only shipments that have been picked up. 0 - show shipments that are awaiting pickup.
shipped_at_{operator} timestamp	Show only items that have been shipped since 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).
Get all "new" shipments. GET https://api.revcascade.com/v1/retailers/500/shipments/?is_acknowledged=0

Back to Top

GET	/v1/retailers/{retailer_id}/shipments/{id}/	Get a single shipment.

Get a single shipment using the RevCascade shipment id.

GET https://api.revcascade.com/v1/retailers/500/shipments/10065/

Back to Top

PUT	/v1/retailers/{retailer_id}/shipments/{id}/acknowledge/	Acknowledge receipt

Acknowledge receipt of a new shipment.

PUT https://api.revcascade.com/v1/retailers/500/shipments/123645/acknowledge/

Back to Top

Shipments

Operations

Shipment Properties

Operation Details & Examples

Integration

API Guides

API Reference