Sequence Usage API

openapi: 3.2.0
info:
  title: Sequence Usage API
  description: The Sequence API lets you programmatically manage usage-based billing, pricing, and revenue orchestration - customers, usage events and usage metrics, billing schedules, invoices and credit notes, products and prices, and quotes.
  version: '2024-07-30'
  contact:
    name: Sequence
    url: https://www.sequencehq.com
  x-grounding:
    confirmed:
    - GET /customers
    - POST /api/usage-events
    - GET /billing-schedules
    - GET /invoices
    - GET /products
    modeledNote: Operations not in the confirmed list are documented by name in Sequence's reference index; their schemas and some paths are modeled and flagged with x-modeled.
    source: https://docs.sequencehq.com
    reviewer: API Evangelist
    reviewed: '2026-07-12'
servers:
- url: https://eu.sequencehq.com
  description: Production (EU)
- url: https://sandbox.sequencehq.com
  description: Sandbox
security:
- basicAuth: []
tags:
- name: Usage
  description: Usage event ingestion, usage metrics, and seats.
paths:
  /api/usage-events:
    post:
      operationId: createUsageEvent
      tags:
      - Usage
      summary: Create a usage event
      description: Ingests a single usage event attributed to a customer via its alias and classified by eventType. Confirmed against the live Sequence API reference (host and path). This endpoint has a higher, separate rate limit than standard endpoints.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UsageEventInput'
      responses:
        '200':
          description: The recorded usage event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageEvent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
    get:
      operationId: listUsageEvents
      tags:
      - Usage
      summary: List usage events
      description: Lists previously ingested usage events. Schema modeled.
      x-modeled: true
      responses:
        '200':
          description: A page of usage events.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UsageEvent'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /usage-metrics:
    get:
      operationId: listUsageMetrics
      tags:
      - Usage
      summary: List usage metrics
      description: Lists usage metrics - the aggregation definitions that turn raw usage events into billable quantities. Path and schema modeled from the documented operation.
      x-modeled: true
      responses:
        '200':
          description: A page of usage metrics.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UsageMetric'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createUsageMetric
      tags:
      - Usage
      summary: Create a usage metric
      description: Creates a usage metric. Path and schema modeled.
      x-modeled: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UsageMetric'
      responses:
        '200':
          description: The created usage metric.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageMetric'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    UsageEventInput:
      type: object
      description: Usage event ingestion payload. `customerAlias` and `eventType` are required per the live reference; other fields are optional.
      required:
      - customerAlias
      - eventType
      properties:
        customerAlias:
          type: string
          description: End-customer alias or ID that this event is attributed to.
        eventType:
          type: string
          description: Event type, referenced from a usage metric.
        customerEventId:
          type: string
          description: Idempotency key. A subsequent event with the same customerEventId supersedes the prior one.
        eventTimestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp for when the event occurred.
        eventProperties:
          type: object
          description: Arbitrary custom properties used by metric aggregation.
          additionalProperties: true
    UsageMetric:
      type: object
      description: Usage metric aggregation definition (modeled).
      x-modeled: true
      properties:
        id:
          type: string
        name:
          type: string
        eventType:
          type: string
        aggregationType:
          type: string
          description: Aggregation applied to matching events, for example COUNT or SUM.
        aggregationProperty:
          type: string
    Error:
      type: object
      description: Error envelope (modeled).
      x-modeled: true
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
              additionalProperties: true
    UsageEvent:
      allOf:
      - $ref: '#/components/schemas/UsageEventInput'
      - type: object
        properties:
          id:
            type: string
  responses:
    Unauthorized:
      description: Missing or invalid Basic auth credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'HTTP Basic authentication. The Client ID is the username and the Client Secret is the password, sent as `Authorization: Basic base64(clientId:clientSecret)`. Credentials are created in the Sequence Dashboard; the Client Secret is shown only once.'