Paid customers API

openapi: 3.1.0
info:
  title: API Reference agents customers API
  version: 1.0.0
servers:
- url: https://api.agentpaid.io/api/v1
  description: Production
tags:
- name: customers
paths:
  /customers:
    get:
      operationId: list
      summary: List customers
      tags:
      - customers
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Customer'
    post:
      operationId: create
      summary: Create a new customer
      tags:
      - customers
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response - customer already exists with this externalId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerCreate'
  /customers/{customerId}:
    get:
      operationId: get
      summary: Get customer by ID
      tags:
      - customers
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
    put:
      operationId: update
      summary: Update customer
      tags:
      - customers
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Customer updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerUpdate'
    delete:
      operationId: delete
      summary: Delete customer
      tags:
      - customers
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customers_delete_Response_204'
  /customers/{customerId}/entitlement:
    get:
      operationId: check-entitlement
      summary: Check customer entitlement for an event
      tags:
      - customers
      parameters:
      - name: customerId
        in: path
        description: The customer ID
        required: true
        schema:
          type: string
      - name: event_name
        in: query
        description: The name of the usage event to check entitlement for
        required: true
        schema:
          type: string
      - name: view
        in: query
        description: Filter view - 'all' returns all entitlements regardless of status, 'active_only' returns only currently active entitlements with available credits
        required: false
        schema:
          $ref: '#/components/schemas/CustomersCustomerIdEntitlementGetParametersView'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customers_checkEntitlement_Response_200'
        '400':
          description: Bad request (missing event_name parameter)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /customers/{customerId}/credit-bundles:
    get:
      operationId: get-entitlements
      summary: Get customer entitlements
      tags:
      - customers
      parameters:
      - name: customerId
        in: path
        description: The customer ID
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EntitlementUsage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /customers/external/{externalId}:
    get:
      operationId: get-by-external-id
      summary: Get customer by external ID
      tags:
      - customers
      parameters:
      - name: externalId
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
    put:
      operationId: update-by-external-id
      summary: Update customer by external ID
      tags:
      - customers
      parameters:
      - name: externalId
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerUpdate'
    delete:
      operationId: delete-by-external-id
      summary: Delete customer by external ID
      tags:
      - customers
      parameters:
      - name: externalId
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customers_deleteByExternalId_Response_204'
  /customers/external/{externalId}/costs:
    get:
      operationId: get-costs-by-external-id
      summary: Fetch cost traces for a customer by external ID
      tags:
      - customers
      parameters:
      - name: externalId
        in: path
        description: The external ID of the customer
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of traces to return (1-1000)
        required: false
        schema:
          type: integer
          default: 100
      - name: offset
        in: query
        description: Number of traces to skip for pagination
        required: false
        schema:
          type: integer
          default: 0
      - name: startTime
        in: query
        description: Filter traces starting from this time (ISO 8601 format)
        required: false
        schema:
          type: string
          format: date-time
      - name: endTime
        in: query
        description: Filter traces up to this time (ISO 8601 format)
        required: false
        schema:
          type: string
          format: date-time
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostTracesResponse'
        '400':
          description: Bad request - Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /customers/external/{externalId}/usage:
    get:
      operationId: get-usage-by-external-id
      summary: Fetch usage summaries for a customer by external ID
      tags:
      - customers
      parameters:
      - name: externalId
        in: path
        description: The external ID of the customer
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of usage summaries to return (1-1000)
        required: false
        schema:
          type: integer
          default: 100
      - name: offset
        in: query
        description: Number of usage summaries to skip for pagination
        required: false
        schema:
          type: integer
          default: 0
      - name: startTime
        in: query
        description: Filter usage summaries starting from this time (ISO 8601 format). Returns summaries that overlap with the time range.
        required: false
        schema:
          type: string
          format: date-time
      - name: endTime
        in: query
        description: Filter usage summaries up to this time (ISO 8601 format). Returns summaries that overlap with the time range.
        required: false
        schema:
          type: string
          format: date-time
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageSummariesResponse'
        '400':
          description: Bad request - Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /customers/external/{externalId}/payment-methods:
    get:
      operationId: list-payment-methods
      summary: List customer payment methods by external ID
      description: Retrieves all payment methods associated with a customer identified by their external ID.
      tags:
      - customers
      parameters:
      - name: externalId
        in: path
        description: The external ID of the customer
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaymentMethod'
        '403':
          description: Forbidden - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: create-payment-method
      summary: Create customer payment method by external ID
      description: Creates a new payment method for a customer using a Stripe confirmation token.
      tags:
      - customers
      parameters:
      - name: externalId
        in: path
        description: The external ID of the customer
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Payment method created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethod'
        '400':
          description: Bad request - Missing confirmation token or invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                confirmationToken:
                  type: string
                  description: Stripe confirmation token for the payment method
                returnUrl:
                  type: string
                  description: URL to redirect to after payment method setup
                metadata:
                  type: object
                  additionalProperties:
                    description: Any type
                  description: Optional metadata to attach to the payment method
              required:
              - confirmationToken
              - returnUrl
  /customers/external/{externalId}/payment-methods/{paymentMethodId}:
    delete:
      operationId: delete-payment-method
      summary: Delete customer payment method by external ID
      description: Deletes a specific payment method from a customer's account.
      tags:
      - customers
      parameters:
      - name: externalId
        in: path
        description: The external ID of the customer
        required: true
        schema:
          type: string
      - name: paymentMethodId
        in: path
        description: The ID of the payment method to delete
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Payment method deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customers_deletePaymentMethod_Response_204'
        '403':
          description: Forbidden - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Customer or payment method not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /customers/:
    get:
      operationId: list-customers
      summary: List customers
      description: Get a list of customers for the organization
      tags:
      - customers
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
      - name: offset
        in: query
        required: false
        schema:
          type: integer
      - name: name
        in: query
        description: Search by customer name (case-insensitive, matches anywhere in the name).
        required: false
        schema:
          type: string
      - name: status
        in: query
        description: 'Filter by customer status. churned: customers marked as churned. active: everyone else.'
        required: false
        schema:
          $ref: '#/components/schemas/CustomersGetParametersStatus'
      - name: creationState
        in: query
        description: 'Filter by creation state: draft or active.'
        required: false
        schema:
          $ref: '#/components/schemas/CustomersGetParametersCreationState'
      - name: createdAtFrom
        in: query
        description: Only customers created on or after this date. Accepts an ISO 8601 date or date-time. Date-only values (e.g. 2026-06-30) are treated as UTC; date-times without an explicit timezone offset are ambiguous, so include one (e.g. 2026-06-30T00:00:00-05:00) when precision matters.
        required: false
        schema:
          type: string
      - name: createdAtTo
        in: query
        description: Only customers created on or before this date. Accepts an ISO 8601 date or date-time. Date-only values (e.g. 2026-06-30) are treated as UTC; date-times without an explicit timezone offset are ambiguous, so include one (e.g. 2026-06-30T00:00:00-05:00) when precision matters.
        required: false
        schema:
          type: string
      - name: externalId
        in: query
        description: Filter by your external customer ID (exact match).
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerListResponse'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: create-customer
      summary: Create a new customer
      description: Creates a new customer for the organization
      tags:
      - customers
      parameters:
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '201':
          description: '201'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer_2'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
  /customers/{id}/aliases:
    get:
      operationId: list-customer-aliases
      summary: List customer aliases
      description: List alternate external identifiers that resolve to a customer by Paid display ID.
      tags:
      - customers
      parameters:
      - name: id
        in: path
        description: Paid customer display id
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
      - name: offset
        in: query
        required: false
        schema:
          type: integer
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerAliasListResponse'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: create-customer-alias
      summary: Create customer alias
      description: Create an alternate external identifier for a customer by Paid display ID.
      tags:
      - customers
      parameters:
      - name: id
        in: path
        description: Paid customer display id
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '201':
          description: '201'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerAlias'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: '409'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerAliasCreateRequest'
  /customers/{id}/aliases/{alias}:
    delete:
      operationId: delete-customer-alias
      summary: Delete customer alias
      description: Remove an alternate external identifier from a customer by Paid display ID.
      tags:
      - customers
      parameters:
      - name: id
        in: path
        description: Paid customer display id
        required: true
        schema:
          type: string
      - name: alias
        in: path
        description: Customer alias value.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /customers/{id}:
    get:
      operationId: get-customer-by-id
      summary: Get customer
      description: Get a customer by Paid display ID. Use the value returned as `customer.id`, for example `cus_abc123`. If you have your own customer ID, use `GET /api/v2/customers/external/{externalId}`.
      tags:
      - customers
      parameters:
      - name: id
        in: path
        description: Paid customer display id
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer_2'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: update-customer-by-id
      summary: Update customer
      description: Update a customer by Paid display ID. Use the value returned as `customer.id`, for example `cus_abc123`. If you have your own customer ID, use `PUT /api/v2/customers/external/{externalId}`.
      tags:
      - customers
      parameters:
      - name: id
        in: path
        description: Paid customer display id
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer_2'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerRequest'
    delete:
      operationId: delete-customer-by-id
      summary: Delete customer
      description: Delete a customer by Paid display ID. Use the value returned as `customer.id`, for example `cus_abc123`. If you have your own customer ID, use `DELETE /api/v2/customers/external/{externalId}`.
      tags:
      - customers
      parameters:
      - name: id
        in: path
        description: Paid customer display id
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /customers/{id}/state:
    get:
      operationId: get-customer-state-by-id
      summary: Get customer state
      description: Get the current customer state by Paid display ID
      tags:
      - customers
      parameters:
      - name: id
        in: path
        description: Paid customer display id
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerState'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /customers/external/{externalId}/aliases:
    get:
      operationId: list-customer-aliases-by-external-id
      summary: List customer aliases by external ID
      description: List alternate external identifiers that resolve to a customer by external ID.
      tags:
      - customers
      parameters:
      - name: externalId
        in: path
        description: Customer ID from the integrator's system, stored on Paid as `externalId`.
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
      - name: offset
        in: query
        required: false
        schema:
          type: integer
      - name: Authorization
        in: header
        description: API Key authentication 

# --- truncated at 32 KB (84 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paid/refs/heads/main/openapi/paid-customers-api-openapi.yml