openapi: 3.1.0
info:
  title: Happy Returns Shipment API
  version: 'v1'
  description: API used for getting Happy Returns shipment and item details.
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: Happy Returns Shipment
  - name: Happy Returns Shipment Items
paths:
  /happy-returns/shipments/{happy_returns_shipment_id}:
    get:
      tags:
        - Happy Returns Shipment
      security:
        - api_key: []
      description: |
        Get high level information from a Happy Returns shipment.

        ### Required API key scope
        - Happy Returns Shipments (Read)
      summary: 'Get Shipment Information'
      parameters:
        - in: path
          name: happy_returns_shipment_id
          schema:
            type: string
          example: "210123"
          required: true
          description: The unique identifier associated with the shipment.
      operationId: getShipment
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "404":
          $ref: '#/components/responses/NotFound'
  /happy-returns/shipments:
    get:
      tags:
        - Happy Returns Shipment
      security:
        - api_key: []
      summary: 'Get Shipments'
      description: |
        Get information about all Happy Returns shipments created within a given timeframe.
        The response is a paginated list of shipments, with up to 200 shipments per page.

        If no date range is provided, the response will return data from the last 24 hours.
        ### Required API key scope
        - Happy Returns Shipments (Read)
      parameters:
        - name: from
          example: 2024-01-01 00:00:00
          in: query
          description: The start date and time for the shipment list, using the ISO 8601 date format.
          schema:
            type: string
            format: date-time
            examples:
              - 2024-01-01 00:00:00
        - name: to
          example: 2024-03-31 23:59:59
          in: query
          description: The end date and time for the shipment list, using the ISO 8601 date format.
          schema:
            type: string
            format: date-time
            examples:
              - 2024-03-31 23:59:59
        - name: page
          in: query
          description: The page number of paginated results to return.
          schema:
            type: integer
            minimum: 1
            examples:
              - 1
      operationId: getShipments
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                properties:
                  current_page:
                    type: integer
                    examples:
                      - 1
                    description: The identifier associated with the current page.
                  data:
                    type: array
                    description: The data for each entry in the shipment list.
                    items:
                      $ref: '#/components/schemas/Shipment'
                  first_page_url:
                    type: string
                    examples:
                      - "https://api.loopreturns.com/api/v1/happy-returns/shipments/list?from=2022-01-01&to=2023-03-01&page=1"
                    description: The link to the first page of paginated results.
                  from:
                    type: integer
                    examples:
                      - 1
                    description: The number of the first shipment on the page.
                  last_page:
                    type: integer
                    examples:
                      - 1
                    description: The identifier associated with the last page.
                  last_page_url:
                    type: string
                    examples:
                      - "https://api.loopreturns.com/api/v1/happy-returns/shipments/list?from=2022-01-01&to=2023-03-01&page=1"
                    description: The link to the last page of paginated results.
                  next_page_url:
                    type: [string, "null"]
                    description: The link to the next page of paginated results.
                  path:
                    type: string
                    examples:
                      - "https://api.loopreturns.com/api/v1/happy-returns/shipments/list"
                    description: The endpoint's path.
                  per_page:
                    type: integer
                    examples:
                      - 200
                    description: The number of shipments per page.
                  prev_page_url:
                    type: [string, "null"]
                    description: The link to the previous page of paginated results.
                  to:
                    type: integer
                    examples:
                      - 1
                    description: The number of the last shipment on the page.
                  total:
                    type: integer
                    examples:
                      - 1
                    description: The total number of shipments returned.
        "401":
          $ref: '#/components/responses/Unauthorized'
        "404":
          $ref: '#/components/responses/NotFound'
        "422":
          $ref: '#/components/responses/UnprocessableContent'
  /happy-returns/shipments/{id}/items:
    get:
      tags:
        - Happy Returns Shipment Items
      security:
        - api_key: []
      description: |
        Get all items for a Happy Returns shipment.

        ### Required API key scope
        - Happy Returns Shipments (Read)
      summary: "Get Shipment Items"
      operationId: getShipmentItems
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier associated with the shipment, assigned by Loop.
          schema:
            type: integer
          example: 47382
        - name: page
          in: query
          description: The page number of paginated results to return.
          schema:
            type: integer
            examples:
              - 1
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                properties:
                  current_page:
                    type: integer
                    examples:
                      - 1
                    description: The identifier associated with the current page.
                  data:
                    type: array
                    description: The data for each item in the shipment.
                    items:
                      $ref: '#/components/schemas/ShipmentItem'
                  first_page_url:
                    type: string
                    examples:
                      - "https://api.loopreturns.com/api/v1/happy-returns/shipments/123/items?page=1"
                    description: The link to the first page of paginated results.
                  from:
                    type: integer
                    examples:
                      - 1
                    description: The number of the first item on the page.
                  last_page:
                    type: integer
                    examples:
                      - 1
                    description: The identifier associated with the last page.
                  last_page_url:
                    type: string
                    examples:
                      - "https://api.loopreturns.com/api/v1/happy-returns/shipments/123/items?page=1"
                    description: The link to the last page of paginated results.
                  next_page_url:
                    type: [string, "null"]
                    description: The link to the next page of paginated results.
                  path:
                    type: string
                    examples:
                      - "https://api.loopreturns.com/api/v1/happy-returns/shipments/123/items"
                    description: The endpoint's path.
                  per_page:
                    type: integer
                    examples:
                      - 200
                    description: The number of items per page.
                  prev_page_url:
                    type: [string, "null"]
                    description: The link to the previous page of paginated results.
                  to:
                    type: integer
                    examples:
                      - 1
                    description: The number of the last item on the page.
                  total:
                    type: integer
                    examples:
                      - 1
                    description: The total number of items returned.
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        "404":
          description: "Not Found"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
components:
  responses:
    Unauthorized:
      description: "Unauthorized"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedResponse'
    NotFound:
      description: "Not Found"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundResponse'
    UnprocessableContent:
      description: "Unprocessable Content"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnprocessableResponse'
  schemas:
    Shipment:
      type: object
      properties:
        loop_shipment_id:
          type: integer
          examples:
            - 12345
          description: The unique identifier associated with the shipment, assigned by Loop.
        happy_returns_shipment_id:
          type: string
          examples:
            - '123456'
          description: The unique identifier associated with the shipment, assigned by Happy Returns.
        line_item_count:
          type: integer
          examples:
            - 2
          description: The number of line items included in the shipment.
        return_count:
          type: integer
          examples:
            - 1
          description: The number of Loop returns represented in the shipment.
        created_at:
          type: string
          format: date-time
          examples:
            - '2024-03-19T12:34:56+00:00'
          description: The date and time at which the shipment was created, using the ISO 8601 date format.
        updated_at:
          type: string
          format: date-time
          examples:
            - '2024-03-20T12:34:56+00:00'
          description: The date and time at which the shipment was last updated, using the ISO 8601 date format.
    ShipmentItem:
      type: object
      properties:
        carrier:
          type: [string, "null"]
          examples:
            - 'ups'
          description: The carrier associated with the item.
        happy_returns_return_bag_barcodes:
          type: [array, "null"]
          items:
            type: string
          examples:
            - ['HRABCDEF-1234-1']
          description: The identifier that appears on Happy Returns polybags.
        happy_returns_rma_id:
          type: [string, "null"]
          examples:
            - 'HRABCDEF'
          description: The identifier shared with the customer for dropping the item off at a Return Bar.
        happy_returns_shipment_id:
          type: [string, "null"]
          examples:
            - '45678'
          description: The unique identifier associated with the shipment, assigned by Happy Returns.
        item_title:
          type: [string, "null"]
          examples:
            - 'T-Shirt'
          description: The name of the item.
        order_name:
          type: [string, "null"]
          examples:
            - '#1234'
          description: The name of the order.
        po_number:
          type: [string, "null"]
          examples:
            - 'PO-123456'
          description: The identifier associated with a consolidated shipment from Happy Returns.
        return_id:
          type: [integer, "null"]
          examples:
            - 123
          description: The return's unique identifier.
        shipment_id:
          type: integer
          examples:
            - 12345
          description: The unique identifier associated with the shipment, assigned by Loop.
        shipping_box_barcode:
          type: [string, "null"]
          examples:
            - 'SB-12345678'
          description: The identifier that appears on the outside of a consolidated box shipped by Happy Returns.
        sku:
          type: [string, "null"]
          examples:
            - 'SKU-123456'
          description: The SKU of the product variant being returned.
        tracking_number:
          type: [string, "null"]
          examples:
            - '1Z1234567890'
          description: The return's tracking number.
        variant_title:
          type: [string, "null"]
          examples:
            - 'Blue'
          description: The name of the product variant.
        created_at:
          type: [string, "null"]
          format: date-time
          examples:
            - '2024-03-19T12:34:56+00:00'
          description: The date and time at which the shipment item was created, using the ISO 8601 date format.
    UnauthorizedResponse:
      type: object
      required:
        - errors
      properties:
        errors:
          type: string
          examples:
            - "Unauthorized."
    NotFoundResponse:
      type: object
      properties:
        message:
          type: string
          examples:
            - 'Not Found'
    UnprocessableResponse:
      type: object
      properties:
        message:
          type: string
          examples:
            - "The from field must be a valid ATOM date."
        errors:
          type: object
          examples:
            - from:
                - "The from field must be a valid ATOM date."
  securitySchemes:
    api_key:
      type: 'apiKey'
      name: 'X-Authorization'
      in: 'header'