Outbound ASN (1.0.0)

Download OpenAPI specification:Download

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.

Outbound ASN Event

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.

Request
Request Body schema: application/json
required
object

The location this ASN is being sent from.

identifier
string

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.
type
string

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

required
object

The location this ASN is being sent to.

identifier
string

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
type
string

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

object (address)

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

name
required
string

The address to name.

company
string

The address company line (under name)

street
required
string

The street address.

street2
string

An optional second line for the street address, for suite or other similar additions.

city
required
string

The city for this address.

state
required
string

The state for this address.

zip
required
string

The zip code for this address.

asn_number
required
string

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”.

channel
required
string

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

shipment_identifier
required
string

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

tracking_number
string

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.

carrier
string

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

carrier_payment_type
string

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

ship_date
required
string

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).

status
required
string

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

details_type
required
string

This will always be “unit”.

required
Array of objects (cartons)

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

Array
identifier
string

The scannable identifier for this carton.

object (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.

type
required
string

Reference type, allowed values are: StockTransferOrder, RA, RMA, ForwardOrder or ReturnsPortalOrder.

identifier
required
string

Reference identifier - for example: the RMA number or RA Number associated with this shipment. This is a pass through from the inbound ASN.

alternate_identifier
string

Secondary reference identifier.

required
Array of objects (details)

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

Array
line_identifier
required
string

identifier for this line, unique within this ASN.

program_identifier
required
string

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

unit_identifier
required
string

The Optiturn LP for this unit.

client_unit_identifier
string

Client unique Identifier

inbound_received_asn
string

Inbound ASN Number associated with the unit at receiving

sku
required
string

The SKU for this item

upc
string

The UPC for this item

quantity
required
integer

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

vendor_identifier
string

The identifier for this unit’s vendor or supplier.

serial_number
string

Serial number for this unit

condition
required
string

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

Enum: "N" "A" "R" "B" "TT" "C" "X"
eligibility_flags
Array of arrays

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

sorting_template_name
string

Name of the last assigned directed sorting template to this carton

bol_number
string

The BOL number on the freight shipment.

timestamp
string

iso8601 formatted date string (YYYY-MM-DDT00:00:00) 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 from the client’s services and retry the request.

422

Validation Failure

500

Internal Server Error

502

Client Server Unavailable

post/outbound_asn
Request samples
application/json
{
  • "from": {
    },
  • "to": {
    },
  • "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": [
    ],
  • "bol_number": "21",
  • "timestamp": "2023-08-29T03:41:16.848Z"
}
Response samples
application/json
{
  • "message": "Success"
}
© 2010 – 2024 Optoro, Inc. For official use only by authorized users. Use subject to terms of license agreement.