openapi: 3.1.0
info:
  title: Loop Returns - Labels API
  description: API for managing label requests and shipping labels for returns.
  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:
    LabelStatusEnum:
      type: string
      description: The status of the label.
      enum:
        - new
        - pre_transit
        - in_transit
        - out_for_delivery
        - delivered
      example: new
    LabelRequestStatusEnum:
      type: string
      description: The status of the label request.
      enum:
        - issued
        - cancelled
        - fulfilled
      example: issued
    ErrorReasonEnum:
      type: string
      description: The error reason.
      enum:
        - INSUFFICIENT_FUNDS
        - INVALID_ADDRESS
        - Other
      example: INVALID_ADDRESS
    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
    MoneySet:
      type: object
      properties:
        amount:
          type: integer
          format: int32
          description: The amount in cents.
          example: 25000
        currency:
          type: string
          default: USD
          example: USD
          description: The ISO 4217 currency code.
      required:
        - amount
        - currency
    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
    Date:
      type: string
      format: date-time
      example: '2023-04-25T13:25:00-05:00'
    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
    UpdateLabelStatusRequest:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/LabelStatusEnum'
      required:
        - status
    LabelRequestErrorResponse:
      type: object
      properties:
        reason:
          $ref: '#/components/schemas/ErrorReasonEnum'
        message:
          type: string
        created_at:
          $ref: '#/components/schemas/Date'
    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'
    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'
    GenerateLabelResponse:
      type: object
      properties:
        message:
          type: string
          example: Label generation queued
        returnId:
          type: integer
          format: int64
          example: 12345
      required:
        - message
        - returnId
  responses:
    NotFound:
      description: The requested entity could not be found.
      content:
        application/json:
          schema:
            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.
    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
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://oauth.loopreturns.com/authorize
          tokenUrl: https://oauth.loopreturns.com/oauth/token
          scopes:
            labels:read: Read access to labels
            labels:write: Create and modify labels
            label_requests:read: Read access to label requests
            label_requests:write: Create and modify label requests
            returns: Access to returns operations
    label-requests-read:
      type: apiKey
      in: header
      name: X-Authorization
      description: 'API Scope: "Label Requests (read)"'
    labels-write:
      name: X-Authorization
      type: apiKey
      in: header
      description: 'API Scope: "Labels (write)"'
    label-requests-write:
      name: X-Authorization
      type: apiKey
      in: header
      description: 'API Scope: "Label Requests (write)"'
    returns:
      name: X-Authorization
      type: apiKey
      in: header
      description: 'API Scope: "Returns"'