> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loopreturns.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced Shipping Notice

> This endpoint will pull all packages by tracking statuses/timeframe. The ASN endpoint will return an array of
objects. Those objects will contain order and return information.

**Version Note (2026-10+)**: `from` and `to` must be parseable dates, and the range between them
must not exceed 120 days (a range of exactly 120 days is allowed). Requests that break either
rule return HTTP 422 with a validation error on both `from` and `to`. Earlier versions accept
any range and fall back to the Unix epoch for unparseable values.

### Required API key scope
- Returns




## OpenAPI

````yaml get /warehouse/reporting/asn
openapi: 3.1.0
info:
  title: Returns API
  version: v1
  description: API used for performing operations on returns.
servers:
  - url: https://api.loopreturns.com/api/2026-10
    description: 2026-10 (Stable)
  - url: https://api.loopreturns.com/api/2026-07
    description: 2026-07
  - url: https://api.loopreturns.com/api/unstable
    description: Unstable (Preview)
security: []
tags:
  - name: Return Actions
  - name: Return Data
paths:
  /warehouse/reporting/asn:
    get:
      tags:
        - Return Data
      summary: Advanced Shipping Notice
      description: >
        This endpoint will pull all packages by tracking statuses/timeframe. The
        ASN endpoint will return an array of

        objects. Those objects will contain order and return information.


        **Version Note (2026-10+)**: `from` and `to` must be parseable dates,
        and the range between them

        must not exceed 120 days (a range of exactly 120 days is allowed).
        Requests that break either

        rule return HTTP 422 with a validation error on both `from` and `to`.
        Earlier versions accept

        any range and fall back to the Unix epoch for unparseable values.


        ### Required API key scope

        - Returns
      operationId: getAdvancedShippingNotice
      parameters:
        - name: from
          example: '2023-08-21T00:00:00.000Z'
          in: query
          description: >
            The start of the date range. If omitted, defaults to one week ago at
            the start of the day.

            Before API version `2026-10`, invalid values fall back to the Unix
            epoch.

            In API version `2026-10` and later, an unparseable value returns
            `422`, and the range from

            `from` to `to` must not exceed 120 days.
          schema:
            type: string
            format: date
            examples:
              - '2023-08-21T00:00:00.000Z'
        - name: to
          example: '2023-08-22T00:00:00.000Z'
          in: query
          description: >
            The end of the date range. If omitted, defaults to the end of the
            current day.

            Before API version `2026-10`, invalid values fall back to the Unix
            epoch.

            In API version `2026-10` and later, an unparseable value returns
            `422`, and the range from

            `from` to `to` must not exceed 120 days.
          schema:
            type: string
            format: date
            examples:
              - '2023-08-21T00:00:00.000Z'
      responses:
        '200':
          $ref: '#/components/responses/AsnReport'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: >
            Unprocessable Entity. In API version `2026-10` and later, returned
            when `from` or `to` is not a

            parseable date, or when the range between them exceeds 120 days. The
            same message is reported

            under both `from` and `to`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Summary of the validation errors.
                  errors:
                    type: object
                    properties:
                      from:
                        type: array
                        items:
                          type: string
                      to:
                        type: array
                        items:
                          type: string
              examples:
                rangeTooLong:
                  summary: Date range exceeds 120 days
                  value:
                    message: >-
                      The from and to range exceeds the allowable max of 120
                      days (and 1 more error)
                    errors:
                      from:
                        - >-
                          The from and to range exceeds the allowable max of 120
                          days
                      to:
                        - >-
                          The from and to range exceeds the allowable max of 120
                          days
                invalidDate:
                  summary: Unparseable date
                  value:
                    message: >-
                      The from and to field must be a valid ATOM date. (and 1
                      more error)
                    errors:
                      from:
                        - The from and to field must be a valid ATOM date.
                      to:
                        - The from and to field must be a valid ATOM date.
      security:
        - api_key: []
components:
  responses:
    AsnReport:
      description: Success
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/AsnReport'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            required:
              - errors
            properties:
              errors:
                type: string
                examples:
                  - Unauthorized.
  schemas:
    AsnReport:
      type: object
      properties:
        id:
          type: integer
          examples:
            - 17
          description: The unique identifier associated with the ASN report.
        return_line_item_id:
          type: string
          examples:
            - '36'
          description: The unique identifier associated with the line item.
        order_id:
          type: string
          examples:
            - '2685651685584'
          description: The unique identifier associated with the order.
        order_name:
          type: string
          examples:
            - '#1138'
          description: The name of the order.
        order_number:
          type: string
          examples:
            - '138'
          description: The order number.
        provider_order_number:
          type: string
          examples:
            - '1138'
          description: The order number from the commerce provider (e.g. Shopify).
        state:
          $ref: '#/components/schemas/ReturnState'
          description: The status of the return.
        customer_email:
          type: string
          examples:
            - h.testman@loopreturns.com
          description: The customer's email address.
        title:
          type: string
          examples:
            - Mens Large Hydrostatic Inflatable PFD
          description: The product's name.
        purchase_price:
          type: string
          examples:
            - '199.99'
          description: The product's purchase price.
        sku:
          type: string
          examples:
            - ad-alias-corporis-cum-ut-facilis-sed-non
          description: The SKU associated with the product.
        barcode:
          type: string
          examples:
            - '789765484987'
          description: The barcode of the product.
        carrier:
          type: string
          examples:
            - USPS
          description: The carrier associated with the return.
        service:
          type: string
          examples:
            - Parcel Select
          description: The service used to ship the return.
        label_status:
          type: string
          examples:
            - out_for_delivery
          description: The delivery status of the return.
        tracking_number:
          type: string
          examples:
            - '9999999999999999999999'
          description: The tracking number associated with the return.
        integration_tracking_url:
          type: string
          examples:
            - N/A
          description: The link to the tracking details.
        restock_status:
          type: string
          examples:
            - restocked
          description: The restock status of the return.
        currency:
          type: string
          examples:
            - USD
          description: The currency code of the store's default currency.
        label_updated_at:
          type: string
          format: date-time
          examples:
            - '2023-08-21T14:09:17.000Z'
          description: >-
            The date and time at which the label was last updated, using the ISO
            8601 date format.
        label_url:
          type: string
          examples:
            - >-
              https://test-bucket.s3-us-west-2.amazonaws.com/files/postage_label/01234567/0df7eea6147b44b7ac204e9eb8293cfa.pdf
          description: The link to the shipping label.
        label_rate:
          type: string
          examples:
            - '250'
          description: The shipping rate paid for the return label.
        closed_at:
          type: string
          format: date-time
          examples:
            - '2023-09-01T14:00:41.000Z'
          description: >-
            The date and time at which the return was closed, using the ISO 8601
            date format.
        updated_at:
          type: string
          format: date-time
          examples:
            - '2023-08-21T14:06:32.000Z'
          description: >-
            The date and time at which the return was last updated, using the
            ISO 8601 date format.
        created_at:
          type: string
          format: date-time
          examples:
            - '2023-08-21T14:05:56.000Z'
          description: >-
            The date and time at which the return was created, using the ISO
            8601 date format.
        return_reason:
          type: string
          examples:
            - Size was too small
          description: The specific reason for return given by the customer.
        actioned_by:
          type: string
          examples:
            - N/A
          description: The method in which the return was actioned.
        return_method:
          type: string
          examples:
            - happy-returns
          description: The return method.
        return_method_rma_code:
          type: string
          examples:
            - HR01234
          description: The return material authorization code.
        return_method_state:
          type: string
          examples:
            - in_transit
          description: The status of the return.
        date_delivered:
          type: string
          examples:
            - N/A
          description: The delivery date of the return.
        outcome:
          $ref: '#/components/schemas/ReturnOutcome'
          description: >-
            The outcome of the return as limited by the merchant and as selected
            by the customer.
        scannable_id:
          type: string
          examples:
            - N/A
          description: The scannable identifier of the return.
        package_reference:
          type: string
          examples:
            - '9999999999999999999999'
          description: The package reference of the return.
        shipping_box_barcode:
          type: string
          examples:
            - N/A
          description: The barcode for the box in which the return was shipped.
        provider_created_at:
          type: string
          format: date-time
          examples:
            - '2021-01-01T10:00:00.000Z'
          description: >
            The date and time at which the return was created by the provider,
            using the ISO 8601 date format.
        destination_id:
          type: string
          examples:
            - '17'
          description: The unique identifier associated with the return's destination.
        destination_name:
          type: string
          examples:
            - Maine Warehouse
          description: The name of the destination.
        destination_address1:
          type: string
          examples:
            - 55 Maine Street
          description: The street address of the destination.
        destination_address2:
          type: string
          examples:
            - Unit 3
          description: The secondary address details of the destination.
        destination_city:
          type: string
          examples:
            - Portland
          description: The city in which the destination is located.
        destination_state:
          type: string
          examples:
            - Maine
          description: The state in which the destination is located.
        destination_zip:
          type: string
          examples:
            - '54321'
          description: The ZIP code of the destination.
        consolidation_tracking:
          type:
            - string
            - 'null'
          description: >
            If a line item is part of a consolidated shipment of many return
            items,

            this value holds the tracking value for

            the consolidated shipment that contains this item such as the

            Happy Returns Outbound Shipment tracking number.
    ReturnState:
      type: string
      enum:
        - open
        - closed
        - expired
        - cancelled
        - review
    ReturnOutcome:
      type: string
      enum:
        - exchange
        - upsell
        - refund
        - credit
        - exchange+refund
        - exchange+credit
  securitySchemes:
    api_key:
      type: apiKey
      name: X-Authorization
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.