Skip to content
API Specifications
/
Returns Management
/
/
Failure Handling

Outbound ASN (1.0.0)

The Outbound ASN API allows clients to be notified when a shipment is leaving the Optoro WMS. This allows clients to notify other systems so that the inventory can be received at the destination.

For very large shipments or pallets multiple ASNs may be sent. Your systems should expect to receive multiple messages for a single carton. Each message will have a unique asn number though.

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 Outbound ASN 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
Languages
Servers
Mock server
https://developer.optoro.com/_mock/openapi/outbound_asn/openapi

Outbound ASN Event

Request

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

Bodyapplication/jsonrequired
fromobjectrequired

The location this ASN is being sent from.

from.​identifierstring

Identifier for the from location.
When from.type is warehouse:

  • If an External Identifier is configured for the warehouse, this will surface that identifier.
  • If not, this will default to the internal OT warehouse ID.
Example: "16"
from.​typestring

Type of the from location options include [warehouse, store]. This will typically be “warehouse”.

Example: "warehouse"
toobjectrequired

The location this ASN is being sent to.

to.​identifierstring

Identifier for the to location.

  • When stock transferring, this value is the stock transfer identifier configured in warehouse settings
  • For freight shipments, this value is the external warehouse identifier configured for the warehouse.
  • For vendor shipments, this value is a number signifying the internal OptiTurn vendor ID
Example: "07"
to.​typestring

Type of the from location options include [warehouse, store]. This will typically be “warehouse”.

Example: "warehouse"
to.​addressobject(address)

The address this shipment is going to. See below for fields.

asn_numberstringrequired

A number generated by Optiturn uniquely identifying this ASN. The regex for this value is: /[A-Za-z0-9-_]{1,255}/.

Sometimes Outbound ASNs are split into multiple messages depending on the size of the shipment. In this case each asn_number will be appended by an incremental number, for example: “_1, _2, etc”.

Example: "1498456_7417412"
channelstringrequired

The channel which the inventory is being fulfilled for - e.g. RTV, RTS, Outlet.

Example: "active_ret"
shipment_identifierstringrequired

An identifier for this shipment, representing the Order Number, RA number, or other reference for that shipment.

Example: "WS3710296-213344"
tracking_numberstring

The tracking number or PRO number for containers in the shipment. If there are multiple different PRO numbers we only pass the first one scanned. There is no character limit on this attribute, Optoro will pass what is scanned. For stock transfers this will always be null.

Example: "1ZA0000000"
carrierstring

The carrier for the shipment. For stock transfers this will always be null.

Example: "UPS GROUND"
carrier_payment_typestring

How the carrier will be paid for this shipment, one of: “prepaid” or “collect”. For stock transfers this will always be null.

Example: "collect"
ship_datestringrequired

An iso8601 formatted date string representing when the ASN was or will be shipped (YYYY-MM-DDT00:00:00) in UTC. This value can be updated using the update endpoint (below).

Example: "2023-08-28T04:49:50.693Z"
statusstringrequired

Allowed values: “pending”, “shipped”, “delivered”, “canceled”.

Example: "shipped"
details_typestringrequired

This will always be “unit”.

Example: "unit"
cartonsArray of objects(cartons)required

Each object (carton) below represents a single box or pallet which has been shipped.

cartons[].​identifierstring

The scannable identifier for this carton.

Example: "T00028546"
cartons[].​referenceobject(reference)

Reference to a Stock Transfer Order, Return Authorization, RMA, Forward Order or Returns Portal Order which can be used to reconcile against. See below for fields.

cartons[].​detailsArray of objects(details)required

The sku or unit lines expected in this carton. See below for details fields.

cartons[].​details[].​line_identifierstringrequired

identifier for this line, unique within this ASN.

Example: "1"
cartons[].​details[].​program_identifierstringrequired

Identifies which program the unit was received into. The value will be provided by Optoro during implementation.

Example: "16_rma"
cartons[].​details[].​unit_identifierstringrequired

The Optiturn LP for this unit.

Example: "A0393197881"
cartons[].​details[].​client_unit_identifierstring

Client unique Identifier

Example: "B04847382"
cartons[].​details[].​inbound_received_asnstring

Inbound ASN Number associated with the unit at receiving

Example: "d470a87c-4f63-4f0e-bc76-4683247bc434"
cartons[].​details[].​skustringrequired

The SKU for this item

Example: "768983020002"
cartons[].​details[].​upcstring

The UPC for this item

Example: "500097771079"
cartons[].​details[].​quantityintegerrequired

Always 1 for now, present to match up with standard ASN fields, but all Optiturn generated ASNs will be unit level.

Example: 1
cartons[].​details[].​vendor_identifierstring

The identifier for this unit’s vendor or supplier.

Example: "Bradtke and Streich"
cartons[].​details[].​serial_numberstring

Serial number for this unit

Example: "11"
cartons[].​details[].​conditionstringrequired

Condition determined by Optiturn driven warehouse processes. One of N,A,R,B,TT,C,X

Enum"N""A""R""B""TT""C""X"
Example: "TT"
cartons[].​details[].​eligibility_flagsArray of arrays

These are the eligibility flags passed on the inbound ASN and configured in OptiTurn

Example: ["64"]
cartons[].​details[].​merchantstring

Merchant name for the unit

Example: "POLO RALPH LAUREN"
cartons[].​sorting_template_namestring

Name of the last assigned directed sorting template to this carton

Example: "Disposable Items"
bol_numberstring

The BOL number on the freight shipment.

Example: "21"
timestampstring

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

Example: "2023-08-29T03:41:16.848Z"
curl -i -X POST \
  https://developer.optoro.com/_mock/openapi/outbound_asn/openapi/outbound_asn \
  -H 'Content-Type: application/json' \
  -d '{
    "from": {
      "identifier": "16",
      "type": "warehouse"
    },
    "to": {
      "identifier": "07",
      "type": "warehouse",
      "address": {
        "name": "Bliss Diamond",
        "company": "Acme",
        "street": "6001 N Dr South",
        "street2": "60 N Dr North",
        "city": "LIBERTYVILLE",
        "state": "OH",
        "zip": "43125"
      }
    },
    "asn_number": "1498456_7417412",
    "channel": "active_ret",
    "shipment_identifier": "WS3710296-213344",
    "tracking_number": "1ZA0000000",
    "carrier": "UPS GROUND",
    "carrier_payment_type": "collect",
    "ship_date": "2023-08-28T04:49:50.693Z",
    "status": "shipped",
    "details_type": "unit",
    "cartons": [
      {
        "identifier": "T00028546",
        "reference": {
          "type": "RA",
          "identifier": "573001000000",
          "alternate_identifier": "742769019332"
        },
        "details": [
          {
            "line_identifier": "1",
            "program_identifier": "16_rma",
            "unit_identifier": "A0393197881",
            "client_unit_identifier": "B04847382",
            "inbound_received_asn": "d470a87c-4f63-4f0e-bc76-4683247bc434",
            "sku": "768983020002",
            "upc": "500097771079",
            "quantity": 1,
            "vendor_identifier": "Bradtke and Streich",
            "serial_number": "11",
            "condition": "TT",
            "eligibility_flags": [
              "64"
            ],
            "merchant": "POLO RALPH LAUREN"
          }
        ],
        "sorting_template_name": "Disposable Items"
      }
    ],
    "bol_number": "21",
    "timestamp": "2023-08-29T03:41:16.848Z"
  }'

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.