A delivery is an inbound shipment of your product to RSF. It could be an “ASN” (Advanced Shipment Notification), an “RMA” (Return Merchandise Authorization) or an “Other Delivery” (anything other than an ASN or RMA). They are all processed similarly regardless of which type of delivery is specified. Processing involves the general stages of “Accepting” the container from the carrier and weighing it, “Processing” the containers to align what was expected with what was actually received, “Putting Away” the processed inventory and “Committing” the put-away inventory to the available inventory. “Accepting” stage results with “Accepted” or “Ready To Process” delivery status. If the delivery has items on it before it is accepted, “Ready To Process” status is set and “Accepted” status skipped. Most of these steps happen automatically depending on the merchant’s configuration and whether or not there are any exceptions (discrepancies between expected and received).

Methods


Entity Properties


delivery.search(null|object $filters, array $options = []) Retrieve list of deliveries. Filtration could be applied.

Parameters

filters
null | object
  • null - Retrieve list of all deliveries.
  • object - Retrieve list of deliveries using specified Search Filters. Allowed properties for filtering: “delivery_id”, “increment_id”, “warehouse_id”, “merchant_ref”, “merchant_status”, “total_skus”, “delivery_type”, “status”, “sender_name”, “expected_delivery”, “sender_ref”, “sender_ref_alt”, “created_at”, “updated_at”, “comments”, “tracking_numbers”.
options
null | object
  • null - No options will be applied.
  • object - Apply specified Search Options.

Return Value

An array of objects. Each object will contain Delivery Properties.

Example Request

Get delivery for one delivery id:
Request
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "delivery.search",
        [
            {
                "delivery_id" : {
                    "eq" : 1
                }
            },
            []
        ]
    ]
}

Example Response

Response
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : {
        "results" : [
            {
                "delivery_id" : 1,
                "warehouse_id" : 1,
                "increment_id" : "1000036",
                "delivery_type" : "asn",
                "state" : "complete",
                "status" : "put_away",
                "progress" : 100,
                "total_skus" : 2,
                "sender_name" : "Microsoft",
                "carrier_name" : "FedEx",
                "expected_delivery" : "2014-06-26",
                "delivered_at" : "2014-07-21T08:52:56+00:00",
                "ready_to_process_at" : "2014-07-21T08:52:56+00:00",
                "processed_at" : "2014-07-21T09:22:36+00:00",
                "putaway_at" : "2014-07-21T11:24:05+00:00",
                "completed_at" : null,
                "comments" : null,
                "merchant_ref" : null,
                "merchant_status" : null,
                "sender_ref" : null,
                "sender_ref_alt" : null,
                "num_containers" : 2,
                "num_labels" : 1,
                "total_container_weight" : null,
                "total_container_weight_unit" : null,
                "total_product_weight" : null,
                "total_product_weight_unit" : null,
                "special_requirements" : null,
                "auto_commit" : 2,
                "auto_close" : 2,
                "created_at" : "2014-06-26T13:47:47+00:00",
                "updated_at" : "2014-06-26T14:09:30+00:00",
                "items" : [
                    {
                        "delivery_item_id" : 1,
                        "delivery_id" : 1,
                        "product_id" : 214,
                        "qty" : 1,
                        "qty_expected" : 0,
                        "qty_received" : 1,
                        "qty_shortage" : 0,
                        "qty_overage" : 5,
                        "qty_processed" : 1,
                        "qty_putaway" : 1,
                        "qty_committed" : 0,
                        "sku" : "product2",
                        "item_ref" : "ref_123456"
                    },
                    {
                        "delivery_item_id" : 2,
                        "delivery_id" : 1,
                        "product_id" : 213,
                        "qty" : 1,
                        "qty_expected" : 0,
                        "qty_received" : 1,
                        "qty_shortage" : 0,
                        "qty_overage" : 0,
                        "qty_processed" : 1,
                        "qty_putaway" : 1,
                        "qty_committed" : 0,
                        "sku" : "product1",
                        "item_ref" : null
                    }
                ],
                "containers" : [
                    {
                        "container_id" : 1,
                        "delivery_id" : 1,
                        "container_type_id" : 1,
                        "damage_type" : "none",
                        "weight_discrepancy" : "none",
                        "tare_weight" : 1,
                        "tare_weight_unit" : "lb",
                        "weight" : 8,
                        "weight_unit" : "lb",
                        "weighed_at" : "2014-06-26T13:49:04+00:00",
                        "weighed_by" : 1,
                        "contents" : [
                            {
                                "delivery_item_id": 1,
                                "qty_counted": 6,
                                "qty_shortage": 0
                            }
                        ],
                        "notes" : null
                    },
                    {
                        "container_id" : 2,
                        "delivery_id" : 1,
                        "container_type_id" : 1,
                        "damage_type" : "none",
                        "weight_discrepancy" : "none",
                        "tare_weight" : 1,
                        "tare_weight_unit" : "lb",
                        "weight" : 3,
                        "weight_unit" : "lb",
                        "weighed_at" : "2014-06-26T13:49:15+00:00",
                        "weighed_by" : 1,
                        "contents" : [
                            {
                                "delivery_item_id": 2,
                                "qty_counted": 1,
                                "qty_shortage": 0
                            }
                        ],
                        "notes" : null
                    }
                ],
                "exceptions" : [
                    {
                        "delivery_exception_id" : 1,
                        "delivery_id" : 1,
                        "delivery_item_id" : 1,
                        "container_id" : 2,
                        "status" : "pending",
                        "sign" : 1,
                        "reason" : "overage_counted",
                        "comment" : null,
                        "qty" : 5
                    }
                ]
            }
        ],
        "totalCount" : 1,
        "numPages" : 1
    }
}

Error Codes

codemessage
101Invalid filters given. Details in error message.

delivery.create

delivery.create(number $deliveryType, object $data, null|array $items = null) Create delivery.

Parameters

deliveryType
string
Delivery type. Allowed: “asn”, “rma”, “other”.
data
object
Delivery data. See Delivery Properties.
items
null | array
  • null - Create delivery without items.
  • array - Array of objects with two properties: “sku” and “qty”.

Return Value

Delivery information.

Example Request

Request
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "delivery.create",
        [
            "asn",
            {
                "warehouse_id" : 1,
                "auto_commit" : 2,
                "auto_close" : 2,
                "sender_name" : "Bill Gates",
                "carrier_name" : "FedEx",
                "expected_delivery" : "2014-07-31",
                "merchant_ref" : "Inv 12345"
            },
            [
                {
                    "sku" : "product1",
                    "qty" : 5,
                    "item_ref" : "ref_123456"
                },
                {
                    "sku" : "product2",
                    "qty" : 1
                }
            ]
        ]
    ]
}

Example Response

Response
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : {
        "delivery_id" : 4,
        "increment_id" : "1000039",
        "delivery_type" : "asn",
        "state": "new",
        "status": "new",
        "progress": 0,
        "total_skus": 1,
        "sender_name" : "Bill Gates",
        "carrier_name" : "FedEx",
        "expected_delivery" : "2014-07-31",
        "delivered_at": null,
        "ready_to_process_at": null,
        "processed_at": null,
        "putaway_at": null,
        "completed_at": null,
        "comments": null,
        "merchant_ref" : 12345,
        "merchant_status": null,
        "sender_ref": null,
        "sender_ref_alt": null,
        "num_containers": null,
        "num_labels": 0,
        "total_container_weight": null,
        "total_container_weight_unit": null,
        "total_product_weight": null,
        "total_product_weight_unit": null,
        "special_requirements": null,
        "auto_commit": 2,
        "auto_close": 2,
        "created_at" : "2014-07-31T14:10:00+00:00",
        "updated_at" : "2014-07-31T14:10:00+00:00",
        "warehouse_id" : 1
    }
}

Error Codes

codemessage
107Error creating the delivery. Details in error message.

delivery.labels

delivery.labels(string $incrementId, null|array $fields = []) Retrieve list of labels for the given delivery.

Parameters

incrementId
string
Delivery increment id
fields
null | array
  • null - Basic label data.
  • array - Array of fields. Allowed: “packages”, “destination_address”, “origin_address”

Return Value

An array of objects. Each object will contain Delivery Label Properties.

Example Request

Get labels for the delivery:
Request
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "delivery.labels",
        [
            "1000055",
            [
                "packages",
                "destination_address",
                "origin_address"
            ]
        ]
    ]
}

Example Response

Response
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result": [
        {
            "label_id": "8",
            "delivery_id": "26",
            "warehouse_id": "1",
            "status": "valid",
            "shipping_label": "ups_03",
            "created_at": "2021-01-20T10:03:55+00:00",
            "updated_at": "2021-01-20T10:04:01+00:00",
            "packages": [
                {
                    "warehouse_id": "1",
                    "label_id": "8",
                    "carrier": "ups",
                    "weight": "18.000",
                    "weight_unit": "lb",
                    "dimensions": {
                        "length": "10.000",
                        "width": "11.000",
                        "height": "12.000"
                    },
                    "dimension_unit": "in",
                    "tracking": [
                        {
                            "number": "1Z49R7V89024431506",
                            "description": "UPS Ground"
                        }
                    ],
                    "package_items": [
                        {
                            "delivery_item_id": 2,
                            "sku": "O-VS-Oregano-p3",
                            "quantity": "4.000"
                        },
                        {
                            "delivery_item_id": 3,
                            "sku": "O-VS-Mint-p2",
                            "quantity": "4.000"
                        },
                        {
                            "delivery_item_id": 5,
                            "sku": "VS-Bags-p1",
                            "quantity": "4.000"
                        }
                    ]
                }
            ],
            "destination_address": {
                "region": "New York",
                "postcode": "13088",
                "lastname": "Marquez",
                "street": "4616 Crossroads Park Dr",
                "city": "Liverpool",
                "email": null,
                "telephone": "865-971-4663",
                "firstname": "Sherlock",
                "company": null,
                "classification": "com",
                "is_valid": null,
                "country": "US"
            },
            "origin_address": {
                "region": "New York",
                "postcode": "10036",
                "lastname": "Gates",
                "street": "11 Times Square",
                "city": "New York",
                "email": null,
                "telephone": "212.245.2100",
                "firstname": "Bill",
                "company": "Microsoft",
                "classification": null,
                "is_valid": null,
                "country": "US"
            }
        },
        {
            "label_id": "9",
            "delivery_id": "26",
            "warehouse_id": "1",
            "status": "valid",
            "carrier": "ups",
            "created_at": "2021-01-20T10:04:23+00:00",
            "updated_at": "2021-01-20T10:04:26+00:00",
            "packages": [
                {
                    "warehouse_id": "1",
                    "label_id": "9",
                    "carrier": "ups",
                    "weight": "27.000",
                    "weight_unit": "lb",
                    "dimensions": {
                        "length": "10.000",
                        "width": "11.000",
                        "height": "12.000"
                    },
                    "dimension_unit": "in",
                    "tracking": [
                        {
                            "number": "1Z49R7V89021837511",
                            "description": "UPS Ground"
                        }
                    ],
                    "package_items": [
                        {
                            "delivery_item_id": 2,
                            "sku": "O-VS-Oregano-p3",
                            "quantity": "6.000"
                        },
                        {
                            "delivery_item_id": 3,
                            "sku": "O-VS-Mint-p2",
                            "quantity": "6.000"
                        },
                        {
                            "delivery_item_id": 5,
                            "sku": "VS-Bags-p1",
                            "quantity": "6.000"
                        }
                    ]
                }
            ],
            "destination_address": {
                "region": "New York",
                "postcode": "13088",
                "lastname": "Marquez",
                "street": "4616 Crossroads Park Dr",
                "city": "Liverpool",
                "email": null,
                "telephone": "865-971-4663",
                "firstname": "Sherlock",
                "company": null,
                "classification": "com",
                "is_valid": null,
                "country": "US"
            },
            "origin_address": {
                "region": "New York",
                "postcode": "10036",
                "lastname": "Gates",
                "street": "11 Times Square",
                "city": "New York",
                "email": null,
                "telephone": "212.245.2100",
                "firstname": "Bill",
                "company": "Microsoft",
                "classification": null,
                "is_valid": null,
                "country": "US"
            }
        }
    ]
}

Error Codes

codemessage
100Requested delivery does not exist.

delivery.update

delivery.update(string $incrementId, array|null $data = null, array|null $addItems = null, array|null $removeItems = null) Update delivery attributes. Add products. Remove products.

Parameters

incrementId
string
Increment ID.
data
object
Delivery data. See Delivery Properties.
addItems
null | array
  • null - Update delivery without adding items.
  • array - Array of objects with two properties: “sku” and “qty”.
removeItems
null | array
  • null - Update delivery without removing items.
  • array - Array of objects with two properties: “sku” and “qty”.

Return Value

true if delivery was successfully updated.

Example Request

Request
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "aebdb4cc6f861c79428768923f0eb6a2",
        "delivery.update",
        [
            "10000011",
            {
                "merchant_ref" : "Inv 12345",
                "merchant_status": "new",
                "sender_name" : "Bill Gates",
                "sender_ref": "100000004",
                "sender_ref_alt": "100000001",
                "expected_delivery" : "2014-07-31",
                "carrier_name": "FedEx",
                "auto_commit": 1,
                "auto_close": 1,
                "comments": "This delivery was updated via API"                
            },
            [
                {
                    "sku": "O-VS-Oregano-p3",
                    "qty": "6.000",
                    "item_ref": "ref_456"
                }
            ],
            [
                {
                    "sku": "O-VS-Oregano-p3",
                    "qty": "3.000"
                }
            ]
        ]
    ]
}

Example Response

Response
{
    "result": true,
    "id": "1234",
    "jsonrpc": "2.0"
}

delivery.close

delivery.close(string $incrementId) Close a delivery.

Parameters

incrementId
string
The “Increment ID” property.

Return Value

true if delivery inventory was successfully closed.

Example Request

Request
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "aebdb4cc6f861c79428768923f0eb6a2",
        "delivery.close",
        [
            "11000011"
        ]
    ]
}

Example Response

Response
{
    "result": true,
    "id": "1234",
    "jsonrpc": "2.0"
}

Error Codes

codemessage
115Delivery with the specified ID cannot be closed. Details in the error message.

delivery.commit

delivery.commit(string $incrementId, boolean $close = FALSE) Commit delivery inventory.

Parameters

incrementId
string
The “Increment ID” property.
close
boolean
true to close the delivery.

Return Value

true if delivery inventory was successfully committed.

Example Request

Request
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "aebdb4cc6f861c79428768923f0eb6a2",
        "delivery.commit",
        [
            "11000011"
        ]
    ]
}

Example Response

Response
{
    "result": true,
    "id": "1234",
    "jsonrpc": "2.0"
}

Error Codes

codemessage
113Delivery with the specified ID cannot be committed. Details in the error message.

delivery.cancel

delivery.cancel(string $incrementId) Cancel delivery.

Parameters

incrementId
string
The “Increment ID” property.

Return Value

true if delivery was successfully canceled.

Example Request

Request
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "aebdb4cc6f861c79428768923f0eb6a2",
        "delivery.cancel",
        [
            "11000017"
        ]
    ]
}

Example Response

Response
{
    "result": true,
    "id": "1234",
    "jsonrpc": "2.0"
}

Error Codes

codemessage
112Delivery with the specified ID cannot be canceled. Details in the error message.

delivery.void

delivery.void(string $incrementId) Cancel delivery.

Parameters

incrementId
string
The “Increment ID” property.

Return Value

true if delivery was successfully voided.

Example Request

Request
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "aebdb4cc6f861c79428768923f0eb6a2",
        "delivery.void",
        [
            "11000018"
        ]
    ]
}

Example Response

Response
{
    "result": true,
    "id": "1234",
    "jsonrpc": "2.0"
}

Error Codes

codemessage
114Delivery with the specified ID cannot be voided. Details in the error message.

Entity Properties

Delivery Properties

Property Translations: API to UI

APIASNRMAOther
sender_nameSupplierCustomer NameSender
sender_refSupplier Invoice Ref(deprecated, use tracking_numbers )Sender Ref 1
sender_ref_altSupplier Order RefMerchant Order #Sender Ref 2
tracking_numbersTracking NumbersTracking NumbersTracking Numbers
merchant_refMerchant RefMerchant RMA #Merchant Ref
merchant_statusMerchant StatusMerchant StatusMerchant Status
expected_deliveryExpected Delivery DateAuthorization DateExpected Delivery Date
delivery_id
integer
The internal delivery ID.
warehouse_id
integer
The internal warehouse ID.
increment_id
string
The “Increment ID” property.
delivery_type
string
The “Delivery Type” property. Allowed: “asn”, “rma”, “other”.
state
string
The “State” property. Allowed: “new”, “processing”, “putting_away”, “pending_commit”, “complete”, “canceled”.
status
string
The “Status” property. Allowed: “new”, “accepting”, “accepted”, “ready_to_process”, “processing”, “processing_exception”, “processed”, “putting_away”, “put_away”, “complete”, “canceled”, “void”.
progress
integer
The “Progress” property. Number from 0 to 100.
total_skus
integer
Total amount of SKUs.
sender_name
string
The “Sender Name” property.
carrier_name
string
The “Carrier Name” property.
expected_delivery
string
The “Expected Delivery” property.
delivered_at
string
The “Delivered At” property.
ready_to_process_at
string
The “Delivered At” property.
processed_at
string
The “Processed At” property.
putaway_at
string
The “Put-Away At” property.
completed_at
string
The “Completed At” property.
comments
string
The “Comments” property.
merchant_ref
string
The “Merchant Reference” property. Uniqueness based on this field is enforced so an error will be given if a delivery with the same merchant_ref already exists.
merchant_status
string
The “Merchant Status” property.
sender_ref
string
The “Sender Reference” property. Do not use this field for RMAs.
sender_ref_alt
string
The “Sender Reference Alt” property.
tracking_numbers
array
The “Tracking Numbers” property.
num_containers
integer
Number of containers.
num_labels
integer
Number of labels.
total_container_weight
number
The “Total Container Weight” property.
total_container_weight_unit
string
The unit of measure used for total_container_weight. See: Weight Units.
total_product_weight
number
The “Total Product Weight” property.
total_product_weight_unit
string
The unit of measure used for total_product_weight. See: Weight Units.
special_requirements
string
The “Special Requirements” property.
auto_commit
integer
Determines whether inventory will be commited automatically upon put-away completion. 0 - Disabled, 1 - Enabled, 2 - Use default from config
auto_close
integer
Determines whether the delivery will be closed automatically upon acceptance of the last container. 0 - Disabled, 1 - Enabled, 2 - Use default from config
created_at
string
The “Created At” property.
updated_at
string
The “Updated At” property.
items
array
Array of delivery items. See Delivery Item Properties.
containers
array
Array of containers. See Container Properties.
exceptions
array
Array of exceptions. See Exception Properties.

Delivery Item Properties

delivery_item_id
integer
The internal delivery item ID.
delivery_id
integer
The internal delivery ID.
product_id
integer
The internal product ID.
qty
integer
The quantity that was set when the delivery was created or edited.
qty_expected
integer
The quantity that is expected to be received in the future.
qty_received
integer
The “Received” quantity.
qty_shortage
integer
The “Shortage” quantity.
qty_overage
integer
The “Overage” quantity.
qty_processed
integer
The “Processed” quantity.
qty_putaway
integer
The “Put-Away” quantity.
qty_committed
integer
The “Committed” quantity.
sku
string
The “SKU” property.
item_ref
string
An external item reference which may be up to 32 characters.

Delivery Label Properties

label_id
integer
The internal delivery label ID.
delivery_id
integer
The internal delivery ID.
warehouse_id
integer
The internal warehouse ID.
status
string
The “Status” property. Allowed: “valid”, “void”.
shipping_method
string
See the Shipping Methods document for a reference. Is not optional.
created_at
string
The “Created At” property in ISO 8601 format.
updated_at
string
The “Updated At” property in ISO 8601 format.
packages
array
Array of delivery label packages. See Delivery Label Package Properties.
destination_address
object
Destination Address. See Delivery Label Address Properties.
origin_address
object
Origination Address. See Delivery Label Address Properties.

Delivery Label Package Properties

warehouse_id
string
The ID of the warehouse associated with the package.
label_id
integer
The internal delivery label ID.
carrier
string
Carrier code.
weight
string
The weight of the package.
weight_unit
string
The unit of measure used for weight. See: Weight Units.
dimensions
object
The length, width, and height of the package.
dimension_unit
string
The unit of measure used for length, width, and height in dimensions. See: Length Units.
tracking
array
An array of tracking objects. The “number” property contains the tracking number. The “description” property contains the shipping method name.
package_items
array
An array of items contained in the package. delivery_item_id is the unqiue identifier of the related delivery item. sku is the package item’s SKU. quantity is the quantity of the item in the package.

Delivery Label Address Properties

firstname
string
The “First Name” property.
lastname
string
The “Last Name” property.
company
string
The “Company” property.
street
string
The street address. Multi-line street addresses will be separated by a newline (\n) character. Only two address lines are supported.
city
string
The “City” property.
region
string
The “Region” property.
postcode
string
The “Postal Code” property. Pass as a string to prevent leading 0s from being dropped.
country
string
The “Country” property.
classification
string
The “Classification” property. Allowed: “res” - residential, “com” - commercial, “po” - post office, “mil” - military, “unk” - unknown.
is_valid
integer
Flag whether address is valid.
telephone
string
The “Telephone” property.
email
string
The “Email” property.

Container Properties

container_id
integer
The internal container ID.
delivery_id
integer
The internal delivery ID.
container_type_id
integer
The “Container Type ID” property.
damage_type
string
The “Damage Type” property. Allowed: “none”, “noted”, “unnoted”.
weight_discrepancy
string
The “Weight Discrepancy” property. Allowed: “none”, “shortage_noted”, “shortage_unnoted”, “overage”, “unknown”.
tare_weight
number
The “Tare Weight” property.
tare_weight_unit
string
The unit of measure used for tare_weight. See: Weight Units.
weight
number
The “Weight” property.
weight_unit
string
The unit of measure used for weight. See: Weight Units.
weighed_at
string
The “Weighed At” property.
weighed_by
integer
The “Weighed By” property.
contents
array
Array of “content” objects. See Container Content Properties.
notes
string
The “Notes” property.

Container Content Properties

delivery_item_id
integer
The internal delivery item ID.
qty_counted
integer
The “Quantity Counted” property.
qty_shortage
integer
The “Quantity Shortage” property.

Exception Properties

delivery_exception_id
integer
The internal delivery exception ID.
delivery_id
integer
The internal delivery ID.
delivery_item_id
integer
The internal delivery item ID.
container_id
integer
The internal container ID.
status
string
The “Status” property. Allowed: “new”, “pending”, “approved”, “rejected”, “void”.
sign
integer
The “Sign” property. Allowed: “-1” - shortage, “1” - overage.
reason
string
The “Reason” property. Allowed: “overage_counted”, “overage_unexpected”, “shortage_damaged”, “shortage_missing”.
comment
string
The “Comment” property.
qty
integer
The “Quantity” property.