Skip to content
API Specifications
/
Returns Management
/
/
Disposition Update

Disposition Update (1.0.0)

Introduction

The Disposition Update API is used to communicate to the client a change in state/disposition, of a unit as it moves through the ROP and is placed in its next possible value disposition. For example, an unused, open box unit changing state from Return to Vendor to being Return to Stock as a new disposition due to Return to Vendor quotas being exceeded for that unit type.

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 Disposition Update 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.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
Languages
Servers
Mock server
https://developer.optoro.com/_mock/openapi/disposition_update/openapi
https://developer.optoro.com

POST a unit's disposition update

Request

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

Bodyapplication/jsonrequired
from_dispositionstringrequired

Indicates which channel this unit is from. Options include: b2b, d2c, client_liquidation, destroy, dispose, donate, outlets, recycle, removed, rts, rts_drop_ship, rtv, stock_transfer

Example: "needs_testing"
to_dispositionstringrequired

Indicates which channel this unit is designated to. Options include: b2b, d2c, client_liquidation, destroy, dispose, donate, outlets, recycle, removed, rts, rts_drop_ship, rtv, stock_transfer

Example: "recycle"
timestampstringrequired

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

Example: "2018-03-20T00:00:00"
location_identifierstringrequired

Shared storage location identifier (present in both Optoro and client’s system) representing the units current location

Example: "RTS-1112"
warehouse_identifierstringrequired

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

Example: "22"
optiturn_lpstringrequired

Unique alphanumeric id of the unit

Example: "LPAA1234567"
program_identifierstringrequired

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

Example: "parcel_returns"
from_skustring

Indicates the client SKU associated with the unit before a change - will be the same as to_sku if the unit didn’t change SKU

Example: "012344566700"
to_skustring

Indicates the client SKU associated with the unit after the change - will be the same as from_sku if the unit didn’t change SKU

Example: "012344566700"
skustring

This field is deprecated and may be removed in a future version of the API. Please use from_sku and to_sku above instead

Example: "012344566700"
upcstringrequired

UPC for the unit

Example: "0123456789012"
from_conditionstringrequired

[N, TT, R, A, B, C, X] indicating which condition the unit was before its new disposition, a condition mapping is often created to match your internal conditions

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

[N, TT, R, A, B, C, X] indicating which condition the unit is at its new disposition, a condition mapping is often created to match your internal conditions

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

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

Example: "Unit A"
store_identifierstring

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

Example: "Store A"
user_loginstring

OptiTurn username of the user that triggered the disposition change. Only included for client users, not 3PL

Example: "client_user_login"
curl -i -X POST \
  https://developer.optoro.com/_mock/openapi/disposition_update/openapi/dispositions \
  -H 'Content-Type: application/json' \
  -d '{
    "from_disposition": "needs_testing",
    "to_disposition": "recycle",
    "timestamp": "2018-03-20T00:00:00",
    "location_identifier": "RTS-1112",
    "warehouse_identifier": "22",
    "optiturn_lp": "LPAA1234567",
    "program_identifier": "parcel_returns",
    "from_sku": "012344566700",
    "to_sku": "012344566700",
    "sku": "012344566700",
    "upc": "0123456789012",
    "from_condition": "N",
    "to_condition": "TT",
    "reference_unit_identifier": "Unit A",
    "store_identifier": "Store A",
    "user_login": "client_user_login"
  }'

Responses

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

Bodyapplication/json
messagestring
Example: "Success"
Response
application/json
{
  "message": "Success"
}
© 2010 – 2026 Optoro, Inc. For official use only by authorized users. Use subject to terms of license agreement.