Inbound Advance Shipping Notice API (1.0.0)

Download OpenAPI specification:Download

The Inbound Advance Shipping Notice API allows clients to notify our system when a shipment is inbound. The data sent will be used to receive and reconcile against.

Create an ASN

SecurityjwtAuth

Request

header Parameters

api-version

required

string

There are currently two supported versions of the Inbound Advance Shipping Notice API. Version 2 adds support for the details.labels array. By default requests to the Inbound Advance Shipping Notice API will use version 1. To explicitly set which version of the API to use clients must set the api-version HTTP header.

Enum: 1 2

Example: 1

Request Body schema: application/json

program_identifier

required

string

Identifies which program this ASN belongs to for operational processes, financials and reporting. The value will be provided by Optoro during implementation.

required

object (From)

identifier required	string Identifier for the from location visible in reporting. ie Numeric Warehouse ID, Store Number, Ecom
type required	string Type of the from location visible in reporting. ie Warehouse, Ecom, Returns Portal, Store

required

object (To)

identifier required	string Identifier for the to location visible in reporting. ie Numeric Warehouse ID, Store Number.
type required	string Type of the to location visible in reporting. ie Warehouse, Store, Customer

asn_number

required

string

A reference number for this ASN, typically this is an RMA Number or Transfer Number. This must be unique per program identifier. This is a scannable identifier in Receiving.

shipment_identifier

string

A reference number which may be used to identify multiple ASNs which were created against a single Order, RMA, or Transfer. This may be the order_identifier, the PO Number or the RMA Number. This is a scannable identifier in Receiving.

tracking_number

string

The tracking number or BOL for the shipment. This is a scannable identifier in Receiving.

carrier

string

The carrier for the shipment.

ship_date

string <date-time>

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

status

required

string

This value can be updated using the update endpoint. Cancelled status will block receiving. *Note passing 'canceled' with one 'l' will not be recognized by our system.

Enum: "pending" "shipped" "delivered" "cancelled"

details_type

required

string

'unit': details.unit_identifier must be provided and other per unit keys are allowed.
'sku': details.sku and details.quantity keys required, per unit keys disallowed. Only one type is allowed to make matching during receiving manageable.

Enum: "unit" "sku"

asn_type

string

Optional, the type of ASN. Blanket type ASNs remove validations around units and overages.

required

Array of objects (Carton)

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

Array

identifier

string

The scannable identifier for this carton which may be used in Receiving.

object (Reference)

type	string Reference type. Enum: "StockTransferOrder" "RA" "RMA" "ForwardOrder"
identifier	string Reference identifier, used with `reference.type` to find the reference during receiving. This is a scannable identifier in Receiving.
alternate_identifier	string Reference alternate identifier, should be scannable, used to locate the reference during receiving if the main identifier isn't always physically on the carton.

required

Array of objects (Detail)

The sku or unit lines expected in this carton.

Array

line_identifier

required

string

The systematic identifier for this line. For ecommerce parcel returns, this is typically the RMA line identifier or order line identifier. For Wholesale or Store returns this might be a specific identifier for the shipment line or you can pass '1' for the first line and then increment by '1' per additional line.

unit_identifier

string

If the details_type is 'unit', this attribute denotes the scannable identifier for this unit, which can be, used to match to the details.line_identifier during receiving. This value needs to be unique across all ASNs provided by the customer to Optoro.

reference_line_identifier

string

This is an optional field for any additional scannable identifiers that could be on the line item that Optoro will match to the details.line_identifier during receiving. This could be used if there is a separate barcode on the product that is not a SKU or UPC barcode.

sku

required

string

The SKU for this item. Can be used to match to the details.line_identifier during receiving.

upc

string

The UPC for this item. Only allows letters and numbers, whitespaces are not allowed.

quantity

required

integer

For unit type ASNs, this must be 1. For sku type ASNs, the number of items for this sku in this carton.

vendor_identifier

string

The identifier for this unit or SKU/quantity's vendor or supplier. This field is required if using Optoro's RTV Module. It is used for determining RTV eligibility and fulfillment.

serial_number

string

Serial number for this unit. Only permitted on Unit type ASNs. Can be used to match to the details.line_identifierline during receiving. Only allows letters and numbers, whitespaces are not allowed.

condition

string

Optional field denoting the condition of the product as reported by the transferring location. This will appear in Optoro's inbound and received shipments reporting.

eligibility_flags

Array of strings

Optional array identifying specific flags about a unit used to determine eligibility for RTV. If one of these flags is present on the ASN and the vendor in Optoro's Vendor Management module has this flag 'checked' then the unit will be blocked from RTV.

sell_date

string <date-time>

Valid for unit type ASNs. An iso8601 formatted date string representing when the detail line was sold. Used for eligibility and dispositioning.

return_date

string <date-time>

Valid for unit type ASNs. An iso8601 formatted date string representing when the detail line was returned.

Array of objects (Label)

Optional object array, used for customers to pass up to two specific values they want printed on labels at receiving or in the OptiTurn Rework Tool. This can be a barcode or a custom string. Currently only two values can be supported on the label print. Customers must be using version 2 of the API for this field.

Array

type required	string This indicates whether the field printed on the label should be text or a barcode. Allowed values - 'barcode' and 'text'. Enum: "barcode" "text"
name required	string This is the title of the field being printed. It is always readable as text. For example, if you want to print a SKU barcode on the label you can pass the SKU string in this field and the barcode in `label.value` field. Alternatively if you want to print the size of the product you should pass 'size' in this field and the size of the product (such as 'medium') in the `label.value` field.
value required	string The corresponding value of the `label.name`. If 'barcode' is passed in `label.type` then the value will always be printed as a barcode.

merchant

string

The name of the merchant that sells the product. This field is required when a customer is processing returns for multiple merchants. It is used to uniquely identify the product when there is SKU or UPC overlap between merchants.

concept

string

The retail 'concept' or 'brand' to which the product belongs. This differentiates similar products when the customer's parent company has multiple retail brands. It is used to uniquely identify the product when there is SKU or UPC overlap within the same merchant.

asin

string

A 10-character alphanumeric unique identifier assigned to a product by Amazon.com and its partners. If there is a scannable ASIN on the unit of inventory this can be used to match to the details.line_identifier.

return_reason

string

This field can be used to identify a line item as a 'misship'. Your onboarding team can configure a setting to receive a unit with a SKU/UPC that is in your catalog but that does not match the ASN line if the 'misship' value is present. This value will be provided in the Inventory Receipt details.return_reason field.

messagetimestamp

string <date-time>

Optional, a timestamp denoting when the ASN message was sent.

Responses

202

The ASN API will return a HTTP status code 202 to indicate that the request was processed successfully and that the provided ASN is queued for creation.

400

Error response will be HTTP status code 400 for other bad/unparseable requests.

401

Error response will be HTTP status code 401 for missing or bad api_key (these have no body).

422

Error response will be HTTP status code 422 for validation errors (missing or invalid fields in this case).

post/asns

Request samples

Payload

application/json

{"program_identifier": "consumer_returns",
"from": {"identifier": 22,
"type": "Warehouse"
},
"to": {"identifier": 1352,
"type": "Store"
},
"asn_number": "SO00001234",
"shipment_identifier": "SI1ZAAAAAAZZ97764680",
"tracking_number": "1Z123123123123",
"carrier": "UPS",
"ship_date": "2019-03-15T00:00:00Z",
"status": "shipped",
"details_type": "unit",
"asn_type": "MR",
"cartons": [{"identifier": "CTAA1234567",
"reference": {"type": "RMA",
"identifier": 12345,
"alternate_identifier": "OR12345678"
},
"details": [{"line_identifier": 123456789,
"unit_identifier": 123456891011,
"reference_line_identifier": 1,
"sku": "S123456",
"upc": 12345678905,
"quantity": 1,
"vendor_identifier": "vnd_3001",
"serial_number": 12345689,
"condition": "N",
"eligibility_flags": [["personalized"
]
],
"sell_date": "2021-01-10T00:00:00Z",
"return_date": "2021-01-10T00:00:00Z",
"labels": [{"type": "text",
"name": "title",
"value": "Printing this title"
}
],
"merchant": "Best Buy",
"concept": "Insignia",
"asin": 1234567890,
"return_reason": "Wrong Item Sent"
}
]
}
],
"messagetimestamp": "2019-10-16T10:59:20"
}

Response samples

application/json

{"message": "Validation Failed",
"errors": [{"field": "reference_number",
"code": "missing_field"
}
]
}

Update an ASN

ASNs may be updated to change the status of the ASN overall or the status of a detail line. See above for permitted status values. ASN Number should be included as part of the url. ASNs can be updated only when they are active and have no receptions.

SecurityjwtAuth

Request

path Parameters

asn-number

required

string

Example: SO00001234

header Parameters

api-version

required

string

Enum: 1 2

Example: 1

Request Body schema: application/json

program_identifier

required

string

Identifies which program this ASN belongs to for operational processes, financials and reporting. The value will be provided by Optoro during implementation.

required

object (From)

identifier required	string Identifier for the from location visible in reporting. ie Numeric Warehouse ID, Store Number, Ecom
type required	string Type of the from location visible in reporting. ie Warehouse, Ecom, Returns Portal, Store

required

object (To)

identifier required	string Identifier for the to location visible in reporting. ie Numeric Warehouse ID, Store Number.
type required	string Type of the to location visible in reporting. ie Warehouse, Store, Customer

asn_number

required

string

A reference number for this ASN, typically this is an RMA Number or Transfer Number. This must be unique per program identifier. This is a scannable identifier in Receiving.

shipment_identifier

string

tracking_number

string

The tracking number or BOL for the shipment. This is a scannable identifier in Receiving.

carrier

string

The carrier for the shipment.

ship_date

string <date-time>

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

status

required

string

This value can be updated using the update endpoint. Cancelled status will block receiving. *Note passing 'canceled' with one 'l' will not be recognized by our system.

Enum: "pending" "shipped" "delivered" "cancelled"

details_type

required

string

'unit': details.unit_identifier must be provided and other per unit keys are allowed.
'sku': details.sku and details.quantity keys required, per unit keys disallowed. Only one type is allowed to make matching during receiving manageable.

Enum: "unit" "sku"

asn_type

string

Optional, the type of ASN. Blanket type ASNs remove validations around units and overages.

required

Array of objects (Carton)

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

Array

identifier

string

The scannable identifier for this carton which may be used in Receiving.

object (Reference)

type	string Reference type. Enum: "StockTransferOrder" "RA" "RMA" "ForwardOrder"
identifier	string Reference identifier, used with `reference.type` to find the reference during receiving. This is a scannable identifier in Receiving.
alternate_identifier	string Reference alternate identifier, should be scannable, used to locate the reference during receiving if the main identifier isn't always physically on the carton.

required

Array of objects (Detail)

The sku or unit lines expected in this carton.

Array

line_identifier

required

string

unit_identifier

string

reference_line_identifier

string

sku

required

string

The SKU for this item. Can be used to match to the details.line_identifier during receiving.

upc

string

The UPC for this item. Only allows letters and numbers, whitespaces are not allowed.

quantity

required

integer

For unit type ASNs, this must be 1. For sku type ASNs, the number of items for this sku in this carton.

vendor_identifier

string

The identifier for this unit or SKU/quantity's vendor or supplier. This field is required if using Optoro's RTV Module. It is used for determining RTV eligibility and fulfillment.

serial_number

string

Serial number for this unit. Only permitted on Unit type ASNs. Can be used to match to the details.line_identifierline during receiving. Only allows letters and numbers, whitespaces are not allowed.

condition

string

Optional field denoting the condition of the product as reported by the transferring location. This will appear in Optoro's inbound and received shipments reporting.

eligibility_flags

Array of strings

sell_date

string <date-time>

Valid for unit type ASNs. An iso8601 formatted date string representing when the detail line was sold. Used for eligibility and dispositioning.

return_date

string <date-time>

Valid for unit type ASNs. An iso8601 formatted date string representing when the detail line was returned.

Array of objects (Label)

Array

type required	string This indicates whether the field printed on the label should be text or a barcode. Allowed values - 'barcode' and 'text'. Enum: "barcode" "text"
name required	string This is the title of the field being printed. It is always readable as text. For example, if you want to print a SKU barcode on the label you can pass the SKU string in this field and the barcode in `label.value` field. Alternatively if you want to print the size of the product you should pass 'size' in this field and the size of the product (such as 'medium') in the `label.value` field.
value required	string The corresponding value of the `label.name`. If 'barcode' is passed in `label.type` then the value will always be printed as a barcode.

merchant

string

concept

string

asin

string

return_reason

string

messagetimestamp

string <date-time>

Optional, a timestamp denoting when the ASN message was sent.

Responses

202

The ASN API will return a HTTP status code 202 to indicate that the request was processed successfully and that the provided ASN is queued for creation.

400

Error response will be HTTP status code 400 for other bad/unparseable requests.

401

Error response will be HTTP status code 401 for missing or bad api_key (these have no body).

422

Error response will be HTTP status code 422 for validation errors (missing or invalid fields in this case).

put/asns/{asn-number}

Request samples

Payload

application/json

{"program_identifier": "consumer_returns",
"from": {"identifier": 22,
"type": "Warehouse"
},
"to": {"identifier": 1352,
"type": "Store"
},
"asn_number": "SO00001234",
"shipment_identifier": "SI1ZAAAAAAZZ97764680",
"tracking_number": "1Z123123123123",
"carrier": "UPS",
"ship_date": "2019-03-15T00:00:00Z",
"status": "shipped",
"details_type": "unit",
"asn_type": "MR",
"cartons": [{"identifier": "CTAA1234567",
"reference": {"type": "RMA",
"identifier": 12345,
"alternate_identifier": "OR12345678"
},
"details": [{"line_identifier": 123456789,
"unit_identifier": 123456891011,
"reference_line_identifier": 1,
"sku": "S123456",
"upc": 12345678905,
"quantity": 1,
"vendor_identifier": "vnd_3001",
"serial_number": 12345689,
"condition": "N",
"eligibility_flags": [["personalized"
]
],
"sell_date": "2021-01-10T00:00:00Z",
"return_date": "2021-01-10T00:00:00Z",
"labels": [{"type": "text",
"name": "title",
"value": "Printing this title"
}
],
"merchant": "Best Buy",
"concept": "Insignia",
"asin": 1234567890,
"return_reason": "Wrong Item Sent"
}
]
}
],
"messagetimestamp": "2019-10-16T10:59:20"
}

Response samples

application/json

{"message": "Validation Failed",
"errors": [{"field": "reference_number",
"code": "missing_field"
}
]
}