Final Disposition (1.0.0)

Download OpenAPI specification:Download

Introduction

The Final Disposition API is used to communicate to the client the final state, or disposition, of a unit when it leaves the ROP and is placed in its highest possible value disposition. For example, an unused, open box unit being returned to stock as a final disposition.

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 Final Disposition 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 unit's final disposition

Client endpoint to which final disposition update 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

disposition

required

string

A flag indicating which channel this pallet is designated for. Possible values are: b2b, d2c, client_liquidation, destroy, dispose, donate, outlets, recycle, removed, rts, rts_drop_ship, rtv, stock_transfer

timestamp

required

string

iso8601 formatted date string (YYYY-MM-DDT00:00:00) in UTC

location_identifier

required

string

Shared storage location identifier (lot name, present in both Optoro and client’s system) representing the units final location

warehouse_identifier

required

string

Indicates the warehouse where the unit was located. Identifier can be configured by the client; otherwise will default to Optoro’s internal warehouse identifier.

optiturn_lp

required

string

Unique alphanumeric id of the unit

program_identifier

required

string

Either a client-provided program name or OptiTurn’s internal program id

sku

string

The client sku to which this unit belongs

upc

string

UPC for the unit

condition

required

string

[N, TT, R, A, B, C, X] final condition value, a condition mapping is often created to match your internal conditions

Enum: "N" "TT" "R" "A" "B" "C" "X"

reference_unit_identifier

string

A client-provided identifier for the unit, likely provided by an inbound integration

store_identifier

string

The identifier of the store that returned the unit to the warehouse

reason

string

The cause of the disposition event. Currently only populated for remove and dispose events. See below for available values.

Remove	Dispose
internal_use duplicate_item lost_item client_request counterfeit hazmat recall other	no_item_in_box physically_damaged hygiene_issue expired personalization

shipment_reference_identifier

string

Uniquely identifies the shipment that left the warehouse. Varies by channel. For example: the order number of an RTS Drop Ship unit.

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 from the client’s services and retry the request.

422

Validation Failure

500

Internal Server Error

502

Client Server Unavailable

post/final_dispositions

Request samples

Payload

application/json

{"disposition": "rts",
"timestamp": "2018-03-20T00:00:00",
"location_identifier": "RTS-1112",
"warehouse_identifier": "22",
"optiturn_lp": "LPAA1234567",
"program_identifier": "parcel_returns",
"sku": "012344566700",
"upc": "0123456789012",
"condition": "N",
"reference_unit_identifier": "Unit A",
"store_identifier": "Store A",
"reason": "no_item_in_box",
"shipment_reference_identifier": "1"
}

Response samples

application/json

{"message": "Success"
}