Recurrency E-Procurement API

openapi: 3.1.0
info:
  title: Recurrency E-Procurement API
  version: '1.0'
  x-apievangelist-generated: '2026-07-21'
  x-apievangelist-method: generated
  x-apievangelist-source: https://recurrency.gitbook.io/recurrency/
  description: The Recurrency API lets wholesale distributors and B2B suppliers authenticate with Recurrency services, retrieve and filter a supplier's product catalog (items, availability, pricing, locations and groups), upload supplier product catalog data, and create and manage sales orders and quotes. This specification was generated by API Evangelist from Recurrency's published GitBook developer documentation; it is a faithful model of the documented endpoints, not a provider-published OpenAPI.
  contact:
    name: Recurrency Support
    url: https://recurrency.gitbook.io/recurrency/support/need-help
  termsOfService: https://www.recurrency.com/
servers:
- url: https://api.recurrency.com
  description: Production
- url: https://api-staging.recurrency.com
  description: Staging (recommended for initial setup)
security:
- oauth2: []
tags:
- name: E-Procurement
  description: Supplier product catalog retrieval, filtering and upload.
paths:
  /marketplace/suppliers:
    get:
      operationId: listSuppliers
      summary: List available suppliers
      description: Retrieve the list of suppliers available to your tenant. The `slug` on each supplier is the identifier used in the item, location, group and price endpoints.
      tags:
      - E-Procurement
      responses:
        '200':
          description: A list of suppliers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplierList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /marketplace/suppliers/{supplierSlug}/items:
    parameters:
    - $ref: '#/components/parameters/SupplierSlug'
    get:
      operationId: listItems
      summary: Retrieve products
      description: Retrieve and filter a supplier's product catalog items.
      tags:
      - E-Procurement
      parameters:
      - name: searchQuery
        in: query
        schema:
          type: string
        description: Searches item names/codes.
      - name: shortCodes
        in: query
        schema:
          type: array
          items:
            type: string
        description: Filter by short codes.
      - name: groupNames
        in: query
        schema:
          type: array
          items:
            type: string
        description: Filter by group names.
      - name: companyNames
        in: query
        schema:
          type: array
          items:
            type: string
        description: Filter by company names.
      - name: locationNames
        in: query
        schema:
          type: array
          items:
            type: string
        description: Filter by location names.
      - name: minQuantityAvailable
        in: query
        schema:
          type: number
        description: Minimum quantity threshold.
      - name: sortBy
        in: query
        schema:
          type: string
          enum:
          - itemName
          - itemCode
          - itemGroupName
      - name: sortDir
        in: query
        schema:
          type: string
          enum:
          - Asc
          - Desc
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
        description: Results per page.
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
        description: Pagination offset.
      responses:
        '200':
          description: A page of catalog items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: uploadItems
      summary: Upload products
      description: Upload a supplier's product catalog items. Accepts up to a maximum of 100 items per request; `product_name` is required on each item.
      tags:
      - E-Procurement
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemUploadRequest'
      responses:
        '201':
          description: Items created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemUploadResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /marketplace/suppliers/{supplierSlug}/item-locations:
    parameters:
    - $ref: '#/components/parameters/SupplierSlug'
    get:
      operationId: listItemLocations
      summary: Retrieve product locations
      description: Retrieve and filter the locations a supplier stocks items at.
      tags:
      - E-Procurement
      parameters:
      - name: searchQuery
        in: query
        schema:
          type: string
        description: Searches locations by name.
      - name: sortBy
        in: query
        schema:
          type: string
          enum:
          - locationId
          - locationName
      - name: sortDir
        in: query
        schema:
          type: string
          enum:
          - Asc
          - Desc
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: A page of locations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /marketplace/suppliers/{supplierSlug}/item-groups:
    parameters:
    - $ref: '#/components/parameters/SupplierSlug'
    get:
      operationId: listItemGroups
      summary: Retrieve product catalogs (item groups)
      description: Retrieve and filter a supplier's item groups / catalogs.
      tags:
      - E-Procurement
      parameters:
      - name: searchQuery
        in: query
        schema:
          type: string
        description: Filter by item group name.
      - name: companyNames
        in: query
        schema:
          type: array
          items:
            type: string
      - name: sortBy
        in: query
        schema:
          type: string
          enum:
          - itemGroupId
          - itemGroupName
          - companyId
          - companyName
      - name: sortDir
        in: query
        schema:
          type: string
          enum:
          - Asc
          - Desc
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: A page of item groups.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemGroupList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /marketplace/suppliers/{supplierSlug}/item-price:
    parameters:
    - $ref: '#/components/parameters/SupplierSlug'
    get:
      operationId: getItemPrice
      summary: Retrieve product price and availability
      description: Retrieve availability and pricing for a specific item at a specified sales/source location.
      tags:
      - E-Procurement
      parameters:
      - name: itemId
        in: query
        required: true
        schema:
          type: string
      - name: salesLocId
        in: query
        required: true
        schema:
          type: string
      - name: sourceLocId
        in: query
        required: true
        schema:
          type: string
      - name: companyId
        in: query
        schema:
          type: string
      - name: customerId
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Item price and availability.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemPrice'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    ItemUploadResult:
      type: object
      properties:
        message:
          type: string
        createdItems:
          type: array
          items:
            type: object
            properties:
              itemId:
                type: string
              product_name:
                type: string
        totalCreated:
          type: number
    ItemGroupList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ItemGroup'
        totalCount:
          type: number
    Location:
      type: object
      properties:
        locationId:
          type: string
        locationName:
          type: string
    Supplier:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
          description: Identifier used in item/location/group/price endpoints.
        description:
          type: string
        address:
          $ref: '#/components/schemas/Address'
    Address:
      type: object
      properties:
        line1:
          type: string
        line2:
          type:
          - string
          - 'null'
        city:
          type: string
        state:
          type: string
        postalCode:
          type: string
        country:
          type: string
    Item:
      type: object
      properties:
        itemId:
          type: string
        part_number:
          type: string
        product_name:
          type: string
        list_price:
          type: number
        on_hand:
          type: integer
        brand_name:
          type: string
        supplier_name:
          type: string
        manufacturer_part_number:
          type: string
        short_description:
          type: string
        long_description:
          type: string
        images:
          type: array
          items:
            type: object
            properties:
              image_url:
                type: string
              image_type:
                type: string
              default_image:
                type: boolean
        attributes:
          type: array
          items:
            type: object
            properties:
              attribute_name:
                type: string
              attribute_value:
                type: string
        documents:
          type: array
          items:
            type: object
            properties:
              document_name:
                type: string
              document_type:
                type: string
              category_name:
                type: string
        categories:
          type: array
          items:
            type: object
            properties:
              category_code:
                type: string
              category_name:
                type: string
              default_category:
                type: boolean
      required:
      - product_name
    SupplierList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Supplier'
        totalCount:
          type: number
    ItemGroup:
      type: object
      properties:
        itemGroupId:
          type: string
        itemGroupName:
          type: string
        companyId:
          type: string
        companyName:
          type: string
    ItemPrice:
      type: object
      properties:
        itemId:
          type: string
        companyId:
          type: string
        locationId:
          type: string
        locationName:
          type: string
        quantityAvailable:
          type: number
        quantityOnHand:
          type: number
        quantityAllocated:
          type: number
        quantityBackordered:
          type: number
        quantityInProcess:
          type: number
        quantityInTransit:
          type: number
        unitOfMeasure:
          type: string
        unitPrice:
          type: number
    ItemList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        totalCount:
          type: number
    LocationList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Location'
        totalCount:
          type: number
    Error:
      type: object
      description: Standard Recurrency error envelope.
      properties:
        message:
          type: string
          description: Human-readable error message.
        details:
          type: object
          additionalProperties: true
          description: Field-level error details keyed by field path.
      required:
      - message
    ItemUploadRequest:
      type: object
      properties:
        items:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/Item'
      required:
      - items
  responses:
    BadRequest:
      description: Validation error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Invalid request
            details:
              product_name: product_name is required
    Unauthorized:
      description: Missing or invalid access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Unauthorized
            details: {}
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Not found
            details: {}
  parameters:
    SupplierSlug:
      name: supplierSlug
      in: path
      required: true
      description: The supplier identifier (slug) from the suppliers list.
      schema:
        type: string
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'OAuth 2.0 client-credentials. POST to the token endpoint with grant_type=client_credentials plus client_id/client_secret to receive a Bearer access token (scope recurrency:api:tenant), valid for 7 days (604800 seconds). Send it as `authorization: Bearer {token}`.'
      flows:
        clientCredentials:
          tokenUrl: https://api.recurrency.com/oauth/token
          scopes:
            recurrency:api:tenant: Tenant-scoped access to the Recurrency e-procurement API.