Rillet Customers API

openapi: 3.1.0
info:
  title: Rillet Accounting API Key Customers 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: Customers
paths:
  /customers:
    get:
      tags:
      - Customers
      operationId: list-all-customers
      summary: Lists all customers
      description: 'Returns customers for accounts receivable with pagination and optional search or external-reference filters.

        '
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/cursor'
      - name: search
        in: query
        required: false
        schema:
          type: string
        description: Filter customer by name.
      - name: external_reference_id
        in: query
        required: false
        schema:
          type: string
        description: 'If this is provided, `external_reference_type` must also be provided.

          '
      - name: external_reference_type
        in: query
        required: false
        schema:
          type: string
        description: 'If this is provided, `external_reference_id` must also be provided.

          '
      - name: updated.gt
        in: query
        required: false
        description: Filter customers updated after this timestamp
        schema:
          type: string
          format: date-time
          example: '2023-01-01T00:00:00Z'
      - name: sort_by
        in: query
        required: false
        schema:
          type: string
          enum:
          - created
          - updated
          default: created
        description: the field the customers should be sorted by descending (either created or updated)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                required:
                - customers
                type: object
                properties:
                  customers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
      - Customers
      operationId: create-a-customer
      summary: Creates a customer
      description: 'Creates a new customer in the Accounts Receivable catalog.

        Required fields: name. When providing an address, all of these fields are required:

        line1, city, state (2-letter code e.g. ''TN'', ''CA''), zip_code, country.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters: []
  /customers/{customer_id}:
    get:
      tags:
      - Customers
      operationId: retrieve-a-customer
      summary: Retrieves a customer
      description: 'Returns a single customer record including billing profile details, which are needed for updates.

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

        IMPORTANT: This is a full-replace operation (PUT semantics). All fields must be

        included in the request body — omitting any field will set it to null, wiping

        existing data. Always call retrieve-a-customer first to fetch the current record,

        then include ALL existing fields in your update request along with your changes.

        '
      parameters:
      - name: customer_id
        in: path
        description: UUID of the customer to be used in this operation.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Customers
      operationId: delete-a-customer
      summary: Deletes a customer
      description: 'Permanently deletes a customer. Verify no active contracts or open invoices reference this customer first.

        '
      parameters:
      - name: customer_id
        in: path
        required: true
        description: UUID of the customer to delete.
        schema:
          type: string
      responses:
        '204':
          description: No Content
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Customer:
      required:
      - id
      - name
      - updated_at
      allOf:
      - type: object
        properties:
          id:
            type: string
            format: uuid
          updated_at:
            type: string
            format: date-time
            description: ISO 8601 timestamp in UTC timezone (must end with 'Z')
      - $ref: '#/components/schemas/CustomerRequest'
    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.
    FieldAssignments:
      type: array
      items:
        type: object
        required:
        - field_id
        - field_value_id
        properties:
          field_id:
            type: string
            format: uuid
          field_value_id:
            type: string
            format: uuid
    PageCursor:
      type: string
      description: If defined, a cursor to retrieve the next page.
      example: iLQvkEj3sh3UiweC
    PageLimit:
      type: integer
      minimum: 1
      maximum: 100
      default: 25
    CustomerRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          example: Bob
        name_on_invoice:
          type: string
          example: Bob Johnson
        address:
          $ref: '#/components/schemas/Address'
        shipping_address:
          $ref: '#/components/schemas/Address'
        emails:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/CustomerEmail'
        external_references:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
        payment_terms:
          type: integer
          format: int32
          minimum: 0
          example: 0
        send_invoices_automatically:
          type: boolean
          default: false
          description: When set to true, invoices for this customer will be automatically sent via email on the invoice date.
        send_payment_reminders:
          type: boolean
          default: false
          description: When set to true, an email will be sent to customers periodically if they have not paid an invoice.
        fields:
          allOf:
          - $ref: '#/components/schemas/FieldAssignments'
          nullable: true
    Pagination:
      type: object
      properties:
        next_cursor:
          $ref: '#/components/schemas/PageCursor'
    CustomerEmail:
      type: object
      required:
      - email
      - type
      properties:
        email:
          type: string
          example: bobjohnson@somedomain.com
        type:
          type: string
          enum:
          - MAIN_SENDER
          - CC
          - BCC
    CountryCode:
      type: string
      description: Two-letter country code (ISO 3166-1 alpha-2).
      example: US
    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.
    Address:
      type: object
      required:
      - city
      - country
      - line1
      - state
      - zip_code
      properties:
        line1:
          type: string
          example: 123 Main St
        line2:
          type: string
          example: Apt 4B
        city:
          type: string
          example: Nashville
        state:
          type: string
          example: TN
          description: State or province code (e.g. 'TN', 'CA' for US; 'ON' for Canada). Required when address is provided.
        zip_code:
          type: string
          example: '37201'
        country:
          $ref: '#/components/schemas/CountryCode'
  parameters:
    cursor:
      name: cursor
      in: query
      required: false
      description: Pagination cursor to navigate through the full response.
      schema:
        $ref: '#/components/schemas/PageCursor'
    limit:
      name: limit
      in: query
      required: false
      description: Maximum number of rows to return in the page.
      schema:
        $ref: '#/components/schemas/PageLimit'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
x-mcp-ready: true
x-readme:
  headers:
  - key: X-Rillet-API-Version
    value: '4'