Drop Ship (6.0)

Download OpenAPI specification:Download

The Drop Shipping API enables customers to fulfill orders for available units and lots that are in stock in the Optoro RMS.

Listings

List listings

Results from the listings endpoint are paginated and the subset of listings that are returned are based on the page and per_page parameters supplied in the request. The total count of records in the set is returned in the response header record_count. This can be used to calculate the number of pages that need to be retrieved to get all records.

Request

query Parameters

updated_at required	string <date-time> Last updated time in ISO 8601 format, UTC. updated_at value should not be older than 3 months. Example: updated_at=2023-01-01T17:27:46
channel required	string Filter listings by Inventory channel name. Example: channel=rts_drop_ship
condition	string Filter listings by condition code. Enum: "N" "A" "B" "R"
page	integer <int32> Default: 1 The page of results to retrieve; If page number is above maximum an empty result set will be returned.
per_page	integer <int32> <= 100 Default: 20 This allows control over the amount of results returned per page.

header Parameters

api-version

required

string

The version of the API to use.

Example: 6

Responses

200

A list of listings of units and lots. The total number of records in the set will be in the response header record_count.

400

Bad Request

401

Not Authorized

404

Not Found

422

Validation error. Fix request payload and try again.

5XX

Internal Server Error

get/listings

Response samples

application/json

{"listings": [{"identifier": "S11727",
"condition": "N",
"channel": "rts_drop_ship",
"quantity": 1,
"lot": {"warehouse_name": "Warehouse A",
"template_name": "template",
"photo_urls": ["test_image.com",
"example_image.com"
],
"weight": 1.5,
"manifest_items": [{"identifier": "ITEM-PTAA760-1",
"item_title": "TITLE-PTAA760-1",
"condition": "new",
"manufacturer": "Dooley and Sons",
"upc": "0123456789012",
"sku": "SKU-PTAA760-1"
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
]
}

Show listings by identifier

Returns the listing details for the listing that matches the identifier that is included in the query parameters.

Request

path Parameters

required

string

The SKU or client identifier for the desired listing.

Example: S11727

query Parameters

condition required	string Condition code. Enum: "N" "A" "B" "R"
channel	string Inventory channel name. Gives out the particular listing if there are multiple sku-channel combinations. Example: channel=rts_drop_ship

header Parameters

api-version

required

string

The version of the API to use.

Example: 6

Responses

200

Returns the listing details for the listing that matches the identifier that is included in the query parameters.

400

Bad Request

401

Not Authorized

404

Not Found

5XX

Internal Server Error

get/listings/{id}

Response samples

application/json

{"listing": {"identifier": "S11727",
"condition": "N",
"channel": "rts_drop_ship",
"quantity": 1,
"lot": {"warehouse_name": "Warehouse A",
"template_name": "template",
"photo_urls": ["test_image.com",
"example_image.com"
],
"weight": 1.5,
"manifest_items": [{"identifier": "ITEM-PTAA760-1",
"item_title": "TITLE-PTAA760-1",
"condition": "new",
"manufacturer": "Dooley and Sons",
"upc": "0123456789012",
"sku": "SKU-PTAA760-1"
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
}

Update Listing quantity

Tell the drop ship service that the client system does not want some amount of this inventory anymore available on this channel.

Request

path Parameters

required

string

The SKU or client identifier for the desired listing.

Example: S11727

header Parameters

api-version

required

string

The version of the API to use.

Example: 6

Request Body schema: application/json

condition	string Condition code. Enum: "N" "A" "B" "R"
channel	string Inventory channel name
quantity	integer Quantity of units or lots available. This will always be 1 for lots

Responses

200

Returns the listing details for the listing that matches the identifier that is included in the query parameters.

400

Bad Request

401

Not Authorized

404

Not Found

422

Validation error. Fix request payload and try again.

5XX

Internal Server Error

put/listings/{id}

Request samples

Payload

application/json

{"condition": "N",
"channel": "rts_drop_ship",
"quantity": 1
}

Response samples

application/json

{"message": "Listing quantity updated"
}

Orders

List orders

Results from the orders endpoint are paginated and the subset of orders that are returned are based on the page and per_page parameters supplied in the request.

Request

query Parameters

updated_at required	string <date-time> Last updated time in ISO 8601 format, UTC. updated_at value should not be older than 3 months. Example: updated_at=2023-01-01T17:27:46
channel	string Filter orders by Inventory channel name. Example: channel=rts_drop_ship
status required	string Filter orders by status Enum: "accepted" "rejected" "cancelled" "pending_payment" "partially_shipped" "shipped"
page	integer <int32> Default: 1 The page of results to retrieve; If page number is above maximum an empty result set will be returned.

header Parameters

api-version

required

string

The version of the API to use.

Example: 6

Responses

200

A list of orders of units and lots. The total number of records in the set will be in the response header record_count.

400

Bad Request

401

Not Authorized

404

Not Found

422

Validation error. Fix request payload and try again.

5XX

Internal Server Error

get/orders

Response samples

application/json

{"orders": [{"id": 1,
"client_identifier": "3fda4c37-6830-469f-b343-9d1a482a97fd",
"billing_address": {"id": 1,
"name": "Lacy Macejkovic",
"company": "Bayer-Abernathy",
"telephone_number": "(914) 000-8971",
"street": "315 5th Ave",
"street2": "Suite 2112",
"city": "Scarsdale",
"state": "NY",
"zip_code": "10583",
"country": "US",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
},
"shipping_address": {"id": 1,
"name": "James Carter",
"company": "Carter Industries",
"telephone_number": "(206) 555-1208",
"street": "121 Vine Street",
"street2": "Suite 1200",
"city": "Seattle",
"state": "WA",
"zip_code": "98121",
"country": "US",
"loading_dock": true,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
},
"brand": "acme",
"shipping_method": "STANDARD",
"status": "accepted",
"price_cents": 10000,
"processing_fee_cents": 0,
"tax_cents": 1000,
"shipping_cost_cents": 500,
"shipping_tax_cents": 0,
"comments": "Sample order instructions",
"expected_delivery_date": "2019-08-24",
"signature_required": true,
"packing_slip_identifier": "1497064",
"reject_reason": "",
"order_items": [{"id": 1,
"client_identifier": "296f0b98-7bc5-4750-8cb9-2e36db1ff766",
"sku": "PTBQ121308",
"brand": "test_brand",
"condition": "N",
"quantity": 1,
"price_cents": 10000,
"tax_cents": 1000,
"shipping_cost_cents": 500,
"shipping_tax_cents": 0,
"status": "created",
"comments": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
]
}

Create an order

Used to notify Optoro of purchases of individual units or lots. Units or lots are assigned as an order item on the order.

Request

header Parameters

api-version

required

string

The version of the API to use.

Example: 6

Request Body schema: application/json

object (order-2)

Order attributes

client_identifier

required

string

The unique identifier for the order, typically coming from the customer's ecommerce Platform or OMS

channel

required

string

This is the name of the channel that the inventory available for Drop Shipping has been dispositioned to in the Optoro RMS. The channel name/names will be provided by the implementation team

required

object (billing_address-2)

name required	string Name for the address.
company	string Company name for the address.
telephone_number required	string Telephone number linked to the address.
street required	string Street line 1 of the address.
street2	string Street line 2 of the address.
city required	string City of the address.
state required	string State of the address.
zip_code required	string Zip code of the address.
country	string Country of the address.

required

object (shipping_address-2)

name required	string Name for the address.
company	string Company name for the address.
telephone_number required	string Telephone number linked to the address.
street required	string Street line 1 of the address.
street2	string Street line 2 of the address.
city required	string City of the address.
state required	string State of the address.
zip_code required	string Zip code of the address.
country	string Country of the address.
loading_dock	boolean Flag to determine whether fork lift is required to deliver package.

brand

required

string

Brand name of client that received the order.

shipping_method

required

string

The shipping method to be used on the order.

Optoro will search for a shipping method that delivers within the timeframes outlined below

Standard - best rate, no constraint on days
Express - <= 2 days
Overnight - <= 1 days

Enum: "STANDARD" "EXPRESS" "OVERNIGHT" "FREIGHT" "PICK-UP"

price_cents

required

integer

Price paid in cents for the order.

processing_fee_cents

integer

Processing fee paid in cents for the order.

tax_cents

required

integer

Tax paid in cents for the order.

shipping_cost_cents

required

integer

Shipping cost paid in cents for the order.

shipping_tax_cents

required

integer

Shipping tax paid in cents for the order.

comments

string

Comments regarding the order.

expected_delivery_date

string <date>

Expected delivery date of the order.

signature_required

boolean

Specifies if a customer signature is required on delivery

packing_slip_identifier

string

Packing slip identifier for the order.

required

Array of objects (order_item-2)

Array of order items on the order

Array

client_identifier	string The order item identifier for the order item, typically coming from the customer's ecommerce platform or OMS
sku	string Item SKU or listing identifier. This will always be listing.identifier
brand	string The brand name of the order item
condition	string The condition code for the order item
quantity	integer The quantity of the order item
price_cents	integer The price in cents for the total quantity of the order item
tax_cents	integer The tax in cents for the total quantity of the order item
shipping_cost_cents	integer The shipping cost paid in cents for the order item
shipping_tax_cents	integer The shipping tax paid in cents for the order item
comments	string Comments associated with the order item

Responses

200

Order rejected response

201

Order accepted response

400

Bad Request

401

Not Authorized

404

Not Found

413

Request too large

422

Order not created response

5XX

Internal Server Error

post/orders

Request samples

Payload

application/json

{"order": {"client_identifier": "3fda4c37-6830-469f-b343-9d1a482a97fd",
"channel": "rts_drop_ship",
"billing_address": {"name": "Lacy Macejkovic",
"company": "Bayer-Abernathy",
"telephone_number": "252-948-6723 12345",
"street": "315 5th Ave",
"street2": "Suite 2112",
"city": "New York",
"state": "NY",
"zip_code": "10016",
"country": "US"
},
"shipping_address": {"name": "Lacy Macejkovic",
"company": "Bayer-Abernathy",
"telephone_number": "252-948-6723 12345",
"street": "315 5th Ave",
"street2": "Suite 2112",
"city": "New York",
"state": "NY",
"zip_code": "10016",
"country": "US",
"loading_dock": true
},
"brand": "acme",
"shipping_method": "STANDARD",
"price_cents": 10000,
"processing_fee_cents": 0,
"tax_cents": 1000,
"shipping_cost_cents": 500,
"shipping_tax_cents": 0,
"comments": "Gift wrap required",
"expected_delivery_date": "2019-08-24",
"signature_required": true,
"packing_slip_identifier": "1497064",
"order_items": [{"client_identifier": "296f0b98-7bc5-4750-8cb9-2e36db1ff766",
"sku": "PTBQ121308",
"brand": "acme",
"condition": "N",
"quantity": 1,
"price_cents": 10000,
"tax_cents": 1000,
"shipping_cost_cents": 500,
"shipping_tax_cents": 0,
"comments": ""
}
]
}
}

Response samples

application/json

{"message": "rejected",
"reason": "Insufficient Quantity for: <order item  #1 client_identifier> - <order item  #1 sku>(condition), <order item  #2 client_identifier> - <order item  #2 sku> (condition)",
"order": {"client_identifier": "3573390128",
"order_items": [{"client_identifier": "296f0b98-7bc5-4750-8cb9-2e36db1ff766",
"sku": "PTBQ121308",
"condition": "N",
"quantity": 3,
"available_quantity": 1
}
]
}
}

Create orders in batches

This request creates orders in batches. Batches can contain a maximum of 25 orders per request.

Request

header Parameters

api-version

required

string

The version of the API to use.

Example: 6

Request Body schema: application/json

Array of objects (order-2)

Array

client_identifier

required

string

The unique identifier for the order, typically coming from the customer's ecommerce Platform or OMS

channel

required

string

This is the name of the channel that the inventory available for Drop Shipping has been dispositioned to in the Optoro RMS. The channel name/names will be provided by the implementation team

required

object (billing_address-2)

name required	string Name for the address.
company	string Company name for the address.
telephone_number required	string Telephone number linked to the address.
street required	string Street line 1 of the address.
street2	string Street line 2 of the address.
city required	string City of the address.
state required	string State of the address.
zip_code required	string Zip code of the address.
country	string Country of the address.

required

object (shipping_address-2)

name required	string Name for the address.
company	string Company name for the address.
telephone_number required	string Telephone number linked to the address.
street required	string Street line 1 of the address.
street2	string Street line 2 of the address.
city required	string City of the address.
state required	string State of the address.
zip_code required	string Zip code of the address.
country	string Country of the address.
loading_dock	boolean Flag to determine whether fork lift is required to deliver package.

brand

required

string

Brand name of client that received the order.

shipping_method

required

string

The shipping method to be used on the order.

Optoro will search for a shipping method that delivers within the timeframes outlined below

Standard - best rate, no constraint on days
Express - <= 2 days
Overnight - <= 1 days

Enum: "STANDARD" "EXPRESS" "OVERNIGHT" "FREIGHT" "PICK-UP"

price_cents

required

integer

Price paid in cents for the order.

processing_fee_cents

integer

Processing fee paid in cents for the order.

tax_cents

required

integer

Tax paid in cents for the order.

shipping_cost_cents

required

integer

Shipping cost paid in cents for the order.

shipping_tax_cents

required

integer

Shipping tax paid in cents for the order.

comments

string

Comments regarding the order.

expected_delivery_date

string <date>

Expected delivery date of the order.

signature_required

boolean

Specifies if a customer signature is required on delivery

packing_slip_identifier

string

Packing slip identifier for the order.

required

Array of objects (order_item-2)

Array of order items on the order

Array

client_identifier	string The order item identifier for the order item, typically coming from the customer's ecommerce platform or OMS
sku	string Item SKU or listing identifier. This will always be listing.identifier
brand	string The brand name of the order item
condition	string The condition code for the order item
quantity	integer The quantity of the order item
price_cents	integer The price in cents for the total quantity of the order item
tax_cents	integer The tax in cents for the total quantity of the order item
shipping_cost_cents	integer The shipping cost paid in cents for the order item
shipping_tax_cents	integer The shipping tax paid in cents for the order item
comments	string Comments associated with the order item

Responses

200

Batch order creation response

400

Bad Request

401

Not Authorized

404

Not Found

413

Request too large

422

Validation error. Fix request payload and try again.

5XX

Internal Server Error

post/batch/orders

Request samples

Payload

application/json

{"orders": [{"client_identifier": "3fda4c37-6830-469f-b343-9d1a482a97fd",
"channel": "rts_drop_ship",
"billing_address": {"name": "Lacy Macejkovic",
"company": "Bayer-Abernathy",
"telephone_number": "252-948-6723 12345",
"street": "315 5th Ave",
"street2": "Suite 2112",
"city": "New York",
"state": "NY",
"zip_code": "10016",
"country": "US"
},
"shipping_address": {"name": "Lacy Macejkovic",
"company": "Bayer-Abernathy",
"telephone_number": "252-948-6723 12345",
"street": "315 5th Ave",
"street2": "Suite 2112",
"city": "New York",
"state": "NY",
"zip_code": "10016",
"country": "US",
"loading_dock": true
},
"brand": "acme",
"shipping_method": "STANDARD",
"price_cents": 10000,
"processing_fee_cents": 0,
"tax_cents": 1000,
"shipping_cost_cents": 500,
"shipping_tax_cents": 0,
"comments": "Gift wrap required",
"expected_delivery_date": "2019-08-24",
"signature_required": true,
"packing_slip_identifier": "1497064",
"order_items": [{"client_identifier": "296f0b98-7bc5-4750-8cb9-2e36db1ff766",
"sku": "PTBQ121308",
"brand": "acme",
"condition": "N",
"quantity": 1,
"price_cents": 10000,
"tax_cents": 1000,
"shipping_cost_cents": 500,
"shipping_tax_cents": 0,
"comments": ""
}
]
}
]
}

Response samples

application/json

[{"client_identifier": "3fda4c37-6830-469f-b343-9d1a482a97fd",
"status": "created",
"message": null
}
]

Show an order by identifier

Returns the order details for the order that matches the identifier that is included in the url path.

Request

path Parameters

required

string

The client identifier for the desired order

Example: 3573390128

header Parameters

api-version

required

string

The version of the API to use.

Example: 6

Responses

200

Success response will return HTTP status code 200

400

Bad Request

401

Not Authorized

404

Not Found

413

Request too large

422

Unprocessable Entity

5XX

Internal Server Error

get/orders/{id}

Response samples

application/json

{"order": {"id": 1,
"client_identifier": "3fda4c37-6830-469f-b343-9d1a482a97fd",
"billing_address": {"id": 1,
"name": "Lacy Macejkovic",
"company": "Bayer-Abernathy",
"telephone_number": "(914) 000-8971",
"street": "315 5th Ave",
"street2": "Suite 2112",
"city": "Scarsdale",
"state": "NY",
"zip_code": "10583",
"country": "US",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
},
"shipping_address": {"id": 1,
"name": "James Carter",
"company": "Carter Industries",
"telephone_number": "(206) 555-1208",
"street": "121 Vine Street",
"street2": "Suite 1200",
"city": "Seattle",
"state": "WA",
"zip_code": "98121",
"country": "US",
"loading_dock": true,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
},
"brand": "acme",
"shipping_method": "STANDARD",
"status": "accepted",
"price_cents": 10000,
"processing_fee_cents": 0,
"tax_cents": 1000,
"shipping_cost_cents": 500,
"shipping_tax_cents": 0,
"comments": "Sample order instructions",
"expected_delivery_date": "2019-08-24",
"signature_required": true,
"packing_slip_identifier": "1497064",
"reject_reason": "",
"order_items": [{"id": 1,
"client_identifier": "296f0b98-7bc5-4750-8cb9-2e36db1ff766",
"sku": "PTBQ121308",
"brand": "test_brand",
"condition": "N",
"quantity": 1,
"price_cents": 10000,
"tax_cents": 1000,
"shipping_cost_cents": 500,
"shipping_tax_cents": 0,
"status": "created",
"comments": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
}

Update an order by identifier

Marks the lot order that matches the identifier that is included in the url path as accepted from pending_payment.

Request

path Parameters

required

string

The client identifier for the desired order

Example: 3573390128

header Parameters

api-version

required

string

The version of the API to use.

Example: 6

Request Body schema: application/json

object

Order attributes

payment_status

string

Current Payment status of the order. Applicable only for lot orders.

Value: "complete"

Responses

204

Success response will return HTTP status code 204 with no content

400

Bad Request

401

Not Authorized

404

Not Found

413

Request too large

422

Validation error. Fix request payload and try again.

500

Internal Server Error

put/orders/{id}

Request samples

Payload

application/json

{"order": {"payment_status": "complete"
}
}

Response samples

application/json

{"message": "Order cannot be found"
}

Cancel an order by identifier

Cancels the lot order that matches the identifier that is included in the url path from pending_payment status.

Request

path Parameters

required

string

The client identifier for the desired order

Example: 3573390128

header Parameters

api-version

required

string

The version of the API to use.

Example: 6

Responses

204

Success response will return HTTP status code 204 with no content

400

Bad Request

401

Not Authorized

404

Not Found

413

Request too large

422

Validation error. Fix request payload and try again.

500

Internal Server Error

delete/orders/{id}

Response samples

application/json

{"message": "Order cannot be found"
}

Shipments

Lists shipments

Results from the shipments endpoint are paginated and the subset of shipments that are returned are based on the page and per_page parameters supplied in the request. The total count of records in the set is returned in the response header record_count. This can be used to calculate the number of pages that need to be retrieved to get all records.

Request

query Parameters

updated_at required	string <date-time> Last updated time in ISO 8601 format, UTC. Example: updated_at=2022-01-01T17:27:46
channel	string Filter shipments by Inventory channel name. Example: channel=rts_drop_ship
page	integer Default: 1 The page of results to retrieve. If page number is above maximum an empty result set will be returned.
per_page	integer <= 100 Default: 20 This allows control over the amount of results returned per page. Maximum allowed value is 100.

header Parameters

api-version

required

string

The version of the API to use.

Example: 6

Responses

200

Returns the list of shipments matching the given conditions.

400

Bad Request

401

Not Authorized

422

Validation error. Fix request payload and try again.

5XX

Internal Server Error

get/shipments

Response samples

application/json

{"shipments": [{"id": 1,
"client_identifier": "3fda4c37-6830-469f-b343-9d1a482a97fd",
"channel": "rts_drop_ship",
"carrier": "UPS",
"shipping_method": "UPS 2nd day air",
"tracking_number": "1Z2E07A20302245707",
"billed_weight": 10,
"shipping_cost_cents": 1000,
"packing_slip_identifier": "1497064",
"shipment_items": [{"id": 1,
"client_identifier": "296f0b98-7bc5-4750-8cb9-2e36db1ff766",
"sku": "SKU12345",
"quantity": 1,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
]
}

Show details of a shipment

Get details of a shipment by tracking number.

Request

path Parameters

required

string

Tracking number of the package.

Example: 1Z2E07A20302245707

query Parameters

carrier

string

Carrier used in shipping.

Example: carrier=UPS

header Parameters

api-version

required

string

The version of the API to use.

Example: 6

Responses

200

Returns the details of a shipment.

400

Bad Request

401

Not Authorized

5XX

Internal Server Error

get/shipments/{id}

Response samples

application/json

{"shipments": [{"id": 1,
"client_identifier": "3fda4c37-6830-469f-b343-9d1a482a97fd",
"channel": "rts_drop_ship",
"carrier": "UPS",
"shipping_method": "UPS 2nd day air",
"tracking_number": "1Z2E07A20302245707",
"billed_weight": 10,
"shipping_cost_cents": 1000,
"packing_slip_identifier": "1497064",
"shipment_items": [{"id": 1,
"client_identifier": "296f0b98-7bc5-4750-8cb9-2e36db1ff766",
"sku": "SKU12345",
"quantity": 1,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
]
}

Show list of the shipments for an order

Get details of a shipments filtered by an order.

Request

path Parameters

required

string

Client Order Identifier

Example: ORDER-1

header Parameters

api-version

required

string

The version of the API to use.

Example: 6

Responses

200

Returns the list of shipments for the given order.

400

Bad Request

401

Not Authorized

5XX

Internal Server Error

get/shipments/identifier/{id}

Response samples

application/json

{"shipments": [{"id": 1,
"client_identifier": "3fda4c37-6830-469f-b343-9d1a482a97fd",
"channel": "rts_drop_ship",
"carrier": "UPS",
"shipping_method": "UPS 2nd day air",
"tracking_number": "1Z2E07A20302245707",
"billed_weight": 10,
"shipping_cost_cents": 1000,
"packing_slip_identifier": "1497064",
"shipment_items": [{"id": 1,
"client_identifier": "296f0b98-7bc5-4750-8cb9-2e36db1ff766",
"sku": "SKU12345",
"quantity": 1,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
]
}