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)
tags:
  - name: Return Actions
  - name: Return Data
paths:
  /warehouse/return/{id}/process:
    post:
      summary: Process Return
      operationId: processReturn
      description: |
        Process a return in Loop based on the return ID. Processing a return will archive it in Loop and
        fulfill any remaining outcomes, such as placing exchange orders or creating gift cards.

        > ⚡ **Processing Note**
        >
        > This endpoint queues the return for processing. The actual processing occurs in the background.
        > HTTP `200` with body `true` is an acknowledgement that Loop queued the work. It is not proof
        > that processing completed.

        ### Confirming the outcome

        After Loop returns `true`, confirm the terminal result with webhooks:

        - Success: [`return.closed`](/webhook-reference/topics/return-webhook) on the Return topic.
        - Background failure: [`return.processing.failed`](/webhook-reference/topics/return-processing-webhook)
          on the Return Processing topic.

        The failure webhook `message` can be generic or `null`. Do not treat it as a stable error code.

        This failure webhook does not cover synchronous refusals. If Loop refuses the request,
        the HTTP `200` response includes an `errors` body instead of `true`. Loop does not send
        `return.processing.failed` for that case.

        > **Note on instant refunds**
        >
        > If the return has an open Reshop instant-refund credit, processing is intentionally skipped: a
        > successful (`true`) response is returned without dispatching any processing jobs.

        Optionally, you may include a JSON payload in the request body. If you choose to do so, Loop will
        add these values to any new orders in the commerce provider (e.g. Shopify) that result from processing the
        return. For example, if the return includes an exchange when the return is processed, Loop will create
        that exchange order and these values will be added to the order as "Additional Details." Loop will also
        add a note to the return timeline with the values in the request body.
        > 🚧 Process Error Codes
        >
        > Returns must be in a processable state to successfully process. If your return is not in a
        > processable state, your response will include an `errors` object with a corresponding message and
        > error code.
        >
        >
        > If you would like to configure your flagged returns to process, please reach out to
        > support@loopreturns.com.

        ```json
        {
          "errors": {
            "message": "Return is open and therefore cannot be processed.",
            "code": "UNPROCESSABLE_FLAGGED_RETURN"
          }
        }
        ```

        ### Required API key scope
        - Returns

      tags:
        - Return Actions
      security:
        - api_key: []
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: The unique identifier associated with the return.
      responses:
        '200':
          $ref: '#/components/responses/ProcessReturn'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /warehouse/return/{id}/remove:
    post:
      summary: Remove Line Items
      operationId: removeLineItems
      description: |
        Remove one or more line items from an open return.

        Only returns whose outcome is entirely a refund or entirely store credit can be modified. Exchanges
        and mixed outcomes cannot.

        Removing items reduces the return total and its refund or gift card value.

        ### What happens to the return afterwards

        If the request removes every remaining item, the return is cancelled rather than processed, freeing
        the items for a new return. This is checked first, so it applies at any item count, whatever the
        outcome.

        Otherwise:

        - **Refund outcome**: the return is processed and closed and the remaining items refunded, without a
          separate call to [Process Return](/api-reference/latest/return-actions/process-return). A later
          call for the same return responds with a `422`.
        - **Store credit outcome**: the return stays open and further items can be removed. Reshop instant
          refunds count as a refund outcome and close the return.

        <Warning>
          On a refund return, pass every line item ID in a single comma separated request. Removing them one
          at a time fails: the first request closes the return.
        </Warning>

        ### Required API key scope
        - Returns
      tags:
        - Return Actions
      security:
        - api_key: []
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: The unique identifier associated with the return.
        - in: query
          name: line_item_id
          description: |
            The `line_item_id` of an item on the return, as listed in the return's `line_items` array. To
            remove more than one, pass them as comma separated values.
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/RemoveLineItems'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 'Forbidden'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoveReturnNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableRemove'
        '500':
          $ref: '#/components/responses/FailedToProcess'
  /warehouse/return/{id}/cancel:
    post:
      summary: Cancel Return
      operationId: cancelReturn
      description: |
        Cancel a return in Loop. Canceling a return will allow a customer to make another return with the same
        items.

        ### Required API key scope
        - Returns
      tags:
        - Return Actions
      security:
        - api_key: []
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: The unique identifier associated with the return.
      responses:
        '200':
          $ref: '#/components/responses/CancelReturn'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /warehouse/return/{id}/flag:
    post:
      summary: Flag Return
      operationId: flagReturn
      description: |
        Flag a return in Loop for review. This will prevent automated processing and will require a human to go
        into the merchant admin in Loop and review this return.

        ### Required API key scope
        - Returns
      tags:
        - Return Actions
      security:
        - api_key: []
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: The unique identifier associated with the return.
      responses:
        '200':
          $ref: '#/components/responses/FlagReturn'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /warehouse/return/{id}/close:
    post:
      summary: Close Return
      operationId: closeReturn
      description: |
        Close a return. Closing a return will not fulfill any outcomes such as exchanges or gift cards, and the
        items are not able to be used in a new return.

        Returns closed using this endpoint will also be closed in the commerce provider (e.g. Shopify).

        ### Required API key scope
        - Returns
      tags:
        - Return Actions
      security:
        - api_key: []
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: The unique identifier associated with the return.
      responses:
        '200':
          $ref: '#/components/responses/CloseReturn'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /warehouse/return/{id}/notes:
    get:
      summary: Get Return Notes
      operationId: getReturnNotes
      description: |
        Get notes on a specific return using the return's ID.

        ### Required API key scope
        - Returns
      tags:
        - Return Actions
      security:
        - api_key: []
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: The unique identifier associated with the return.
      responses:
        '200':
          $ref: '#/components/responses/ReturnNotes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/NoReturnNotes'
  /warehouse/return/{id}/note:
    post:
      summary: Create Return Note
      operationId: createReturnNote
      description: |
        Post a new note to a return.

        ### Required API key scope
        - Returns
      tags:
        - Return Actions
      security:
        - api_key: []
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: The unique identifier associated with the return.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReturnNoteRequest'
      responses:
        '200':
          $ref: '#/components/responses/CreateReturnNote'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 'Forbidden'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnActionError'
        '422':
          description: 'Unprocessable'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidContentForNoteResponse'
  /warehouse/return/list:
    get:
      tags:
        - Return Data
      security:
        - api_key: []
      summary: Detailed Returns List
      operationId: getDetailedReturnsList
      description: |
        Pull a detailed list of returns created within a given timeframe.

        This endpoint supports pagination. We _highly_
        encourage using [pagination](https://docs.loopreturns.com/reference/paginated-requests)
        for this endpoint. Read the guide on
        [paginating requests](https://docs.loopreturns.com/reference/paginated-requests)
        for details.

        **Note**: If neither `from` nor `to` is passed,
        the response defaults to only contain returns from the previous 24
        hours. See [`from`](#parameter-from) and [`to`](#parameter-to) below for more information.

        **Note**: The maximum number of days in the range of the from and to properties is 120 days.
        If the number of days
        in this range exceeds 120 days, a validation error will be returned.

        **Note**: If no `state` is passed, the response defaults to only contain open, closed, and expired returns. See
        [`state`](#parameter-state) below for more information.

        ### Required API key scope
        - Returns
      parameters:
        - name: from
          example: yyyy-mm-dd hh:mm:ss
          in: query
          description: >
            The start date and time for the returns list.
            If `from` is passed without `to`, returns created in the 24 hours after `from` are returned.
          schema:
            type: string
            examples:
              - 2022-01-01 00:00:00
        - name: to
          example: yyyy-mm-dd hh:mm:ss
          in: query
          description: >
            The end date and time for the returns list.
            If `to` is provided without `from`,
            the parameter is ignored and returns from the last 24 hours are returned.
          schema:
            type: string
            examples:
              - 2022-03-31 23:59:59
        - name: filter
          in: query
          description: |
            The date used to filter results.
          schema:
            type: string
            enum:
              - created_at
              - updated_at
            default: created_at
        - name: state
          example: open
          in: query
          description: |
            The keywords used to filter the list to only include returns in a particular state.
            Defaults to only contain open, closed, and expired returns.
          schema:
            type: string
            enum:
              - open
              - closed
              - cancelled
              - expired
              - review
        - name: paginate
          in: query
          description: |
            When present, enables cursor-based pagination. The response is then wrapped in an object
            containing `returns` plus `nextPageUrl`/`previousPageUrl`, rather than a bare array.
          schema:
            type: boolean
        - name: pageSize
          in: query
          description: The number of returns to return per page when paginating.
          schema:
            type: integer
        - name: cursor
          in: query
          description: The cursor identifying the page to return when paginating.
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/DetailedReturnList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableReturnListRequest'
  /warehouse/return/details:
    get:
      summary: Get Return Details
      operationId: getReturnDetails
      tags:
        - Return Data
      security:
        - api_key: []
      description: |
        Get the details of a specific return based on a return's ID,
        an order name, or an order ID from the commerce provider (e.g. Shopify) depending on the
        query value of the call.

        ### Required API key scope
        - Returns
      parameters:
        - name: return_id
          description: The unique identifier associated with the return.
          example: 37603922
          in: query
          schema:
            type: integer
        - name: order_id
          description: The unique identifier associated with the order.
          example: 2347613440760
          in: query
          schema:
            type: integer
        - name: order_name
          description: The order name from the commerce provider (e.g. Shopify).
          example: '2222'
          in: query
          schema:
            type: string
        - name: currency_type
          description: >
            The currency type of the return.


            If set to `shop`, all currency fields in the response will use the shop's currency.


            If set to `presentment`, all currency fields in the response will use the currency
            presented to the shopper when they made the purchase.
          in: query
          schema:
            type: string
            enum:
              - 'shop'
              - 'presentment'
      responses:
        '200':
          $ref: '#/components/responses/ReturnDetails'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /warehouse/reporting/asn:
    get:
      tags:
        - Return Data
      security:
        - api_key: []
      summary: Advanced Shipping Notice
      operationId: getAdvancedShippingNotice
      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
      parameters:
        - name: from
          example: 2023-08-21
          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-21
        - name: to
          example: 2023-08-22
          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-21
      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.
  /order/link:
    post:
      summary: Create Return Deep Link
      operationId: createReturnDeepLink
      tags:
        - Return Actions
      security:
        - api_key: []
      description: |
        Create a deep link URL.
        Depending on a shop's settings, the `zip` value could be an email, phone number, or postal
        code. All use the key `zip`.

        ### Required API key scope
        - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeeplinkCreationRequest'
      responses:
        '200':
          description: 'Success'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeeplinkCreationResponse'
        '400':
          description: 'Bad Request'
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/BadRequestWithErrorCode'
                  - $ref: '#/components/schemas/OrderNotAvailableResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: 'Unprocessable Entity'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MissingOrderFieldsResponse'
  /order/qr:
    post:
      summary: Create Return Deep Link with QR Code
      operationId: createReturnDeepLinkWithQrCode
      description: |
        Generate a link to a QR code image file that,
        when scanned, will take the user directly to their order in Loop so
        they can initiate a return without requiring them to enter their order information.

        The deep link URL is also returned. If `type` is not included in the request, or is a non-supported format, a
        `png` will be returned.

        ### Required API key scope
        - Orders
      tags:
        - Return Actions
      security:
        - api_key: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QrCreationRequest'
      responses:
        '200':
          description: 'Success'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QrCreationResponse'
        '400':
          description: 'Bad Request'
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/BadRequestWithErrorCode'
                  - $ref: '#/components/schemas/OrderNotAvailableResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: 'Unprocessable Entity'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MissingOrderFieldsResponse'
components:
  responses:
    ProcessReturn:
      description: |
        Success - HTTP `200` with `true` means Loop queued processing (acknowledgement, not completion).
        HTTP `200` with an `errors` body means Loop refused the request before queueing.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/SuccessMessage'
              - $ref: '#/components/schemas/ReturnActionError'
              - $ref: '#/components/schemas/UnprocessableStateReturn'
              - $ref: '#/components/schemas/UnprocessableFlaggedReturn'
    RemoveLineItems:
      description: 'Success'
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/SuccessMessage'
              - $ref: '#/components/schemas/ReturnActionError'
    UnprocessableRemove:
      description: 'Unprocessable'
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/RemoveLineItemValidationError'
              - $ref: '#/components/schemas/RemoveLineItemError'
    FailedToProcess:
      description: Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RemoveLineItemError'
    CancelReturn:
      description: 'Success'
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/SuccessMessage'
              - $ref: '#/components/schemas/ReturnActionError'
    ReturnDetails:
      description: Success
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ReturnDetails'
              - $ref: '#/components/schemas/NoMatchingReturnDetails'
              - $ref: '#/components/schemas/ReturnDetailsMissingParameters'
    FlagReturn:
      description: 'Success'
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/SuccessMessage'
              - $ref: '#/components/schemas/ReturnActionError'
    CloseReturn:
      description: 'Success'
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/SuccessMessage'
              - $ref: '#/components/schemas/ReturnActionError'
    ReturnNotes:
      description: 'Success'
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ReturnNote'
    NoReturnNotes:
      description: 'Unprocessable'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FailureMessage'
    CreateReturnNote:
      description: 'Success'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuccessMessage'
    CreateReturnNoteInvalid:
      description: 'Unprocessable'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InvalidContentForNoteResponse'
    DetailedReturnList:
      description: Success
      content:
        application/json:
          schema:
            oneOf:
              - type: array
                items:
                  $ref: '#/components/schemas/DetailedReturnList'
              - type: object
                description: Returned when the `paginate` query parameter is present.
                properties:
                  returns:
                    type: array
                    items:
                      $ref: '#/components/schemas/DetailedReturnList'
                  nextPageUrl:
                    type: [string, 'null']
                  previousPageUrl:
                    type: [string, 'null']
    UnprocessableReturnListRequest:
      description: 'Unprocessable'
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/InvalidFromDate'
              - $ref: '#/components/schemas/InvalidToDate'
              - $ref: '#/components/schemas/InvalidState'
    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.'
    Unprocessable:
      description: Unprocessable
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                examples:
                  - {}
              errors:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - A request attribute is invalid or improperly formatted.
  schemas:
    SuccessMessage:
      description: The value returned when the return action succeeds.
      type: boolean
      examples:
        - true
    FailureMessage:
      description: The value returned when no notes can be retrieved for the return.
      type: boolean
      examples:
        - false
    ReturnActionError:
      type: object
      description: An error response for a return action, containing a message describing the failure.
      properties:
        errors:
          type: object
          properties:
            message:
              type: string
              examples:
                - 'No return found with this ID.'
    UnprocessableFlaggedReturn:
      type: object
      description: >-
        Returned when a return cannot be processed because processing of flagged
        returns is disabled, or when a generic processing error occurs (the
        catch-all in `process` also returns this code). The return's current state
        is interpolated into the message.
      properties:
        errors:
          type: object
          properties:
            message:
              type: string
              examples:
                - 'Return is open and therefore cannot be processed.'
            code:
              type: string
              examples:
                - 'UNPROCESSABLE_FLAGGED_RETURN'
    UnprocessableStateReturn:
      type: object
      description: The value returned when the return is closed and can't be processed.
      properties:
        errors:
          type: object
          properties:
            message:
              type: string
              examples:
                - 'Return is closed and therefore cannot be processed.'
            code:
              type: string
              examples:
                - 'UNPROCESSABLE_RETURN'
    RemoveReturnNotFound:
      type: object
      description: >-
        Returned with HTTP 403 when no return matches the given ID for the
        authenticated shop. Note that `errors` is an array of objects here.
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                examples:
                  - 'No return found with this ID.'
    RemoveLineItemValidationError:
      type: object
      description: >-
        Standard Laravel validation error returned when `line_item_id` is missing
        or invalid.
      properties:
        message:
          type: string
          examples:
            - 'The line item id field is required.'
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          examples:
            - line_item_id:
                - 'The line item id field is required.'
    RemoveLineItemError:
      type: object
      description: >-
        Error envelope returned by the remove-line-items endpoint for modification
        failures (return not modifiable, item count mismatch, or a processing
        error). The requested `line_item_id` is echoed back under `data`, and the
        `errors.message` varies by failure — count-mismatch messages include a
        ` - Received: … - Qualifying: …` suffix.
      properties:
        data:
          type: object
          properties:
            line_item_id:
              type: [string, 'null']
              examples:
                - '123456789'
        errors:
          type: object
          properties:
            message:
              type: string
              examples:
                - 'Return cannot be modified.'
    ReturnNote:
      type: object
      properties:
        id:
          type: integer
          examples:
            - 1
          description: The unique identifier associated with the return note.
        content:
          type: string
          examples:
            - 'This is a sample note'
          description: The content of the note.
        created_at:
          type: string
          examples:
            - '2023-08-15 13:19:20'
          description: The date and time at which the note was created, in `Y-m-d H:i:s` format.
    CreateReturnNoteRequest:
      type: object
      required:
        - content
      properties:
        content:
          description: The content of the note.
          type: string
          maxLength: 255
          examples:
            - 'This is a new note'
    InvalidContentForNoteResponse:
      type: object
      properties:
        errors:
          type: object
          properties:
            message:
              type: string
              examples:
                - 'Content is required and must be less than 255 characters.'
        data:
          type: object
          properties:
            content:
              type: string
    DeeplinkCreationRequest:
      type: object
      required:
        - name
        - zip
      properties:
        name:
          type: string
          examples:
            - 'Shopify Order Name'
          description: The name of the order in the commerce provider (e.g. Shopify).
        zip:
          type: string
          examples:
            - '43215'
          description: |
            The order detail used to identify the order. Often the customer's shipping ZIP code, but depending on the
            merchant's shop settings, could also be the customer's email or phone number. A phone number matches the
            shipping address phone, or the billing address or customer phone when the order has no shipping address
            (for example, a local pickup order).
        gift:
          type: boolean
          examples:
            - false
          description: |
            Whether or not the return will use Loop's Gift flow. For details, see
            [Gift Returns](https://help.loopreturns.com/en/articles/1911041).
    InvalidFromDate:
      type: object
      properties:
        message:
          type: string
          examples:
            - The `from attribute has an invalid date format.
        errors:
          type: object
          properties:
            from:
              type: array
              items:
                type: string
                examples:
                  - The `from` attribute has an invalid date format.
    InvalidToDate:
      type: object
      properties:
        message:
          type: string
          examples:
            - The `to` attribute has an invalid date format.
        errors:
          type: object
          properties:
            from:
              type: array
              items:
                type: string
                examples:
                  - The `to` attribute has an invalid date format.
    InvalidState:
      type: object
      properties:
        message:
          type: string
          examples:
            - The selected state is invalid.
        errors:
          type: object
          properties:
            from:
              type: array
              items:
                type: string
                examples:
                  - The selected state is invalid.
    DeeplinkCreationResponse:
      type: object
      properties:
        url:
          type: string
          examples:
            - 'https://test-shop.loopreturns.com/#/link/examp1e-uu1d-h3r3'
    QrCreationRequest:
      type: object
      required:
        - name
        - zip
      properties:
        name:
          type: string
          examples:
            - 'Shopify Order Name'
        zip:
          type: string
          examples:
            - '43215'
        gift:
          type: boolean
          examples:
            - false
        'type':
          type: string
          enum:
            - png
            - eps
            - svg
          examples:
            - 'png'
        size:
          type: integer
          examples:
            - 250
    QrCreationResponse:
      type: object
      properties:
        qr:
          type: string
          examples:
            - 'https://api.loopreturns.com/api/v1/qr/i/example-uuid-for-qr-image'
        deeplink_url:
          type: string
          examples:
            - 'https://test-shop.loopreturns.com/#/link/examp1e-uu1d-h3r3'
    BadRequestWithErrorCode:
      type: object
      description: >-
        Bad-request error where `errors` is an array of message strings (for
        example, the order could not be loaded or a deep link could not be
        created).
      properties:
        errors:
          type: array
          items:
            type: string
          examples:
            - ['errorCode1']
    OrderNotAvailableResponse:
      type: object
      description: >-
        Returned with HTTP 400 when the order exists but is not available for
        return (for example, it is blocklisted). Here `errors` is an object with a
        message and an error code.
      properties:
        errors:
          type: object
          properties:
            message:
              type: string
              examples:
                - 'This order is not available for return.'
            code:
              type: string
              examples:
                - 'NOT_AUTHORIZED'
    MissingOrderFieldsResponse:
      type: object
      description: >-
        Returned with HTTP 422 by /order/link and /order/qr when the required
        order-lookup fields (`name` and `zip`) are missing. The submitted lookup
        fields are echoed back under `data`.
      properties:
        errors:
          type: object
          properties:
            message:
              type: string
              examples:
                - 'Missing fields - "name" and "zip" are required.'
        data:
          type: object
          properties:
            name:
              type: [string, 'null']
            zip:
              type: [string, 'null']
            size:
              type: [integer, 'null']
            'type':
              type: [string, 'null']
            gift:
              type: [boolean, 'null']
    DetailedReturnList:
      type: object
      properties:
        id:
          type: string
          examples:
            - '12345678'
          description: The unique identifier associated with the return.
        state:
          type: string
          examples:
            - open
          description: The current state of the return.
        created_at:
          type: string
          format: date-time
          examples:
            - 2023-01-01T22:27:15+00:00
          description: The date and time at which the return was created, using the ISO 8601 date format.
        updated_at:
          type: string
          format: date-time
          examples:
            - 2023-01-01T22:27:18+00:00
          description: The date and time at which the return was last updated, using the ISO 8601 date format.
        edited_at:
          type: string
          format: date-time
          examples:
            - 2023-01-03T22:34:17+00:00
          description: The date and time at which the return was last edited, using the ISO 8601 date format.
        total:
          type: string
          examples:
            - '63.30'
          description: The total cost 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.
        order_id:
          type: string
          examples:
            - '98766312'
          description: The Loop order identifier associated with the return.
        order_name:
          type: string
          examples:
            - '#7382018'
          description: The order name.
        provider_order_id:
          type: string
          examples:
            - '3248923479283'
          description: The order ID from the commerce provider (e.g. Shopify).
        order_number:
          type: string
          examples:
            - '7381018'
          description: The order number.
        provider_order_number:
          type: string
          examples:
            - '7382018'
          description: The order number from the commerce provider (e.g. Shopify).
        customer:
          type: [string, 'null']
          examples:
            - example@example.com
          description: The customer's email address.
        origin_country:
          type: [string, 'null']
          examples:
            - United States
          description: The country of the customer's shipping address.
        origin_country_code:
          type: [string, 'null']
          examples:
            - US
          description: The ISO 3166-1 alpha-2 country code of the customer's shipping address.
        multi_currency:
          examples:
            - false
          description: |
            Whether the order was placed through Shopify Payments in some currency other than the default store
            currency.
        currency:
          type: string
          examples:
            - USD
          description: The currency code of the store's default currency.
        return_product_total:
          type: string
          examples:
            - '156.00'
          description: The gross value of the returning items before discounts and tax.
        return_discount_total:
          type: string
          examples:
            - '0.00'
          description: The total value of the discounts on the returning items.
        return_tax_total:
          type: string
          examples:
            - '8.58'
          description: The total value of the taxes on the returning items.
        return_total:
          type: string
          examples:
            - '164.58'
          description: The net value of the returning items after discounts and tax.
        refund_shipping_total:
          type: string
          examples:
            - '4.00'
          description: >-
            Total original-order shipping reimbursement folded into the refund
            (the sum of each line item's `refund_shipping`).
        refund_shipping_tax_total:
          type: string
          examples:
            - '0.40'
          description: >-
            The tax portion of the reimbursed shipping folded into the refund
            (the sum of each line item's `refund_shipping_tax`).
        return_credit_total:
          type: string
          examples:
            - '101.28'
          description: The value of the returning items credited to the shopper after the refund has been issued.
        exchange_product_total:
          type: string
          examples:
            - '96.00'
          description: The gross value of the exchange before discounts and tax.
        exchange_discount_total:
          type: string
          examples:
            - '0.00'
          description: The total value of discounts on the exchange.
        exchange_tax_total:
          type: string
          examples:
            - '5.28'
          description: The total value of the taxes on the exchange.
        exchange_total:
          type: string
          examples:
            - '101.28'
          description: The net value of the exchanges after discounts and tax.
        exchange_credit_total:
          type: string
          examples:
            - '101.28'
          description: The value of the return credit used by the shopper.
        gift_card:
          type: string
          examples:
            - '0.00'
          description: The value of the gift card issued in the return.
        gift_card_order_name:
          type: [string, 'null']
          examples:
            - Gift Card Name
          description: The name of the gift card order issued in the return.
        gift_card_order_id:
          type: [string, 'null']
          examples:
            - '23141001200513'
          description: The unique identifier of the gift card issued in the return.
        gift_card_presentment:
          $ref: '#/components/schemas/GiftCardPresentment'
        handling_fee:
          type: string
          examples:
            - '0.00'
          description: The handling fee charged by the merchant.
        refund:
          type: string
          examples:
            - '63.30'
          description: The amount refunded in the return.
        upsell:
          type: string
          examples:
            - '0.00'
          description: The upsell amount associated with the return.
        line_items:
          $ref: '#/components/schemas/LineItem'
        presentment:
          $ref: '#/components/schemas/Presentment'
        exchanges:
          $ref: '#/components/schemas/Exchange'
        carrier:
          type: string
          examples:
            - N/A
          description: The carrier associated with the return.
        tracking_number:
          type: string
          examples:
            - N/A
          description: The return's tracking number.
        label_status:
          type: string
          examples:
            - N/A
          description: The status of the return shipping label.
        label_url:
          type: [string, 'null']
          examples:
            - http://example.label.url
          description: The link to the shipping label details.
        label_rate:
          type: [string, 'null']
          description: The shipping rate paid for the return label.
        status_page_url:
          type: string
          examples:
            - https://example.loopreturns.com/#/return/{uuid}
          description: The link to the Loop return tracking status page associated with the return.
        label_updated_at:
          type: string
          format: date-time
          examples:
            - N/A
          description: The date and time at which the label was last updated, using the ISO 8601 date format.
        destination_id:
          type: [string, 'null']
          examples:
            - '67896541368765'
          description: The unique identifier associated with the shipping destination of the return.
        return_method:
          $ref: '#/components/schemas/ReturnMethod'
        package_reference:
          type: [string, 'null']
          description: The data used to look up package data in WMS software.
        type:
          $ref: '#/components/schemas/Type'
          description: The type of return submission.
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
    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-21 14:09:17
          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-01 14:00:41
          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-21 14:06:32
          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-21 14:05:56
          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-01 10:00:00
          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.
    ReturnDetails:
      type: object
      properties:
        id:
          type: integer
          examples:
            - 37603915
          description: The unique identifier associated with the return.
        created_at:
          type: string
          format: date-time
          examples:
            - '2023-08-22 14:08:31'
          description: The date and time at which the return was created, using the ISO 8601 date format.
        updated_at:
          type: string
          format: date-time
          examples:
            - '2023-08-22 15:05:15'
          description: The date and time at which the return was last updated, using the ISO 8601 date format.
        edited_at:
          type: string
          format: date-time
          examples:
            - '2023-08-22 15:05:15'
          description: The date and time at which the return was last edited, using the ISO 8601 date format.
        order_id:
          examples:
            - 3838173
          description: The Loop order identifier associated with the return.
        order_name:
          examples:
            - '1138'
          description: The order name.
        order_number:
          examples:
            - 138
          description: The order number.
        provider_order_number:
          type: integer
          examples:
            - 1138
          description: The order number from the commerce provider (e.g. Shopify).
        provider_order_id:
          type: integer
          examples:
            - 5444175757553
          description: The order ID from the commerce provider (e.g. Shopify).
        total:
          examples:
            - '192.42'
          description: The total cost of the return.
        customer:
          type: [string, 'null']
          examples:
            - email@loopreturns.com
          description: The customer's email address.
        multi_currency:
          examples:
            - false
          description: |
            Whether the order was placed through Shopify Payments in
            some currency other than the default store currency.
        state:
          examples:
            - cancelled
          description: The status of the return.
        currency:
          examples:
            - USD
          description: The currency code of the store's default currency.
        exchange:
          examples:
            - '0.00'
          description: The value of the exchange.
        exchange_order_name:
          type: array
          items:
            type: string
          examples:
            - ['EXC-4736272-1', 'EXC-4736272-2']
          description: |
            The names of the exchange orders associated with the return.
        exchange_order_id:
          type: array
          items:
            type: integer
            format: int64
          examples:
            - [2342352463453, 2342352463454]
          description: |
            The unique identifiers associated with the exchange orders.
        gift_card_order_name:
          examples:
            - Gift Card Name
          description: The name of the gift card order.
        gift_card_order_id:
          examples:
            - 987651987684
          description: The unique identifier associated with the gift card order.
        gift_card:
          examples:
            - '0.00'
          description: The gift card amount.
        gift_card_presentment:
          $ref: '#/components/schemas/GiftCardPresentment'
        refund:
          examples:
            - '192.42'
          description: The refund amount in the presentment currency.
        refunds:
          $ref: '#/components/schemas/Refunds'
        return_product_total:
          type: string
          examples:
            - '156.00'
          description: The gross value of the returning items before discounts and tax.
        return_discount_total:
          type: string
          examples:
            - '0.00'
          description: The total value of the discounts on the returning items.
        return_tax_total:
          type: string
          examples:
            - '8.58'
          description: The total value of the taxes on the returning items.
        return_total:
          type: string
          examples:
            - '164.58'
          description: The net value of the returning items after discounts and tax.
        refund_shipping_total:
          type: string
          examples:
            - '4.00'
          description: >-
            Total original-order shipping reimbursement folded into the refund
            (the sum of each line item's `refund_shipping`).
        refund_shipping_tax_total:
          type: string
          examples:
            - '0.40'
          description: >-
            The tax portion of the reimbursed shipping folded into the refund
            (the sum of each line item's `refund_shipping_tax`).
        return_credit_total:
          type: string
          examples:
            - '101.28'
          description: The value of the returning items credited to the shopper after the refund has been issued.
        handling_fee:
          examples:
            - '0.00'
          description: The handling fee charged by the merchant.
        exchange_product_total:
          type: string
          examples:
            - '96.00'
          description: The gross value of the exchange before discounts and tax.
        exchange_discount_total:
          type: string
          examples:
            - '0.00'
          description: The total value of discounts on the exchange.
        exchange_tax_total:
          type: string
          examples:
            - '5.28'
          description: The total value of the taxes on the exchange.
        exchange_total:
          type: string
          examples:
            - '101.28'
          description: The net value of the exchanges after discounts and tax.
        exchange_credit_total:
          type: string
          examples:
            - '101.28'
          description: The value of the return credit used by the shopper.
        upsell:
          examples:
            - '0.00'
          description: The upsell amount associated with the return.
        line_items:
          $ref: '#/components/schemas/ReturnDetailsLineItem'
        presentment:
          $ref: '#/components/schemas/Presentment'
        customer_email:
          type: string
          examples:
            - email@loopreturns.com
          description: The customer's email address.
        carrier:
          type: string
          examples:
            - USPS
          description: The carrier associated with the return.
        label_status:
          type: string
          examples:
            - out_for_delivery
          description: The delivery status of the return.
        label_updated_at:
          type: string
          format: date-time
          examples:
            - 2023-08-21 14:09:17
          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.
        outcome:
          $ref: '#/components/schemas/ReturnOutcome'
          description: The outcome of the return as limited by the merchant and as selected by the customer.
        tracking_number:
          type: string
          examples:
            - '9999999999999999999999'
          description: The tracking number associated with the return.
        destination_id:
          type: string
          examples:
            - '17'
          description: The unique identifier associated with the return's destination.
        status_page_url:
          type: string
          examples:
            - https://sample-store.loopreturns.com/#/return/beee8df-b948-4feb-8e23-8cfd2d1e3565
          description: The link to the return's status page.
        return_method:
          type: string
          examples:
            - happy-returns
          description: The return method.
        package_reference:
          type: string
          examples:
            - '9999999999999999999999'
          description: The package reference of the return.
        shopify_refund_object:
          type: array
          items:
            $ref: '#/components/schemas/ShopifyRefundObject'
        exchanges:
          type: array
          examples:
            - []
        customer_first_name:
          examples:
            - Alex
          type: string
        customer_last_name:
          examples:
            - Doe
          type: string
        type:
          $ref: '#/components/schemas/Type'
          description: The type of return submission.
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
    ReturnDetailsLineItem:
      type: array
      items:
        type: object
        properties:
          line_item_id:
            type: number
            examples:
              - 293482039
          provider_line_item_id:
            type: number
            examples:
              - 23984238720
          provider_line_item_external_id:
            type: [string, 'null']
            description: >
              Always present on each `line_items` entry (never omitted). The
              merchant-supplied external identifier for the order line item, as set
              via the Commerce Data Orders API (`line_items[].external_id`). Resolved from
              the Commerce Data order line item linked by `provider_line_item_id`. `null`
              for non-Commerce Data shops (including Shopify), when the line item has no
              external identifier, when no Commerce Data line item matches, or when the
              Commerce Data lookup cannot be completed (the request still returns HTTP 200).
              When a single Commerce Data order line with quantity greater than one is split
              into multiple returning units, each unit shares this value but has a distinct
              `line_item_id`.
            examples:
              - merchant-line-item-abc-123
              - null
          product_id:
            type: number
            examples:
              - 29871298313
          variant_id:
            type: number
            examples:
              - 23498287203948
          sku:
            type: string
            examples:
              - 2039473-Y
          line_item_title:
            type: string
            examples:
              - Black Striped Shirt
          variant_title:
            type: string
            examples:
              - Small / Navy
          title:
            type: string
            examples:
              - Black Striped Shirt
          image:
            type: string
            examples:
              - https://cdn.shopify.com/s/files/1/0000/0000/0000/products/Black_Striped_Shirt.jpg
          price:
            type: string
            examples:
              - '78.00'
          discount:
            type: string
            examples:
              - '0.00'
          tax:
            type: string
            examples:
              - '4.29'
          refund:
            type: string
            examples:
              - '31.65'
          returned_at:
            type: string
            format: date-time
            examples:
              - 2023-01-01 22:27:16
            description: The date and time at which the item was returned, using the ISO 8601 date format.
          exchange_variant:
            type: [string, 'null']
          barcode:
            type: string
            examples:
              - ''
          provider_restock_location_id:
            type: [string, 'null']
          consolidation_tracking:
            type: [string, 'null']
            examples:
              - 'MS6681181'
            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.
          consolidation_destination_id:
            type: [string, 'null']
            examples:
              - '357'
            description: |
              If a line item is part of a consolidated shipment of many return items,
              this value holds the destination id for the consolidated shipment that
              contains this item such as the Happy Returns Outbound Shipment
              destination address id.
          reason:
            type: string
            examples:
              - Item was too small
          parent_reason:
            type: string
            examples:
              - Item didn't fit
          refund_tax:
            type: string
            examples:
              - '4.29'
          refund_item:
            type: string
            examples:
              - '27.36'
          refund_shipping:
            type: string
            examples:
              - '4.00'
            description: >-
              This line's share of the original-order shipping reimbursement
              folded into `refund`.
          refund_excluding_shipping:
            type: string
            examples:
              - '27.65'
            description: >-
              This line's `refund` with shipping removed
              (`refund` minus `refund_shipping`).
          refund_shipping_tax:
            type: string
            examples:
              - '0.40'
            description: The tax portion of `refund_shipping`.
          refund_excluding_shipping_tax:
            type: string
            examples:
              - '4.29'
            description: >-
              The tax on the items excluding shipping. The existing `refund_tax`
              already excludes shipping tax, so this value equals `refund_tax`;
              the corrected total refund tax is `refund_tax` plus
              `refund_shipping_tax`.
          outcome:
            type: string
            enum:
              - reject
              - donate
              - review
              - default
              - keep
            examples:
              - default
          condition:
            $ref: '#/components/schemas/Condition'
          disposition:
            $ref: '#/components/schemas/Disposition'
          customer_uploads:
            type: object
            description: >-
              Images and videos uploaded by the customer for this line item during
              the return process. Omitted if the line item has no customer uploads.
              `images` and `media` are independent arrays backed by separate upload
              systems, so a given upload appears in exactly one of them, never both:
              photos from the legacy upload flow are listed in `images`, while all
              videos and photos from the newer upload flow are listed in `media`
              (`type: video` or `type: image`). Read both arrays to get the full set
              of customer photos, and `media` for videos, to avoid double-fetching
              or missing uploads.
            properties:
              images:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      examples:
                        - 4837291
                    source:
                      type: string
                      examples:
                        - customer
                      description: The source of the upload. Always `customer` for this field.
                    url:
                      type: string
                      examples:
                        - https://loop-uploads.s3.amazonaws.com/image_uploads/4837291-item-photo.jpg
                      description: A temporary, signed URL to the uploaded image, valid for 7 days.
                    created_at:
                      type: [string, 'null']
                      format: date-time
                      examples:
                        - '2023-08-22 14:08:31'
                      description: The date and time at which the image was uploaded, using the ISO 8601 date format.
              media:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      examples:
                        - 128374
                    type:
                      type: string
                      enum:
                        - image
                        - video
                      examples:
                        - video
                    url:
                      type: string
                      examples:
                        - https://loop-media-uploads.s3.amazonaws.com/videos/128374/item-video.mp4
                      description: A temporary, signed URL to the uploaded media, valid for 7 days.
                    created_at:
                      type: [string, 'null']
                      format: date-time
                      examples:
                        - '2023-08-22 14:08:31'
                      description: The date and time at which the media was uploaded, using the ISO 8601 date format.
    NoMatchingReturnDetails:
      type: object
      properties:
        error:
          type: object
          properties:
            data:
              type: object
            message:
              type: string
              examples:
                - 'No return found with this ID.'
    ReturnDetailsMissingParameters:
      type: object
      properties:
        error:
          type: object
          properties:
            data:
              type: object
            message:
              type: string
              examples:
                - 'Missing parameter. Please pass in: return_id, order_name, or order_id.'
    ReturnState:
      type: string
      enum:
        - open
        - closed
        - expired
        - cancelled
        - review
    ReturnOutcome:
      type: string
      enum:
        - exchange
        - upsell
        - refund
        - credit
        - exchange+refund
        - exchange+credit
    Refunds:
      type: array
      items:
        type: object
        properties:
          gateway:
            type: string
            examples:
              - 'Stripe'
          amount:
            type: string
            examples:
              - '78.00'
          currency:
            type: string
            examples:
              - 'USD'
          provider_refund_id:
            type: [string, 'null']
            examples:
              - '12345'
          provider:
            type: string
            examples:
              - 'reshop'
    GiftCardPresentment:
      type: object
      description: >-
        The gift card credit issued in the return, in the currency the gift card was issued in
        (the order's presentment currency when available).
      properties:
        value:
          type: string
          examples:
            - '0.00'
          description: The total value of the gift card credit issued in the return.
        currency:
          type: [string, 'null']
          examples:
            - CAD
          description: The ISO 4217 currency code of `value`.
    Presentment:
      type: object
      description: >-
        Return totals in the order's presentment (customer) currency, sourced from the stored,
        provider-authoritative amounts rather than converted from the shop currency. Use this
        block to reconcile multi-currency returns to the cent; the amounts satisfy
        `refund + return_credit_total + handling_fee == return_total + return_shipping_total +
        credit_shipping_total`.
      properties:
        currency:
          type: [string, 'null']
          examples:
            - CAD
          description: The ISO 4217 code of the order's presentment (customer) currency.
        return_product_total:
          type: string
          examples:
            - '156.00'
          description: The gross value of the returning items before discounts and tax.
        return_discount_total:
          type: string
          examples:
            - '0.00'
          description: The total value of the discounts on the returning items.
        return_tax_total:
          type: string
          examples:
            - '8.58'
          description: The total value of the taxes on the returning items.
        return_total:
          type: string
          examples:
            - '164.58'
          description: >-
            The net value of the returning items after discounts and tax
            (`return_product_total - return_discount_total + return_tax_total`).
            Items only — excludes reimbursed shipping.
        return_shipping_total:
          type: string
          examples:
            - '4.00'
          description: Reimbursed original-order shipping folded into the refund, tax inclusive.
        return_shipping_tax_total:
          type: string
          examples:
            - '0.40'
          description: >-
            The tax portion already included in `return_shipping_total`. Informational —
            not an additional amount.
        credit_shipping_total:
          type: string
          examples:
            - '0.00'
          description: >-
            Reimbursed original-order shipping folded into the store credit instead of the
            refund.
        handling_fee:
          type: string
          examples:
            - '0.00'
          description: The handling fee withheld by the merchant (`0.00` when waived).
        return_credit_total:
          type: string
          examples:
            - '0.00'
          description: The store credit issued to the shopper. Equal to `gift_card`.
        gift_card:
          type: string
          examples:
            - '0.00'
          description: The value of the gift card issued in the return. Equal to `return_credit_total`.
        refund:
          type: string
          examples:
            - '168.58'
          description: The total amount refunded to the original payment tender(s).
        refund_breakdown:
          type: array
          description: >-
            The per-tender split of `refund` — one entry per original payment tender (for
            example a gift card tender alongside a card).
          items:
            type: object
            properties:
              gateway:
                type: string
                examples:
                  - shopify_payments
                description: >-
                  The payment gateway of the original tender (for example `shopify_payments`
                  or `gift_card`).
              provider:
                type: string
                examples:
                  - shopify
                description: The commerce provider that processed the refund.
              amount:
                type: string
                examples:
                  - '168.58'
                description: The amount refunded to this tender, in the presentment currency.
              currency:
                type: string
                examples:
                  - CAD
                description: The ISO 4217 currency code of `amount` (the presentment currency).
        line_items:
          type: array
          description: Presentment amounts for each returning line item.
          items:
            type: object
            properties:
              line_item_id:
                type: string
                examples:
                  - '59989689'
                description: >-
                  The unique identifier of the returning line item (matches the top-level
                  `line_items` entries).
              price:
                type: string
                examples:
                  - '156.00'
                description: The price of the line item before discounts and tax.
              discount:
                type: string
                examples:
                  - '0.00'
                description: The discount on the line item.
              tax:
                type: string
                examples:
                  - '8.58'
                description: The tax on the line item.
    LineItem:
      type: array
      items:
        type: object
        properties:
          line_item_id:
            type: string
            examples:
              - '293482039'
            description: The unique identifier associated with the line item.
          provider_line_item_id:
            type: string
            examples:
              - '23984238720'
            description: The identifier from the commerce provider (e.g. Shopify) associated with the line item.
          provider_line_item_external_id:
            type: [string, 'null']
            description: >
              Always present on each `line_items` entry (never omitted). The
              merchant-supplied external identifier for the order line item, as set
              via the Commerce Data Orders API (`line_items[].external_id`). Resolved from
              the Commerce Data order line item linked by `provider_line_item_id`. `null`
              for non-Commerce Data shops (including Shopify), when the line item has no
              external identifier, when no Commerce Data line item matches, or when the
              Commerce Data lookup cannot be completed (the request still returns HTTP 200).
              When a single Commerce Data order line with quantity greater than one is split
              into multiple returning units, each unit shares this value but has a distinct
              `line_item_id`.
            examples:
              - merchant-line-item-abc-123
              - null
          product_id:
            type: string
            examples:
              - '29871298310292'
            description: The unique identifier associated with the product.
          variant_id:
            type: string
            examples:
              - '23498287203948'
            description: The unique identifier associated with the product variant.
          sku:
            type: string
            examples:
              - 2039473-Y
            description: The SKU associated with the product.
          title:
            type: string
            examples:
              - Black Striped Shirt
            description: The product's name.
          price:
            type: string
            examples:
              - '78.00'
            description: The product's price.
          discount:
            type: string
            examples:
              - '0.00'
            description: The discount amount associated with the line item.
          tax:
            type: string
            examples:
              - '4.29'
            description: The tax amount associated with the line item.
          refund:
            type: string
            examples:
              - '31.65'
            description: The refund amount associated with the line item.
          refund_item:
            type: string
            examples:
              - '27.36'
            description: The refund amount minus the tax amount.
          refund_tax:
            type: string
            examples:
              - '4.29'
            description: Equal to the refund.
          refund_shipping:
            type: string
            examples:
              - '4.00'
            description: >-
              This line's share of the original-order shipping reimbursement
              folded into `refund`.
          refund_excluding_shipping:
            type: string
            examples:
              - '27.65'
            description: >-
              This line's `refund` with shipping removed
              (`refund` minus `refund_shipping`).
          refund_shipping_tax:
            type: string
            examples:
              - '0.40'
            description: The tax portion of `refund_shipping`.
          refund_excluding_shipping_tax:
            type: string
            examples:
              - '4.29'
            description: >-
              The tax on the items excluding shipping. The existing `refund_tax`
              already excludes shipping tax, so this value equals `refund_tax`;
              the corrected total refund tax is `refund_tax` plus
              `refund_shipping_tax`.
          returned_at:
            type: string
            format: date-time
            examples:
              - 2023-01-01 22:27:16
            description: The date and time at which the item was returned, using the ISO 8601 date format.
          exchange_variant:
            type: string
            examples:
              - ''
            description: The product variant selected by the customer for exchange (if applicable).
          return_reason:
            type: string
            examples:
              - I like another style more
            description: The specific reason for return given by the customer.
          parent_return_reason:
            type: string
            examples:
              - Didn't like it
            description: The general return reason category given by the customer.
          return_comment:
            type: string
            examples:
              - N/A
            description: The optional comment left by the customer when returning the product.
          barcode:
            type: string
            examples:
              - '290832428347'
            description: The barcode of the product.
          outcome:
            type: string
            enum:
              - reject
              - donate
              - review
              - default
              - keep
            examples:
              - default
            description: The return outcome, as permitted by the merchant's return policy.
          provider_restock_location_id:
            type: [string, 'null']
            description: The restock location for the return.
          consolidation_tracking:
            type: string
            examples:
              - 'MS6681181'
            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.
          consolidation_destination_id:
            type: [string, 'null']
            examples:
              - '357'
            description: |
              If a line item is part of a consolidated shipment of many return items,
              this value holds the destination id for the consolidated shipment that
              contains this item such as the Happy Returns Outbound Shipment
              destination address id.
          condition:
            $ref: '#/components/schemas/Condition'
          disposition:
            $ref: '#/components/schemas/Disposition'
    Exchange:
      type: array
      items:
        type: object
        properties:
          exchange_id:
            type: string
            examples:
              - '23423423'
            description: The unique identifier associated with the exchange.
          exchange_order_id:
            type: integer
            format: int64
            examples:
              - 2342352463453
            description: The unique identifier associated with the exchange order.
          exchange_order_name:
            type: string
            examples:
              - EXC-4736272-1
            description: The name of the exchange order.
          product_id:
            type: string
            examples:
              - '2342342342344'
            description: The unique identifier associated with the product.
          variant_id:
            type: string
            examples:
              - '49483943473899'
            description: The unique identifier associated with the product variant.
          sku:
            type: string
            examples:
              - 2833928-Y
            description: The SKU associated with the product.
          type:
            type: string
            examples:
              - storefront
            description: The order type.
          title:
            type: string
            examples:
              - Grey Striped Shirt
            description: The product's name.
          price:
            type: string
            examples:
              - '48.00'
            description: The product's price.
          discount:
            type: string
            examples:
              - '0.00'
            description: The discount amount associated with the exchange.
          tax:
            type: string
            examples:
              - '2.64'
            description: The tax amount associated with the line item.
          total:
            type: string
            examples:
              - '50.64'
            description: The sum of the product's price and any tax, minus any discount applied.
          out_of_stock:
            type: boolean
            examples:
              - false
            description: Whether the product is in or out of stock.
          out_of_stock_resolution:
            type: [string, 'null']
          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.
    ReturnMethod:
      type: object
      properties:
        provider:
          type: string
          examples:
            - happy-returns
          description: The provider behind the return.
        method_type:
          type: string
          examples:
            - drop-off
          description: The method in which the return was physically initiated by the customer.
        address:
          $ref: '#/components/schemas/Address'
        state:
          type: string
          enum:
            - new
            - canceled
            - pre_transit
            - in_transit
            - out_for_delivery
            - delivered
            - needs_scheduled
            - skipped
            - pickup_failed
        rma_id:
          type: string
          examples:
            - HR12345
        qr_code_url:
          type: string
          examples:
            - https://partner.happyreturns.com/barcode/qr?code=HR12345
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'
        scheduled_at:
          type: string
          format: date-time
        scannable_id:
          type: [string, 'null']
          description: The data used to scan and lookup return_method data in WMS software
    Address:
      type: object
      properties:
        id:
          type: integer
          format: int32
          examples:
            - 23432434
        hash:
          type: string
          examples:
            - dd93hf99d83hdops9d8fhh38fhd03hh3
        created_at:
          type: string
          format: date-time
          examples:
            - 2021-10-01 03:30:15
        updated_at:
          type: string
          format: date-time
          examples:
            - 2021-10-01 03:30:15
        name:
          type: string
          examples:
            - Staples
        company:
          type: [string, 'null']
          examples:
            - Example Company
        address1:
          type: string
          examples:
            - 1747 Olentangy River Rd
        address2:
          type: string
          examples:
            - ''
        city:
          type: string
          examples:
            - Columbus
        state:
          type: string
          examples:
            - OH
        zip:
          type: string
          examples:
            - '43212'
        country:
          type: string
          examples:
            - United States of America
        country_code:
          type: string
          examples:
            - US
        phone:
          type: string
          examples:
            - ''
        latitude:
          type: number
          examples:
            - 39.995329
        longitude:
          type: number
          examples:
            - -83.026838
    Condition:
      type: [object, 'null']
      properties:
        description:
          type: string
          examples:
            - 'Grade A: No refurbishment needed'
        condition_category:
          type: [string, 'null']
          enum:
            - grade_a
            - grade_b
            - grade_c
            - grade_d
            - incorrect_item
            - missing
            - junk
          examples:
            - grade_c
        return_processor:
          type: [string, 'null']
          examples:
            - 'warehouse-operator@example.com'
        note:
          type: [string, 'null']
          examples:
            - "This item is missing the original packaging. \
              Light refurbishment required. Scuff marks on the back of the item."
        inspected_at:
          type: string
          format: date-time
          examples:
            - '2023-07-19T15:11:32+00:00'
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
    Disposition:
      type: [object, 'null']
      properties:
        disposition_outcome:
          type: string
          enum:
            - back_to_stock
            - resale_hold
            - recycle
            - donate
            - missing
        return_processor:
          type: [string, 'null']
          examples:
            - 'warehouse-operator@example.com'
        note:
          type: [string, 'null']
          examples:
            - 'This item will be returned to stock after bagging and tagging'
        inspected_at:
          type: string
          format: date-time
          examples:
            - '2023-07-19T15:11:32+00:00'
    Image:
      type: string
      format: uri
      examples:
        - 'https://example.com/image.jpg'
    UpdatedAt:
      type: object
      properties:
        date:
          type: string
        timezone_type:
          type: integer
          format: int32
        timezone:
          type: string
    Type:
      type: string
      enum:
        - standard
        - warranty
    Label:
      type: object
      properties:
        status:
          type: string
          examples:
            - N/A
          description: The status of the return shipping label.
        updated_at:
          type: string
          format: date-time
          examples:
            - 2023-01-01T22:27:18+00:00
          description: The date and time at which the label was last updated, using the ISO 8601 date format.
        url:
          type: string
          format: url
          examples:
            - http://example.label.url
          description: The link to the shipping label details.
        rate:
          type: [integer, 'null']
          description: The shipping rate paid for the return label.
        carrier:
          type: string
          examples:
            - USPS
          description: The carrier associated with the return.
        tracking_number:
          type: string
          examples:
            - '9999999999999999999999'
          description: The tracking number associated with the return.
        line_items:
          type: array
          items:
            type: integer
          description: A list of line item ids associated with the label.
          examples:
            - [1001, 1002]
    ShopifyRefundObject:
      type: object
      properties:
        id:
          type: integer
          examples:
            - 1
          description: The unique identifier associated with the refund, assigned by Loop.
        return_id:
          type: integer
          examples:
            - 123456789
          description: The unique identifier associated with the return, assigned by Loop.
        provider_refund_id:
          type: integer
          examples:
            - 987654321
          description: >-
            The unique identifier associated with the refund, assigned by the commerce provider (e.g. Shopify).
        provider_created_at:
          type: string
          format: date-time
          examples:
            - 2023-01-01T20:18:04+00:00
          description: >-
            The date and time at which the refund was created in the commerce provider (e.g. Shopify), using the
            ISO 8601 date format.
        created_at:
          type: string
          format: date-time
          examples:
            - 2023-01-01T22:27:18+00:00
          description: The date and time at which the refund was created in Loop, using the ISO 8601 date format.
        updated_at:
          type: string
          format: date-time
          examples:
            - 2023-01-01T22:27:18+00:00
          description: The date and time at which the refund was last updated in Loop, using the ISO 8601 date format.
  securitySchemes:
    api_key:
      type: 'apiKey'
      name: 'X-Authorization'
      in: 'header'