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
delivery.search(null|object $filters, array $options = [])
Retrieve list of deliveries. Filtration could be applied.
Parameters
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”.
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:
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"delivery.search",
[
{
"delivery_id" : {
"eq" : 1
}
},
[]
]
]
}
Example 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
code | message |
---|
101 | Invalid filters given. Details in error message. |
delivery.create
delivery.create(number $deliveryType, object $data, null|array $items = null)
Create delivery.
Parameters
Delivery type. Allowed: “asn”, “rma”, “other”.
null
- Create delivery without items.
array
- Array of objects with two properties: “sku” and “qty”.
Return Value
Delivery information.
Example 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
{
"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
code | message |
---|
107 | Error 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
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:
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"delivery.labels",
[
"1000055",
[
"packages",
"destination_address",
"origin_address"
]
]
]
}
Example 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
code | message |
---|
100 | Requested 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
null
- Update delivery without adding items.
array
- Array of objects with two properties: “sku” and “qty”.
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
{
"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
{
"result": true,
"id": "1234",
"jsonrpc": "2.0"
}
delivery.close
delivery.close(string $incrementId)
Close a delivery.
Parameters
The “Increment ID” property.
Return Value
true
if delivery inventory was successfully closed.
Example Request
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"aebdb4cc6f861c79428768923f0eb6a2",
"delivery.close",
[
"11000011"
]
]
}
Example Response
{
"result": true,
"id": "1234",
"jsonrpc": "2.0"
}
Error Codes
code | message |
---|
115 | Delivery 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
The “Increment ID” property.
true
to close the delivery.
Return Value
true
if delivery inventory was successfully committed.
Example Request
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"aebdb4cc6f861c79428768923f0eb6a2",
"delivery.commit",
[
"11000011"
]
]
}
Example Response
{
"result": true,
"id": "1234",
"jsonrpc": "2.0"
}
Error Codes
code | message |
---|
113 | Delivery with the specified ID cannot be committed. Details in the error message. |
delivery.cancel
delivery.cancel(string $incrementId)
Cancel delivery.
Parameters
The “Increment ID” property.
Return Value
true
if delivery was successfully canceled.
Example Request
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"aebdb4cc6f861c79428768923f0eb6a2",
"delivery.cancel",
[
"11000017"
]
]
}
Example Response
{
"result": true,
"id": "1234",
"jsonrpc": "2.0"
}
Error Codes
code | message |
---|
112 | Delivery with the specified ID cannot be canceled. Details in the error message. |
delivery.void
delivery.void(string $incrementId)
Cancel delivery.
Parameters
The “Increment ID” property.
Return Value
true
if delivery was successfully voided.
Example Request
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"aebdb4cc6f861c79428768923f0eb6a2",
"delivery.void",
[
"11000018"
]
]
}
Example Response
{
"result": true,
"id": "1234",
"jsonrpc": "2.0"
}
Error Codes
code | message |
---|
114 | Delivery with the specified ID cannot be voided. Details in the error message. |
Entity Properties
Delivery Properties
Property Translations: API to UI
API | ASN | RMA | Other |
---|
sender_name | Supplier | Customer Name | Sender |
sender_ref | Supplier Invoice Ref | (deprecated, use tracking_numbers ) | Sender Ref 1 |
sender_ref_alt | Supplier Order Ref | Merchant Order # | Sender Ref 2 |
tracking_numbers | Tracking Numbers | Tracking Numbers | Tracking Numbers |
merchant_ref | Merchant Ref | Merchant RMA # | Merchant Ref |
merchant_status | Merchant Status | Merchant Status | Merchant Status |
expected_delivery | Expected Delivery Date | Authorization Date | Expected Delivery Date |
The internal delivery ID.
The internal warehouse ID.
The “Increment ID” property.
The “Delivery Type” property. Allowed: “asn”, “rma”, “other”.
The “State” property. Allowed: “new”, “processing”, “putting_away”, “pending_commit”, “complete”, “canceled”.
The “Status” property. Allowed: “new”, “accepting”, “accepted”, “ready_to_process”, “processing”, “processing_exception”, “processed”, “putting_away”, “put_away”, “complete”, “canceled”, “void”.
The “Progress” property. Number from 0 to 100.
The “Sender Name” property.
The “Carrier Name” property.
The “Expected Delivery” property.
The “Delivered At” property.
The “Delivered At” property.
The “Processed At” property.
The “Put-Away At” property.
The “Completed At” property.
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.
The “Merchant Status” property.
The “Sender Reference” property. Do not use this field for RMAs.
The “Sender Reference Alt” property.
The “Tracking Numbers” property.
The “Total Container Weight” property.
total_container_weight_unit
The unit of measure used for total_container_weight
. See: Weight Units.
The “Total Product Weight” property.
total_product_weight_unit
The unit of measure used for total_product_weight
. See: Weight Units.
The “Special Requirements” property.
Determines whether inventory will be commited automatically upon put-away completion. 0 - Disabled, 1 - Enabled, 2 - Use default from config
Determines whether the delivery will be closed automatically upon acceptance of the last container. 0 - Disabled, 1 - Enabled, 2 - Use default from config
The “Created At” property.
The “Updated At” property.
Delivery Item Properties
The internal delivery item ID.
The internal delivery ID.
The quantity that was set when the delivery was created or edited.
The quantity that is expected to be received in the future.
The “Processed” quantity.
The “Committed” quantity.
An external item reference which may be up to 32 characters.
Delivery Label Properties
The internal delivery label ID.
The internal delivery ID.
The internal warehouse ID.
The “Status” property. Allowed: “valid”, “void”.
The “Created At” property in ISO 8601 format.
The “Updated At” property in ISO 8601 format.
Delivery Label Package Properties
The ID of the warehouse associated with the package.
The internal delivery label ID.
The weight of the package.
The length
, width
, and height
of the package.
The unit of measure used for length
, width
, and height
in dimensions
. See: Length Units.
An array of tracking objects. The “number” property contains the tracking number. The “description” property contains the shipping method name.
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
The “First Name” property.
The “Last Name” property.
The street address. Multi-line street addresses will be separated by a newline (\n
) character. Only two address lines are supported.
The “Postal Code” property. Pass as a string to prevent leading 0s from being dropped.
The “Classification” property. Allowed: “res” - residential, “com” - commercial, “po” - post office, “mil” - military, “unk” - unknown.
Flag whether address is valid.
The “Telephone” property.
Container Properties
The internal container ID.
The internal delivery ID.
The “Container Type ID” property.
The “Damage Type” property. Allowed: “none”, “noted”, “unnoted”.
The “Weight Discrepancy” property. Allowed: “none”, “shortage_noted”, “shortage_unnoted”, “overage”, “unknown”.
The “Tare Weight” property.
The unit of measure used for tare_weight
. See: Weight Units.
The “Weighed At” property.
The “Weighed By” property.
Container Content Properties
The internal delivery item ID.
The “Quantity Counted” property.
The “Quantity Shortage” property.
Exception Properties
The internal delivery exception ID.
The internal delivery ID.
The internal delivery item ID.
The internal container ID.
The “Status” property. Allowed: “new”, “pending”, “approved”, “rejected”, “void”.
The “Sign” property. Allowed: “-1” - shortage, “1” - overage.
The “Reason” property. Allowed: “overage_counted”, “overage_unexpected”, “shortage_damaged”, “shortage_missing”.