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.
API Specifications
/Returns Management
/- Inbound Advance Shipping Notice API
Create an ASN
Update an ASN
Forward Orders (DEPRECATED)
Create/Update Forward Orders.
RTV Vendor API
Create or update a vendor
Inbound Advance Shipping...
Inbound Advance Shipping Notice API (1.0.0)
Download OpenAPI description
Overview
Languages
Servers
Mock server
https://developer.optoro.com/_mock/openapi/asn/openapi
Production
https://asn.optiturn.com
Sandbox
https://asn.sandbox.optiturn.com
Staging
https://asn.stage.optiturn.com
Headers
Bodyapplication/jsonrequiredThere 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.
Enum12
Example: 1
Identifies which program this ASN belongs to for operational processes, financials and reporting. The value will be provided by Optoro during implementation.
Example: "consumer_returns"
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.
Example: "SO00001234"
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.
Example: "SI1ZAAAAAAZZ97764680"
The tracking number or BOL for the shipment. This is a scannable identifier in Receiving.
Example: "1Z123123123123"
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.
Example: "2019-03-15T00:00:00Z"
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"
Example: "shipped"
- 'unit':
details.unit_identifiermust be provided and other per unit keys are allowed. - 'sku':
details.skuanddetails.quantitykeys required, per unit keys disallowed. Only one type is allowed to make matching during receiving manageable.
Enum"unit""sku"
Example: "unit"
Optional, the type of ASN. Blanket type ASNs remove validations around units and overages.
Example: "MR"
Each object (carton) below represents a single box or pallet which has been shipped.
The scannable identifier for this carton which may be used in Receiving.
Example: "CTAA1234567"
The sku or unit lines expected in this carton.
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.
Example: 123456789
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.
Example: 123456891011
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.
Example: 1
The SKU for this item. Can be used to match to the details.line_identifier during receiving.
Example: "S123456"
The UPC for this item. Only allows letters and numbers, whitespaces are not allowed.
Example: 12345678905
For unit type ASNs, this must be 1. For sku type ASNs, the number of items for this sku in this carton.
Example: 1
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.
Example: "vnd_3001"
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.
Example: 12345689
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.
Example: "N"
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.
Example: [["personalized"]]
Valid for unit type ASNs. An iso8601 formatted date string representing when the detail line was sold. Used for eligibility and dispositioning.
Example: "2021-01-10T00:00:00Z"
Valid for unit type ASNs. An iso8601 formatted date string representing when the detail line was returned.
Example: "2021-01-10T00:00:00Z"
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.
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.
Example: "Best Buy"
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.
Example: "Insignia"
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.
Example: 1234567890
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.
Example: "Wrong Item Sent"
- Mock serverhttps://developer.optoro.com/_mock/openapi/asn/openapi/asns
- Productionhttps://asn.optiturn.com/asns
- Sandboxhttps://asn.sandbox.optiturn.com/asns
- Staginghttps://asn.stage.optiturn.com/asns
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://developer.optoro.com/_mock/openapi/asn/openapi/asns \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-H 'api-version: 1' \
-d '{
"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",
"set_identifier": "SET-S123456"
}
]
}
],
"messagetimestamp": "2019-10-16T10:59:20"
}'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.
Response
No contentRequest
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.
Security
jwtAuth
Headers
Bodyapplication/jsonrequiredThere 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.
Enum12
Example: 1
Identifies which program this ASN belongs to for operational processes, financials and reporting. The value will be provided by Optoro during implementation.
Example: "consumer_returns"
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.
Example: "SO00001234"
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.
Example: "SI1ZAAAAAAZZ97764680"
The tracking number or BOL for the shipment. This is a scannable identifier in Receiving.
Example: "1Z123123123123"
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.
Example: "2019-03-15T00:00:00Z"
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"
Example: "shipped"
- 'unit':
details.unit_identifiermust be provided and other per unit keys are allowed. - 'sku':
details.skuanddetails.quantitykeys required, per unit keys disallowed. Only one type is allowed to make matching during receiving manageable.
Enum"unit""sku"
Example: "unit"
Optional, the type of ASN. Blanket type ASNs remove validations around units and overages.
Example: "MR"
Each object (carton) below represents a single box or pallet which has been shipped.
The scannable identifier for this carton which may be used in Receiving.
Example: "CTAA1234567"
The sku or unit lines expected in this carton.
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.
Example: 123456789
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.
Example: 123456891011
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.
Example: 1
The SKU for this item. Can be used to match to the details.line_identifier during receiving.
Example: "S123456"
The UPC for this item. Only allows letters and numbers, whitespaces are not allowed.
Example: 12345678905
For unit type ASNs, this must be 1. For sku type ASNs, the number of items for this sku in this carton.
Example: 1
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.
Example: "vnd_3001"
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.
Example: 12345689
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.
Example: "N"
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.
Example: [["personalized"]]
Valid for unit type ASNs. An iso8601 formatted date string representing when the detail line was sold. Used for eligibility and dispositioning.
Example: "2021-01-10T00:00:00Z"
Valid for unit type ASNs. An iso8601 formatted date string representing when the detail line was returned.
Example: "2021-01-10T00:00:00Z"
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.
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.
Example: "Best Buy"
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.
Example: "Insignia"
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.
Example: 1234567890
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.
Example: "Wrong Item Sent"
- Mock serverhttps://developer.optoro.com/_mock/openapi/asn/openapi/asns/{asn-number}
- Productionhttps://asn.optiturn.com/asns/{asn-number}
- Sandboxhttps://asn.sandbox.optiturn.com/asns/{asn-number}
- Staginghttps://asn.stage.optiturn.com/asns/{asn-number}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PUT \
https://developer.optoro.com/_mock/openapi/asn/openapi/asns/SO00001234 \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-H 'api-version: 1' \
-d '{
"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",
"set_identifier": "SET-S123456"
}
]
}
],
"messagetimestamp": "2019-10-16T10:59:20"
}'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.
Response
No content