Loop Returns Label Requests API

openapi: 3.1.0
info:
  title: Loop Returns Cart Label Requests API
  description: API for managing shop carts in Shop Now On-Store exchanges.
  version: v1
servers:
- url: https://api.loopreturns.com/api/v1
tags:
- name: Label Requests
paths:
  /label-requests:
    get:
      summary: List Label Requests
      description: Retrieve a list of label requests.
      operationId: list-label-requests
      tags:
      - Label Requests
      security:
      - oauth2:
        - label_requests:read
      - label-requests-read: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LabelRequestResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      parameters:
      - in: query
        name: from
        description: Returns label requests after or equal to a minimum date.
        schema:
          $ref: '#/components/schemas/Date'
      - in: query
        name: to
        description: Returns label requests before a maximum date.
        schema:
          $ref: '#/components/schemas/Date'
      - in: query
        name: return_id
        description: Return label requests associated with a specific return_id.
        schema:
          type: integer
          example: 67329889100573
      - in: query
        name: status
        schema:
          $ref: '#/components/schemas/LabelRequestStatusEnum'
      - in: query
        name: limit
        description: The per page limit of label requests to return.
        schema:
          type: integer
          default: 50
          minimum: 0
          maximum: 250
      - in: query
        name: offset
        description: The number of label requests to offset.
        schema:
          type: integer
  /label-requests/{id}:
    get:
      summary: Get Label Request
      description: Get details about a single label request.
      operationId: get-label-request
      tags:
      - Label Requests
      security:
      - oauth2:
        - label_requests:read
      - label-requests-read: []
      parameters:
      - in: path
        name: id
        schema:
          type: integer
          example: 67329889100573
        required: true
        description: The unique identifier for the label request, created by Loop.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelRequestResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /label-requests/{id}/errors:
    post:
      summary: Create Label Request Error
      description: Submit unrecoverable errors encountered when generating labels for merchants.
      operationId: create-label-request-error
      tags:
      - Label Requests
      security:
      - oauth2:
        - label_requests:write
      - label-requests-write: []
      parameters:
      - in: path
        name: id
        schema:
          type: integer
          example: 67329889100573
        required: true
        description: The unique identifier for the label request, created by Loop.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLabelRequestErrorRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelRequestErrorResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /labels:
    post:
      summary: Create Label
      description: Create a label for a label request.
      operationId: create-label-request-label
      tags:
      - Label Requests
      security:
      - oauth2:
        - labels:write
      - labels-write: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLabelRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /labels/{id}:
    put:
      summary: Update Label Status
      description: Update the status of a label.
      operationId: update-label-status
      tags:
      - Label Requests
      security:
      - oauth2:
        - labels:write
      - labels-write: []
      parameters:
      - in: path
        name: id
        schema:
          type: integer
          example: 67329889100573
        required: true
        description: The unique identifier for the label, created by Loop.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLabelStatusRequest'
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /returns/{returnId}/labels:
    post:
      summary: Generate Label
      description: Queue label generation for a return. Triggers an asynchronous label generation process.
      operationId: generate-label
      tags:
      - Label Requests
      security:
      - oauth2:
        - returns
      - returns: []
      parameters:
      - in: path
        name: returnId
        schema:
          type: integer
          example: 12345
        required: true
        description: The unique identifier for the return, created by Loop.
      responses:
        '202':
          description: Label generation queued successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateLabelResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Return not found.
        '409':
          description: Label already exists for this return.
        '422':
          description: Return cannot receive a label or label generation failed.
        '500':
          description: Internal server error.
components:
  schemas:
    GenerateLabelResponse:
      type: object
      properties:
        message:
          type: string
          example: Label generation queued
        returnId:
          type: integer
          format: int64
          example: 12345
      required:
      - message
      - returnId
    CreateLabelRequest:
      type: object
      properties:
        label_request_id:
          type: integer
          example: 67329889100573
        tracking_number:
          type: string
          maxLength: 256
          example: '9400136105440512280610'
        tracking_url:
          type:
          - string
          - 'null'
          maxLength: 2048
        carrier:
          type: string
          maxLength: 32
          example: USPS
        label_url:
          type: string
          maxLength: 2048
          example: https://s3.amazonaws.com/example-bucket/label.pdf
        qrcode_url:
          type: string
          maxLength: 512
          example: https://s3.amazonaws.com/example-bucket/qrcode.pdf
        rate:
          $ref: '#/components/schemas/MoneySetData'
      required:
      - label_request_id
      - tracking_number
      - carrier
      - label_url
      - rate
    LabelResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 67329889100573
        tracking_number:
          type: string
        tracking_url:
          type: string
        carrier:
          type: string
          example: USPS
        label_url:
          type: string
        qrcode_url:
          type: string
        rate:
          $ref: '#/components/schemas/MoneySetData'
        status:
          type: string
          example: new
        created_at:
          $ref: '#/components/schemas/Date'
    CreateLabelRequestErrorRequest:
      type: object
      properties:
        reason:
          $ref: '#/components/schemas/ErrorReasonEnum'
        message:
          type: string
          example: Failed to generate a label, the origin address is invalid
      required:
      - reason
    Date:
      type: string
      format: date-time
      example: '2023-04-25T13:25:00-05:00'
    LabelRequestErrorResponse:
      type: object
      properties:
        reason:
          $ref: '#/components/schemas/ErrorReasonEnum'
        message:
          type: string
        created_at:
          $ref: '#/components/schemas/Date'
    LabelRequestStatusEnum:
      type: string
      description: The status of the label request.
      enum:
      - issued
      - cancelled
      - fulfilled
      example: issued
    LabelRequestResponse:
      type: object
      properties:
        id:
          type: string
          example: '67329889100573'
        addresses:
          type: object
          properties:
            origin:
              $ref: '#/components/schemas/Address'
            destination:
              $ref: '#/components/schemas/Address'
        parcel:
          type: object
          properties:
            height:
              type: number
              format: double
              description: Height in inches.
              example: 5
            length:
              type: number
              format: double
              description: Length in inches.
              example: 20.2
            width:
              type: number
              format: double
              description: Width in inches.
              example: 10.9
            weight:
              type: number
              format: double
              description: Weight in grams.
              example: 65.9
        return_id:
          type: integer
          format: int64
          example: 1001
        shop_id:
          type: integer
          format: int64
          example: 50
        status:
          $ref: '#/components/schemas/LabelRequestStatusEnum'
        created_at:
          $ref: '#/components/schemas/Date'
    Address:
      type: object
      properties:
        name:
          type: string
          maxLength: 100
        company:
          type:
          - string
          - 'null'
          maxLength: 100
        address1:
          type: string
          maxLength: 125
        address2:
          type:
          - string
          - 'null'
          maxLength: 125
        city:
          type: string
          maxLength: 100
        region:
          type:
          - string
          - 'null'
          maxLength: 100
        postal_code:
          type:
          - string
          - 'null'
          maxLength: 16
        country:
          type:
          - string
          - 'null'
          maxLength: 100
        country_code:
          type: string
          maxLength: 2
          description: The two-letter country code.
      required:
      - address1
      - city
      - country_code
    LabelStatusEnum:
      type: string
      description: The status of the label.
      enum:
      - new
      - pre_transit
      - in_transit
      - out_for_delivery
      - delivered
      example: new
    ErrorReasonEnum:
      type: string
      description: The error reason.
      enum:
      - INSUFFICIENT_FUNDS
      - INVALID_ADDRESS
      - Other
      example: INVALID_ADDRESS
    UpdateLabelStatusRequest:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/LabelStatusEnum'
      required:
      - status
    MoneySetData:
      type: object
      properties:
        amount:
          type: integer
          format: int32
          description: The amount in cents.
          example: 25000
        currency_code:
          type: string
          default: USD
          example: USD
          description: The ISO 4217 currency code.
      required:
      - amount
      - currency_code
  responses:
    NotFound:
      description: The requested entity could not be found.
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
    BadRequest:
      description: The request could not be processed.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
    Unauthorized:
      description: The request could not be authorized.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: '401'
                  http_code:
                    type: string
                    example: GEN-UNAUTHORIZED
                  message:
                    type: string
                    example: Unauthorized.
  securitySchemes:
    api_key:
      type: apiKey
      name: X-Authorization
      in: header