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
application/json
{
  • "program_identifier": "consumer_returns",
  • "from": {
    },
  • "to": {
    },
  • "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": [
    ],
  • "messagetimestamp": "2019-10-16T10:59:20"
}
Response samples
application/json
{
  • "message": "Validation Failed",
  • "errors": [
    ]
}

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

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

put/asns/{asn-number}
Request samples
application/json
{
  • "program_identifier": "consumer_returns",
  • "from": {
    },
  • "to": {
    },
  • "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": [
    ],
  • "messagetimestamp": "2019-10-16T10:59:20"
}
Response samples
application/json
{
  • "message": "Validation Failed",
  • "errors": [
    ]
}
© 2010 – 2024 Optoro, Inc. For official use only by authorized users. Use subject to terms of license agreement.