openapi: 3.1.0
info:
  title: Loop Returns - Returns API
  version: v1
  description: API used for performing operations on returns, including processing, cancelling, flagging, closing, managing notes, listing returns, and creating deep links.
servers:
  - url: https://api.loopreturns.com/api/v1
tags:
  - name: Return Actions
  - name: Return Data
paths:
  /warehouse/return/{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. This endpoint queues the
        return for processing asynchronously.
      tags:
        - Return Actions
      security:
        - api_key: []
      parameters:
        - in: path
          name: return_id
          schema:
            type: integer
          required: true
          description: The unique identifier associated with the return.
      responses:
        '200':
          description: Success - return queued for processing.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SuccessMessage'
                  - $ref: '#/components/schemas/UnprocessableCancelledReturn'
                  - $ref: '#/components/schemas/UnprocessableStateReturn'
                  - $ref: '#/components/schemas/UnprocessableInReviewReturn'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /warehouse/return/{return_id}/remove:
    post:
      summary: Remove Line Items
      operationId: removeLineItems
      description: Remove line items from a return and process the return. Only line items tied to a refund or store credit outcome allow programmatic removal.
      tags:
        - Return Actions
      security:
        - api_key: []
      parameters:
        - in: path
          name: return_id
          schema:
            type: integer
          required: true
          description: The unique identifier associated with the return.
        - in: query
          name: line_item_id
          description: The ID of the line item to remove. Optionally include more than one using comma separated values.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Unprocessable
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/LineItemRequiredResponse'
                  - $ref: '#/components/schemas/ReturnCannotBeModifiedResponse'
                  - $ref: '#/components/schemas/NoLineItemsToRemoveResponse'
                  - $ref: '#/components/schemas/NotAllLineItemsQualifyForRemovalResponse'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedToProcess'
  /warehouse/return/{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.
      tags:
        - Return Actions
      security:
        - api_key: []
      parameters:
        - in: path
          name: return_id
          schema:
            type: integer
          required: true
          description: The unique identifier associated with the return.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SuccessMessage'
                  - $ref: '#/components/schemas/UnprocessableStateReturn'
                  - $ref: '#/components/schemas/ExpiredReturnCannotBeCancelled'
                  - $ref: '#/components/schemas/FlaggedReturnCannotBeCancelled'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /warehouse/return/{return_id}/flag:
    post:
      summary: Flag Return
      operationId: flagReturn
      description: Flag a return in Loop for review. This will prevent automated processing and require a human to review the return in the merchant admin.
      tags:
        - Return Actions
      security:
        - api_key: []
      parameters:
        - in: path
          name: return_id
          schema:
            type: integer
          required: true
          description: The unique identifier associated with the return.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SuccessMessage'
                  - $ref: '#/components/schemas/UnprocessableStateReturn'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /warehouse/return/{return_id}/close:
    post:
      summary: Close Return
      operationId: closeReturn
      description: Close a return. Closing will not fulfill outcomes such as exchanges or gift cards, and items are not able to be used in a new return.
      tags:
        - Return Actions
      security:
        - api_key: []
      parameters:
        - in: path
          name: return_id
          schema:
            type: integer
          required: true
          description: The unique identifier associated with the return.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SuccessMessage'
                  - $ref: '#/components/schemas/UnprocessableStateReturn'
                  - $ref: '#/components/schemas/UnprocessableCancelledReturn'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /warehouse/return/{return_id}/notes:
    get:
      summary: Get Return Notes
      operationId: getReturnNotes
      description: Get notes on a specific return using the return's ID.
      tags:
        - Return Actions
      security:
        - api_key: []
      parameters:
        - in: path
          name: return_id
          schema:
            type: integer
          required: true
          description: The unique identifier associated with the return.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  notes:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReturnNote'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: No notes found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailureMessage'
  /warehouse/return/{return_id}/note:
    post:
      summary: Create Return Note
      operationId: createReturnNote
      description: Post a new note to a return.
      tags:
        - Return Actions
      security:
        - api_key: []
      parameters:
        - in: path
          name: return_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':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Unprocessable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidContentForNoteResponse'
  /warehouse/return/list:
    get:
      summary: Detailed Returns List
      operationId: getDetailedReturnsList
      description: Pull a detailed list of returns created within a given timeframe. Supports pagination. Maximum date range is 120 days.
      tags:
        - Return Data
      security:
        - api_key: []
      parameters:
        - name: from
          in: query
          description: The start date and time for the returns list.
          schema:
            type: string
            examples:
              - 2022-01-01T00:00:00.000Z
        - name: to
          in: query
          description: The end date and time for the returns list.
          schema:
            type: string
            examples:
              - 2022-03-31T23:59:59.000Z
        - name: filter
          in: query
          description: The date field used to filter results.
          schema:
            type: string
            enum:
              - created_at
              - updated_at
            default: created_at
        - name: state
          in: query
          description: Filter by return state.
          schema:
            type: string
            enum:
              - open
              - closed
              - cancelled
              - expired
              - review
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DetailedReturnList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Unprocessable
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/InvalidFromDate'
                  - $ref: '#/components/schemas/InvalidToDate'
                  - $ref: '#/components/schemas/InvalidState'
  /warehouse/return/details:
    get:
      summary: Get Return Details
      operationId: getReturnDetails
      description: Get the details of a specific return based on return ID, order name, or Shopify order ID.
      tags:
        - Return Data
      security:
        - api_key: []
      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 Shopify order name.
          example: '2222'
          in: query
          schema:
            type: string
        - name: currency_type
          description: The currency type of the return (shop or presentment).
          in: query
          schema:
            type: string
            enum:
              - shop
              - presentment
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnDetails'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /warehouse/reporting/asn:
    get:
      summary: Advanced Shipping Notice
      operationId: getAdvancedShippingNotice
      description: Pull all packages by tracking statuses/timeframe. Returns an array of objects containing order and return information.
      tags:
        - Return Data
      security:
        - api_key: []
      parameters:
        - name: from
          in: query
          schema:
            type: string
            format: date
            examples:
              - 2023-08-21T00:00:00.000Z
        - name: to
          in: query
          schema:
            type: string
            format: date
            examples:
              - 2023-08-22T00:00:00.000Z
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AsnReport'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /order/link:
    post:
      summary: Create Return Deep Link
      operationId: createReturnDeepLink
      description: Create a deep link URL for a customer to initiate a return. The zip value could be an email, phone number, or postal code depending on shop settings.
      tags:
        - Return Actions
      security:
        - api_key: []
      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:
                $ref: '#/components/schemas/BadRequestWithErrorCode'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /order/qr:
    post:
      summary: Create Return Deep Link with QR Code
      operationId: createReturnDeepLinkWithQrCode
      description: Generate a link to a QR code image that, when scanned, takes the user directly to their order in Loop to initiate a return.
      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:
                $ref: '#/components/schemas/BadRequestWithErrorCode'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    examples:
                      - '401'
                  http_code:
                    type: string
                    examples:
                      - GEN-UNAUTHORIZED
                  message:
                    type: string
                    examples:
                      - Unauthorized.
  schemas:
    SuccessMessage:
      description: Value returned when the operation succeeds.
      type: string
      examples:
        - 'true'
    FailureMessage:
      description: Value returned when the operation fails.
      type: string
      examples:
        - 'false'
    UnprocessableCancelledReturn:
      type: object
      properties:
        message:
          type: string
          examples:
            - Return is cancelled and therefore cannot be processed.
    UnprocessableStateReturn:
      type: object
      properties:
        errors:
          type: object
          properties:
            message:
              type: string
              examples:
                - Return is closed and therefore cannot be processed.
            code:
              type: string
              examples:
                - UNPROCESSABLE_RETURN
    UnprocessableInReviewReturn:
      type: object
      properties:
        message:
          type: string
          examples:
            - Return is review and therefore cannot be processed.
    ExpiredReturnCannotBeCancelled:
      type: object
      properties:
        content:
          type: string
          examples:
            - Return is expired and cannot be processed.
    FlaggedReturnCannotBeCancelled:
      type: object
      properties:
        content:
          type: string
          examples:
            - Return is flagged and cannot be processed.
    LineItemRequiredResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              examples:
                - The line item id field is required.
    ReturnCannotBeModifiedResponse:
      type: object
      properties:
        message:
          type: string
          examples:
            - Return cannot be modified.
    NoLineItemsToRemoveResponse:
      type: object
      properties:
        message:
          type: string
          examples:
            - There are no line items that qualify for removal
    NotAllLineItemsQualifyForRemovalResponse:
      type: object
      properties:
        message:
          type: string
          examples:
            - Not all line items qualify for removal
    FailedToProcess:
      type: object
      properties:
        message:
          type: string
          examples:
            - An error was encountered during processing.
    ReturnNote:
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier associated with the return note.
        content:
          type: string
          description: The content of the note.
        created_at:
          type: string
          format: date-time
          description: The date and time at which the note was created.
    CreateReturnNoteRequest:
      type: object
      required:
        - content
      properties:
        content:
          description: The content of the note.
          type: string
          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.
    DeeplinkCreationRequest:
      type: object
      required:
        - name
        - zip
      properties:
        name:
          type: string
          description: The name of the order in Shopify.
          examples:
            - Shopify Order Name
        zip:
          type: string
          description: The order detail used to identify the order (ZIP code, email, or phone number).
          examples:
            - '43215'
        gift:
          type: boolean
          description: Whether the return will use Loop's Gift flow.
          examples:
            - false
    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
      properties:
        errors:
          type: array
          items:
            type: string
    InvalidFromDate:
      type: object
      properties:
        message:
          type: string
        errors:
          type: object
    InvalidToDate:
      type: object
      properties:
        message:
          type: string
        errors:
          type: object
    InvalidState:
      type: object
      properties:
        message:
          type: string
        errors:
          type: object
    ReturnDetails:
      type: object
      description: Detailed information about a specific return.
      properties:
        id:
          type: string
          description: The unique identifier associated with the return.
        state:
          type: string
          description: The current state of the return.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        total:
          type: string
          description: The total cost of the return.
        outcome:
          type: string
          description: The outcome of the return.
        order_id:
          type: string
        order_name:
          type: string
        customer:
          type: string
          description: The customer's email address.
    DetailedReturnList:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier associated with the return.
        state:
          type: string
          description: The current state of the return.
          examples:
            - open
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        total:
          type: string
          examples:
            - '63.30'
        order_id:
          type: string
        order_name:
          type: string
        customer:
          type: string
          description: The customer's email address.
        currency:
          type: string
          examples:
            - USD
        refund:
          type: string
          examples:
            - '63.30'
        carrier:
          type: string
        tracking_number:
          type: string
        label_status:
          type: string
        label_url:
          type:
            - string
            - 'null'
        destination_id:
          type:
            - string
            - 'null'
    AsnReport:
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier associated with the ASN report.
        return_line_item_id:
          type: string
        order_id:
          type: string
        order_name:
          type: string
        state:
          type: string
          description: The status of the return.
        customer_email:
          type: string
        title:
          type: string
          description: The product's name.
        purchase_price:
          type: string
        sku:
          type: string
        barcode:
          type: string
        carrier:
          type: string
        tracking_number:
          type: string
        label_status:
          type: string
        restock_status:
          type: string
        currency:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        closed_at:
          type: string
          format: date-time
  securitySchemes:
    api_key:
      type: apiKey
      name: X-Authorization
      in: header
      description: API key passed via X-Authorization header. Scope required depends on endpoint.