openapi: 3.1.0
info:
  title: Listings API
  description: Loop Listings can be utilized to allow exceptions and prevent returns in specific
    situations. This API can be used to manage your shop's listings.
  version: 'v1'
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: Blocklist
  - name: Allowlist
paths:
  /blocklists:
    get:
      summary: 'List Blocklist Items'
      operationId: listBlocklistItems
      tags:
        - Blocklist
      security:
        - api_key: []
      description: |
        Retrieve a list of paginated blocklist entries.

        ### Required API key scope
        - Orders
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedBlocklistResponse'
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
    post:
      summary: 'Create Blocklist Item'
      operationId: createBlocklistItem
      tags:
        - Blocklist
      security:
        - api_key: []
      description: |
        Create a blocklist entry.

        ### Required API key scope
        - Orders
      requestBody:
        $ref: '#/components/requestBodies/CreateBlocklistRequest'
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlocklistEntryWithCreatedAtResponse'
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        "422":
          description: 'Unprocessable'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableResponse'
  /blocklists/{id}:
    get:
      summary: 'Get Blocklist Item'
      operationId: getBlocklistItem
      tags:
        - Blocklist
      security:
        - api_key: []
      description: |
        Retrieve a blocklist entry.

        ### Required API key scope
        - Orders
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier associated with the blocklist entry.
          example: 1
          schema:
            type: integer
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlocklistEntryWithCreatedAtResponse'
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
    delete:
      summary: 'Delete Blocklist Item'
      operationId: deleteBlocklistItem
      tags:
        - Blocklist
      security:
        - api_key: []
      description: |
        Delete a blocklist entry.

        ### Required API key scope
        - Orders
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier associated with the blocklist entry.
          example: 1
          schema:
            type: integer
      responses:
        "204":
          description: "No Content"
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
  /allowlists:
    get:
      summary: 'List Allowlist Items'
      operationId: listAllowlistItems
      tags:
        - Allowlist
      security:
        - api_key: []
      description: |
        Retrieve a list of paginated allowlist entries.

        ### Required API key scope
        - Orders
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedAllowlistResponse'
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
    post:
      summary: 'Create Allowlist Item'
      operationId: createAllowlistItem
      tags:
        - Allowlist
      security:
        - api_key: []
      description: |
        Create an allowlist entry.

        ### Required API key scope
        - Orders
      requestBody:
        $ref: '#/components/requestBodies/CreateAllowlistRequest'
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllowlistEntryWithCreatedAtResponse'
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        "422":
          description: 'Unprocessable'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableResponse'
  /allowlists/{id}:
    get:
      summary: 'Get Allowlist Item'
      operationId: getAllowlistItem
      tags:
        - Allowlist
      security:
        - api_key: []
      description: |
        Retrieve an allowlist entry.

        ### Required API key scope
        - Orders
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier associated with the allowlist entry.
          schema:
            type: integer
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllowlistEntryWithCreatedAtResponse'
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
    delete:
      summary: 'Delete Allowlist Item'
      operationId: deleteAllowlistItem
      tags:
        - Allowlist
      security:
        - api_key: []
      description: |
        Delete an allowlist entry.

        ### Required API key scope
        - Orders
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier associated with the allowlist entry.
          example: 1
          schema:
            type: integer
      responses:
        "204":
          description: "No Content"
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
components:
  schemas:
    BlocklistValueType:
      type: string
      description: The type of value blocked by this blocklist entry. `order` is the order number
        of the blocked order, `email` is the blocked customer's email address, `product` is the
        variant ID of the blocked product, and `product_tag` disables returns for all products
        with that tag.
      enum:
        - order
        - email
        - product
        - product_tag
    AllowlistValueType:
      type: string
      description: The type of value allowed by this allowlist entry. `order` is the order number
        of the allowed order and `email` is the customer's email address.
      enum:
        - order
        - email
    BlocklistEntryWithCreatedAtResponse:
      type: object
      properties:
        id:
          type: integer
          examples:
            - 1
          description: The unique identifier associated with the blocklist entry.
        type:
          $ref: '#/components/schemas/BlocklistValueType'
        value:
          type: string
          examples:
            - example@example.com
          description: The blocked value. Items purchased using this value will be ineligible for return.
        secondary_value:
          type: [string, "null"]
          examples:
            - example.2@example.com
          description: An additional blocked value associated with this entry. Items purchased
            using this value will also be ineligible for return.
        created_at:
          type: [string, "null"]
          format: date-time
          examples:
            - '2023-06-09 00:00:00'
          description: The date and time at which the entry was created.
    PaginatedBlocklistResponse:
      type: object
      properties:
        data:
          type: array
          description: The data for each entry in the blocklist.
          items:
            $ref: '#/components/schemas/BlocklistEntryWithCreatedAtResponse'
        links:
          type: array
          items:
            description: An array of links to each page.
            $ref: '#/components/schemas/PaginatedBlocklistLink'
        next_page_url:
          type: [string, "null"]
          description: The link to the next page of paginated results.
          examples:
            - https://api.loopreturns.com/api/v1/blocklists?page=2
        current_page:
          type: integer
          description: The identifier associated with the current page.
          examples:
            - 1
        from:
          type: [string, "null"]
          description: The number of the first blocklist entry on the page.
          examples:
            - 1
        first_page_url:
          type: [string, "null"]
          description: The link to the first page of paginated results.
          examples:
            - https://api.loopreturns.com/api/v1/blocklists?page=1
        last_page:
          type: [string, "null"]
          description: The identifier associated with the last page.
          examples:
            - 2
        last_page_url:
          type: [string, "null"]
          description: The link to the last page of paginated results.
          examples:
            - https://api.loopreturns.com/api/v1/blocklists?page=2
        path:
          type: [string, "null"]
          description: The endpoint's path.
          examples:
            - https://api.loopreturns.com/api/v1/blocklists
        per_page:
          type: integer
          description: The number of blocklist entries per page.
          examples:
            - 15
        prev_page_url:
          type: [string, "null"]
          description: The link to the previous page of paginated results.
        to:
          type: [integer, "null"]
          description: The number of the last blocklist entry on the page.
          examples:
            - 15
        total:
          type: integer
          description: The total number of blocklist entries returned.
          examples:
            - 20
    AllowlistEntryWithCreatedAtResponse:
      type: object
      properties:
        id:
          type: integer
          examples:
            - 1
          description: The unique identifier associated with the allowlist entry.
        type:
          $ref: '#/components/schemas/AllowlistValueType'
        value:
          type: string
          examples:
            - example@example.com
          description: The allowed value. Returns made using this value will override any other return ineligibility.
        created_at:
          type: [string, "null"]
          examples:
            - '2023-06-09 00:00:00'
          description: The date and time at which the entry was created.
    PaginatedAllowlistResponse:
      type: object
      properties:
        data:
          type: array
          description: The data for each entry in the allowlist.
          items:
            $ref: '#/components/schemas/AllowlistEntryWithCreatedAtResponse'
        links:
          type: array
          description: An array of links to each page.
          items:
            $ref: '#/components/schemas/PaginatedAllowlistLink'
        next_page_url:
          type: [string, "null"]
          description: The link to the next page of paginated results.
          examples:
            - https://api.loopreturns.com/api/v1/allowlists?page=2
        current_page:
          type: integer
          description: The identifier associated with the current page.
          examples:
            - 1
        from:
          type: [string, "null"]
          description: The number of the first allowlist entry on the page.
          examples:
            - 1
        first_page_url:
          type: [string, "null"]
          description: The link to the first page of paginated results.
          examples:
            - https://api.loopreturns.com/api/v1/allowlists?page=1
        last_page:
          type: [string, "null"]
          description: The identifier associated with the last page.
          examples:
            - 2
        last_page_url:
          type: [string, "null"]
          description: The link to the last page of paginated results.
          examples:
            - https://api.loopreturns.com/api/v1/allowlists?page=2
        path:
          type: [string, "null"]
          description: The endpoint's path.
          examples:
            - https://api.loopreturns.com/api/v1/allowlists
        per_page:
          type: integer
          description: The number of allowlist entries per page.
          examples:
            - 15
        prev_page_url:
          type: [string, "null"]
          description: The link to the previous page of paginated results.
        to:
          type: [integer, "null"]
          description: The number of the last allowlist entry on the page.
          examples:
            - 15
        total:
          type: integer
          description: The total number of allowlist entries returned.
          examples:
            - 20
    PaginatedAllowlistLink:
      type: object
      properties:
        url:
          type: string
          description: The link to a page.
          examples:
            - https://api.loopreturns.com/api/v1/allowlists?page=1
        label:
          type: string
          description: The page's label, used to store either page numbers or previous/next page data.
          examples:
            - 1
            - « Previous
            - Next »
        active:
          type: boolean
          description: Whether the page is active.
          examples:
            - true
            - false
    PaginatedBlocklistLink:
      type: object
      properties:
        url:
          type: string
          description: The link to a page.
          examples:
            - https://api.loopreturns.com/api/v1/blocklists?page=1
        label:
          type: string
          description: The page's label, used to store either page numbers or previous/next page data.
          examples:
            - 1
            - « Previous
            - Next »
        active:
          type: boolean
          description: Whether the page is active.
          examples:
            - true
            - false
    UnauthorizedResponse:
      type: object
      required:
        - errors
      properties:
        errors:
          type: string
          examples:
            - "Unauthorized."
    NotFoundResponse:
      type: object
      properties:
        error:
          description: The error message returned when a blocklist entry associated with the given `id` can't be found.
          type: string
          examples:
            - "Listing not found"
    UnprocessableResponse:
      type: object
      properties:
        message:
          description: The error message returned when an unsupported value is submitted in the `type` field.
          type: string
          examples:
            - "Must be one of the following values: order, product, email, product_tag"
        errors:
          type: object
  requestBodies:
    CreateBlocklistRequest:
      content:
        application/json:
          schema:
            type: object
            required:
              - value
              - type
            properties:
              value:
                type: string
                examples:
                  - 'example@example.com'
                description: The blocked value. Items purchased using this value will be ineligible for return.
              type:
                $ref: '#/components/schemas/BlocklistValueType'
              secondary_value:
                type: string
                examples:
                  - example.2@example.com
                description: An additional blocked value associated with this entry. Items purchased
                  using this value will also be ineligible for return.
    CreateAllowlistRequest:
      content:
        application/json:
          schema:
            type: object
            required:
              - value
              - type
            properties:
              value:
                type: string
                examples:
                  - 'example@example.com'
                description: The allowed value. Returns made using this value will override any
                  other return ineligibility.
              type:
                $ref: '#/components/schemas/AllowlistValueType'
  securitySchemes:
    api_key:
      type: 'apiKey'
      name: 'X-Authorization'
      in: 'header'