openapi: 3.2.0 info: title: Inbound Advance Shipping Notice Asns API description: 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. version: 1.0.0 contact: name: Receiving servers: - url: https://asn.optiturn.com description: Production - url: https://asn.sandbox.optiturn.com description: Sandbox - url: https://asn.stage.optiturn.com description: Staging security: - jwtAuth: [] tags: - name: Asns paths: /asns: post: summary: Create an ASN parameters: - name: api-version in: header description: 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. required: true schema: type: string enum: - 1 - 2 example: 1 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdvanceShipNotice' responses: '202': description: 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': description: Error response will be HTTP status code 400 for other bad/unparseable requests. '401': description: Error response will be HTTP status code 401 for missing or bad api_key (these have no body). '422': description: Error response will be HTTP status code 422 for validation errors (missing or invalid fields in this case). content: application/json: schema: properties: message: type: string example: Validation Failed errors: type: array items: properties: field: type: string example: reference_number code: type: string example: missing_field tags: - Asns /asns/{asn-number}: put: summary: Update an ASN description: 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. parameters: - name: api-version in: header description: 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. required: true schema: type: string enum: - 1 - 2 example: 1 - name: asn-number in: path required: true schema: type: string example: SO00001234 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdvanceShipNotice' responses: '202': description: 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': description: Error response will be HTTP status code 400 for other bad/unparseable requests. '401': description: Error response will be HTTP status code 401 for missing or bad api_key (these have no body). '422': description: Error response will be HTTP status code 422 for validation errors (missing or invalid fields in this case). content: application/json: schema: properties: message: type: string example: Validation Failed errors: type: array items: properties: field: type: string example: reference_number code: type: string example: missing_field tags: - Asns components: schemas: Detail: required: - line_identifier - sku - quantity properties: line_identifier: type: string example: 123456789 description: 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: type: string example: 123456891011 description: 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: type: string example: 1 description: 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: type: string example: S123456 description: The SKU for this item. Can be used to match to the `details.line_identifier` during receiving. upc: type: string example: 12345678905 description: The UPC for this item. Only allows letters and numbers, whitespaces are not allowed. quantity: type: integer example: 1 description: For unit type ASNs, this must be 1. For sku type ASNs, the number of items for this sku in this carton. vendor_identifier: type: string example: vnd_3001 description: 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: type: string example: 12345689 description: 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: type: string example: N description: 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: type: array items: type: string example: - personalized description: 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: type: string format: date-time example: '2021-01-10T00:00:00Z' description: Valid for unit type ASNs. An iso8601 formatted date string representing when the detail line was sold. Used for eligibility and dispositioning. return_date: type: string format: date-time example: '2021-01-10T00:00:00Z' description: Valid for unit type ASNs. An iso8601 formatted date string representing when the detail line was returned. labels: type: array items: $ref: '#/components/schemas/Label' description: 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. merchant: type: string example: Best Buy description: 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: type: string example: Insignia description: 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: type: string example: 1234567890 description: 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: type: string example: Wrong Item Sent description: 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. set_identifier: type: string example: SET-S123456 description: Optional field to group the items. This field is applicable only when the `details_type` is 'unit'. Label: required: - type - name - value properties: type: type: string enum: - barcode - text example: text description: This indicates whether the field printed on the label should be text or a barcode. Allowed values - 'barcode' and 'text'. name: type: string example: title description: 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: type: string example: Printing this title description: The corresponding value of the `label.name`. If 'barcode' is passed in `label.type` then the value will always be printed as a barcode. AdvanceShipNotice: required: - program_identifier - from - to - asn_number - status - details_type - cartons properties: program_identifier: type: string example: consumer_returns description: Identifies which program this ASN belongs to for operational processes, financials and reporting. The value will be provided by Optoro during implementation. from: type: object $ref: '#/components/schemas/From' description: The location this ASN is being sent from. to: type: object $ref: '#/components/schemas/To' description: The location this ASN is being sent to. asn_number: type: string example: SO00001234 description: 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: type: string example: SI1ZAAAAAAZZ97764680 description: 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: type: string example: 1Z123123123123 description: The tracking number or BOL for the shipment. This is a scannable identifier in Receiving. carrier: type: string example: UPS description: The carrier for the shipment. ship_date: type: string format: date-time example: '2019-03-15T00:00:00Z' description: 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: type: string enum: - pending - shipped - delivered - cancelled example: shipped description: 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. details_type: type: string enum: - unit - sku example: unit description: '- ''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. ' asn_type: type: string example: MR description: Optional, the type of ASN. Blanket type ASNs remove validations around units and overages. cartons: type: array items: $ref: '#/components/schemas/Carton' description: Each object (carton) below represents a single box or pallet which has been shipped. messagetimestamp: type: string format: date-time example: '2019-10-16T10:59:20' description: Optional, a timestamp denoting when the ASN message was sent. To: required: - identifier - type properties: identifier: type: string example: 1352 description: Identifier for the to location visible in reporting. ie Numeric Warehouse ID, Store Number. type: type: string example: Store description: Type of the to location visible in reporting. ie Warehouse, Store, Customer From: required: - identifier - type properties: identifier: type: string example: 22 description: Identifier for the from location visible in reporting. ie Numeric Warehouse ID, Store Number, Ecom type: type: string example: Warehouse description: Type of the from location visible in reporting. ie Warehouse, Ecom, Returns Portal, Store Carton: required: - details properties: identifier: type: string example: CTAA1234567 description: The scannable identifier for this carton which may be used in Receiving. reference: type: object $ref: '#/components/schemas/Reference' description: Reference to a StockTransferOrder, RMA or ForwardOrder with additional information used for receiving and reconciling this ASN. details: type: array items: $ref: '#/components/schemas/Detail' description: The sku or unit lines expected in this carton. Reference: properties: type: type: string enum: - StockTransferOrder - RA - RMA - ForwardOrder - ReturnsPortalOrder example: RMA description: Reference type. identifier: type: string example: 12345 description: Reference identifier, used with `reference.type` to find the reference during receiving. This is a scannable identifier in Receiving. alternate_identifier: type: string example: OR12345678 description: Reference alternate identifier, should be scannable, used to locate the reference during receiving if the main identifier isn't always physically on the carton. securitySchemes: jwtAuth: type: http scheme: bearer bearerFormat: JWT