Rillet Products API

openapi: 3.1.0
info:
  title: Rillet Accounting API Key Products API
  version: v4.0
servers:
- url: https://api.rillet.com
  description: Production server url
- url: https://sandbox.api.rillet.com
  description: Test server url
security:
- bearerAuth: []
tags:
- name: Products
paths:
  /products:
    get:
      tags:
      - Products
      operationId: list-all-products
      summary: Lists all products
      description: 'Returns sellable products and services for accounts receivable (contracts, invoices).

        Supports pagination and optional filters such as status and currency.

        '
      parameters:
      - name: status
        in: query
        description: Optional status filter (allowed values depend on the resource).
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/cursor'
      - name: currency
        in: query
        description: Optional ISO currency code filter.
        required: false
        schema:
          $ref: '#/components/schemas/CurrencyCode'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                required:
                - products
                - pagination
                type: object
                properties:
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
      - Products
      operationId: create-a-product
      summary: Creates a product
      description: 'Creates a new product (good or service) that can be referenced on contracts and invoices.

        Choose pricing and revenue behavior consistent with how you bill customers (one-time, recurring, usage, etc.).

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters: []
  /products/{product_id}:
    get:
      tags:
      - Products
      operationId: retrieve-a-product
      summary: Retrieves a product
      description: 'Returns a single product definition including pricing configuration used on contracts and invoices.

        '
      parameters:
      - name: product_id
        in: path
        required: true
        description: UUID of the product to retrieve.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
      - Products
      operationId: update-a-product
      summary: Updates a product
      description: 'Updates a single product definition in the catalog.

        IMPORTANT: This is a full-replace operation (PUT semantics). Include every field expected by ProductRequest;

        omitted fields may be cleared. Call retrieve-a-product first, merge your changes, then submit the full body.

        '
      parameters:
      - name: product_id
        in: path
        required: true
        description: UUID of the product to update.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Products
      operationId: delete-a-product
      summary: Deletes a product
      description: 'Permanently removes a product. Ensure no in-flight contracts or invoices require this product before deleting.

        '
      parameters:
      - name: product_id
        in: path
        required: true
        description: UUID of the product to delete.
        schema:
          type: string
      responses:
        '204':
          description: No Content
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    TieredBilling:
      type: object
      required:
      - type
      - mode
      - tiers
      properties:
        type:
          type: string
          default: TIERED
        mode:
          type: string
          enum:
          - GRADUATED
          - METERED
          description: In metered tiering, the maximum quantity within a period determines the price. In graduated tiering, pricing changes as the quantity grows – the price from each tier up to the reported quantity is accumulated.
        tiers:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Tier'
      description: All tiers except for the highest have to define a value for upTo. There cannot be more than one tier with the same upTo value.
    AccountCode:
      type: string
      description: The account code found in the Chart of Accounts
      example: '11112'
    BillingScheme:
      discriminator:
        propertyName: type
        mapping:
          PER_UNIT: '#/components/schemas/PerUnitBilling'
          TIERED: '#/components/schemas/TieredBilling'
      oneOf:
      - $ref: '#/components/schemas/PerUnitBilling'
      - $ref: '#/components/schemas/TieredBilling'
    Price:
      discriminator:
        propertyName: type
        mapping:
          FIXED_RECURRING: '#/components/schemas/FixedRecurringPrice'
          ONE_TIME: '#/components/schemas/OneTimePrice'
          USAGE: '#/components/schemas/UsagePrice'
      oneOf:
      - $ref: '#/components/schemas/FixedRecurringPrice'
      - $ref: '#/components/schemas/OneTimePrice'
      - $ref: '#/components/schemas/UsagePrice'
      example:
        type: FIXED_RECURRING
        amount:
          amount: '10.00'
          currency: USD
        interval_months: 1
    ExternalReference:
      type: object
      required:
      - type
      - id
      properties:
        type:
          type: string
          example: xyzSystemId
        id:
          type: string
          example: '234'
        url:
          type: string
          format: uri
          example: https://xyzsystempage.com/ids/234
      description: For requests, only pre-defined custom IDs are accepted. In responses, an object imported through an integration (e.g. Stripe) would return the provider's object ID.
    Pagination:
      type: object
      properties:
        next_cursor:
          $ref: '#/components/schemas/PageCursor'
    FixedRecurringPrice:
      allOf:
      - $ref: '#/components/schemas/FixedPrice'
      - $ref: '#/components/schemas/RecurringPrice'
      - type: object
        required:
        - type
        properties:
          type:
            type: string
            default: FIXED_RECURRING
    UsagePrice:
      allOf:
      - $ref: '#/components/schemas/RecurringPrice'
      - type: object
        required:
        - type
        - billing_scheme
        properties:
          type:
            type: string
            default: USAGE
          billing_scheme:
            $ref: '#/components/schemas/BillingScheme'
    MonetaryAmount:
      type: object
      required:
      - amount
      - currency
      properties:
        amount:
          type: string
          description: Monetary amount in decimal format, using a period (.) as the decimal separator. (e.g. '1.01' in $ currency represents 1$ and 1 cent.)
          example: '1.01'
        currency:
          $ref: '#/components/schemas/CurrencyCode'
    Tier:
      type: object
      required:
      - up_to
      properties:
        up_to:
          type: integer
          format: int32
          minimum: 1
          example: 10
        flat_price:
          $ref: '#/components/schemas/MonetaryAmount'
        per_unit_price:
          $ref: '#/components/schemas/MonetaryAmount'
      description: At least one of flatPrice or perUnitPrice has to be defined. flatPrice is the price for the entire tier. perUnitPrice is price for units relevant to the tier.
    Error:
      type: object
      required:
      - type
      - title
      properties:
        type:
          type: string
          format: uri
          description: A URI reference that identifies the error type.
          example: https://rillet.io/forbidden
        title:
          type: string
          description: Summary of the problem.
          example: Forbidden
        status:
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the error.
          example: 403
        detail:
          type: string
          description: Explanation specific to this occurrence of the error.
          example: User does not have rights to perform this operation.
    PageCursor:
      type: string
      description: If defined, a cursor to retrieve the next page.
      example: iLQvkEj3sh3UiweC
    PageLimit:
      type: integer
      minimum: 1
      maximum: 100
      default: 25
    ProductRequest:
      type: object
      required:
      - description
      - include_in_arr_mrr
      - name
      - price
      - revenue_pattern
      - account_code
      properties:
        name:
          maxLength: 250
          minLength: 1
          type: string
          example: English subscription
        description:
          type: string
          example: Subscription to english classes
        price:
          $ref: '#/components/schemas/Price'
        include_in_arr_mrr:
          type: boolean
        revenue_pattern:
          $ref: '#/components/schemas/RevenuePattern'
        account_code:
          $ref: '#/components/schemas/AccountCode'
        status:
          type: string
          default: ACTIVE
          enum:
          - ACTIVE
          - INACTIVE
        external_references:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
    FixedPrice:
      type: object
      required:
      - amount
      properties:
        amount:
          $ref: '#/components/schemas/MonetaryAmount'
    CurrencyCode:
      type: string
      description: Currency code following ISO-4217
      example: USD
    OneTimePrice:
      allOf:
      - $ref: '#/components/schemas/FixedPrice'
      - type: object
        required:
        - type
        properties:
          type:
            type: string
            default: ONE_TIME
    Product:
      type: object
      required:
      - description
      - id
      - include_in_arr_mrr
      - name
      - price
      - revenue_pattern
      - status
      - account_code
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          example: English subscription
        description:
          type: string
          example: Subscription to english classes
        price:
          $ref: '#/components/schemas/Price'
        include_in_arr_mrr:
          type: boolean
        revenue_pattern:
          $ref: '#/components/schemas/RevenuePattern'
        external_references:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
        status:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
        account_code:
          $ref: '#/components/schemas/AccountCode'
    RevenuePattern:
      type: string
      enum:
      - DAILY
      - EVEN_PERIOD
      description: DAILY means that the revenue is divided equally per day in the revenue period. EVEN_PERIOD means that the revenue is divided equally for each calendar month in the revenue period.
    PerUnitBilling:
      type: object
      required:
      - type
      - amount
      - units
      properties:
        type:
          type: string
          default: PER_UNIT
        amount:
          $ref: '#/components/schemas/MonetaryAmount'
        units:
          type: integer
          format: int32
          minimum: 1
          example: 1
    RecurringPrice:
      type: object
      required:
      - interval_months
      properties:
        interval_months:
          type: integer
          format: int32
          minimum: 1
          maximum: 12
          example: 1
  parameters:
    limit:
      name: limit
      in: query
      required: false
      description: Maximum number of rows to return in the page.
      schema:
        $ref: '#/components/schemas/PageLimit'
    cursor:
      name: cursor
      in: query
      required: false
      description: Pagination cursor to navigate through the full response.
      schema:
        $ref: '#/components/schemas/PageCursor'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
x-mcp-ready: true
x-readme:
  headers:
  - key: X-Rillet-API-Version
    value: '4'