Drop Ship (1.0.0)

Download OpenAPI specification:Download

Introduction

The Drop Ship is used to communicate to the client once an order has been shipped or cancelled from OptiTurn, to close an order within the client's OMS.

Post Confirmation:

The Drop Shipment Confirmation API is used to post a shipment confirmation for the orders shipped so that the client can close the order on their end. Optoro can POST a shipment confirmation to the client endpoint.

Post Cancellation:

The Drop Shipment Cancellation API is used to post a cancelled order to a client endpoint. An order could be rejected or cancelled in the warehouse, due to the inventory not being found or it being damaged.

Post Partial Cancellation:

The Drop Shipment Partial Cancellation API is used to post a partially cancelled order to a client endpoint. An order item could be cancelled in the warehouse, due to the inventory is not being found or damaged.

Failure Handling

When Optoro receives a 401 HTTP status, Optoro will request a new Authentication Token from the client's services and retry the request.

When Optoro receives any other error (as described above and identified by a 4xx (not 401) or 5xx range http status code) Optoro will retry five times with the same message. The retries will happen at an exponential backoff cadence in order not to overload machines. If the failure persists, the message will be stored in a failure queue and Optoro will have a technical contact person reach out to client tech support to report a problem. When the problem has been resolved, Optoro can manually retry failed requests.

For Drop Shipment acknowledgement, all errors are handled the same since this is not in a user facing flow. However, the differentiation of status codes will help Optoro when reporting an issue.

POST a Drop Shipment Confirmation

Client endpoint to which Drop Shipment Confirmation data is posted to.
This endpoint along with any authentication mechanisms needed must be communicated to client's account manager.

Request

Request Body schema: application/json

object

integer

An object's database primary key. Do not rely on this value!

client_identifier

required

string

client_identifier associated with the shipment which is also associated with the order

channel

required

string

Inventory channel name

carrier

required

string

Carrier used in shipping.

shipping_method

required

string

Name of the shipping method used for the shipment

tracking_number

required

string

Shipment tracking number

billed_weight

required

number

Weight of the shipment in pounds

shipping_cost_cents

required

integer

Actual shipping cost paid to ship the package

packing_slip_identifier

string

Identifier to be printed on the packing slip barcode. If null, client_identifier will be the default barcode.

required

Array of objects

Items included in this shipment

Array

id	integer >= 1 An object's database primary key. Do not rely on this value!
client_identifier	string Client_identifier associated with the shipment item which is also associated with the order item
quantity	integer >= 1 Shipped item quantity
created_at	string <date-time> Date in ISO 8601 format in UTC
updated_at	string <date-time> Date in ISO 8601 format in UTC

created_at

string <date-time>

Date in ISO 8601 format in UTC

updated_at

string <date-time>

Date in ISO 8601 format in UTC

Responses

200

Success. Optoro recommends client APIs respond with a JSON-structured object. This is used for debugging purposes only so this guidance is technically optional.

400

Bad Request

401

Not Authorized. A new authentication token will be requested from the client's services and the request will be retried.

422

Validation failure

500

Internal Server Error

502

Client Server Unavailable

post/drop_shipment_confirmation

Request samples

Payload

application/json

{"shipment": {"id": 1,
"client_identifier": "3fda4c37-6830-469f-b343-9d1a482a97fd",
"channel": "rts_drop_ship",
"carrier": "UPS",
"shipping_method": "UPS Ground",
"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",
"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"
}
}

Response samples

application/json

{"message": "Success"
}

POST a Drop Shipment Cancellation

Client endpoint to which Drop Shipment Cancellation data is posted to.
This endpoint along with any authentication mechanisms needed must be communicated to client's account manager.

Request

Request Body schema: application/json

object

integer

An object's database primary key. Do not rely on this value!

client_identifier

required

string

client_identifier associated with the shipment which is also associated with the order

required

object

id	integer An object's database primary key. Do not rely on this value!
name	string Name for the address.
company	string Company name for the address.
telephone_number	string Telephone number linked to the address.
street	string Street line 1 of the address.
street2	string Street line 2 of the address.
city	string City of the address.
state	string State of the address.
zip_code	string Zip code of the address.
country	string Country of the address.
created_at	string <date-time> Creation timestamp iso8601 UTC
updated_at	string <date-time> Timestamp of most recent update iso8601 UTC

required

object

id	integer An object's database primary key. Do not rely on this value!
name	string Name for the address.
company	string Company name for the address.
telephone_number	string Telephone number linked to the address.
street	string Street line 1 of the address.
street2	string Street line 2 of the address.
city	string City of the address.
state	string State of the address.
zip_code	string Zip code of the address.
country	string Country of the address.
created_at	string <date-time> Creation timestamp iso8601 UTC
updated_at	string <date-time> Timestamp of most recent update iso8601 UTC

brand

required

string

Brand name of client that received the order.

shipping_method

required

string

The shipping method to be used on the order.

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

status

required

string

Status of the order.

price_cents

required

integer

Price paid in cents for the order.

tax_cents

required

integer

Tax paid in cents for the order.

processing_fee_cents

integer

Processing fee 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.

reject_reason

string

Reason the order was rejected.

required

Array of objects

Order Item attributes

Array

id	integer An object's database primary key. Do not rely on this value!
client_identifier required	string The order item identifier for the order item, typically coming from the customer's ecommerce platform or OMS
sku required	string Item SKU or listing identifier. This will always be listing.identifier
brand required	string The brand name of the order item
condition required	string The condition code for the order item
quantity required	integer The quantity of the order item
price_cents required	integer The price in cents for the total quantity of the order item
tax_cents required	integer The tax in cents for the total quantity of the order item
shipping_cost_cents required	integer The shipping cost paid in cents for the order item
shipping_tax_cents required	integer The shipping tax paid in cents for the order item
status required	string Status of the order item
comments	string Comments associated with the order item

created_at

string <date-time>

Date in ISO 8601 format in UTC

updated_at

string <date-time>

Date in ISO 8601 format in UTC

Responses

200

Success. Optoro recommends client APIs respond with a JSON-structured object. This is used for debugging purposes only so this guidance is technically optional.

400

Bad Request

401

Not Authorized. A new authentication token will be requested from the client's services and the request will be retried.

422

Validation failure

500

Internal Server Error

502

Client Server Unavailable

post/drop_shipment_cancellation

Request samples

Payload

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",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
},
"brand": "acme",
"shipping_method": "STANDARD",
"status": "cancelled",
"price_cents": 10000,
"tax_cents": 1000,
"processing_fee_cents": 0,
"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": "cancelled",
"comments": ""
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
}

Response samples

application/json

{"message": "Success"
}

POST a Drop Shipment Partial Cancellation

Client endpoint to which Drop Shipment Partial Cancellation data is posted to.
This endpoint along with any authentication mechanisms needed must be communicated to client's account manager.

Request

Request Body schema: application/json

object

integer

An object's database primary key. Do not rely on this value!

client_identifier

string

client_identifier associated with the shipment which is also associated with the order

status

string

Status of the order.

Array of objects

Order Item attributes

Array

id	integer An object's database primary key. Do not rely on this value!
client_identifier required	string The order item identifier for the order item, typically coming from the customer's ecommerce platform or OMS
status required	string Status of the order item
quantity required	integer The quantity of the order item
cancelled_quantity required	integer The quantity of the order item

Responses

200

Success. Optoro recommends client APIs respond with a JSON-structured object. This is used for debugging purposes only so this guidance is technically optional.

400

Bad Request

401

Not Authorized. A new authentication token will be requested from the client's services and the request will be retried.

422

Validation failure

500

Internal Server Error

502

Client Server Unavailable

post/drop_shipment_partial_cancellation

Request samples

Payload

application/json

{"order": {"id": 1,
"client_identifier": "3fda4c37-6830-469f-b343-9d1a482a97fd",
"status": "shipped",
"order_items": [{"id": 1,
"client_identifier": "296f0b98-7bc5-4750-8cb9-2e36db1ff766",
"status": "cancelled",
"quantity": 3,
"cancelled_quantity": 1
}
]
}
}

Response samples

application/json

{"message": "Success"
}