> ## Documentation Index
> Fetch the complete documentation index at: https://docs.integrateledger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set a customer's overage cap

> Set or clear the monthly overage spend limit for one customer.

Pass the exact `customerId` as a URL-encoded query value. `capCents` is the most the customer can spend on overage in one billing period, in cents. It replaces the plan's default `overageCapCents` for this customer, so it can be higher or lower than the default, and `0` turns overage off for them. Send `{ "capCents": null }` to clear it and restore the plan default. There is no delete route.

Call this from your own billing page when a customer changes their limit. The cap only matters while the customer's active paid plan has overage. You can set it at any time, and it applies to the current period straight away: [Track usage](https://docs.integrateledger.com/api-reference/usage/track.md) compares the period's overage cost with the new cap on the next request.

The response returns the saved cap and the customer's `overage` for the current period, or `null` when their plan has no overage. Unknown customers return `404 customer_not_found`. The key needs the `customers:write` permission.


## OpenAPI

````yaml openapi.json POST /v1/customers/overage-cap
openapi: 3.1.0
info:
  title: Ledger API
  version: 0.1.0
servers:
  - url: https://api.integrateledger.com
    description: Hosted Ledger API
security: []
paths:
  /v1/customers/overage-cap:
    post:
      tags:
        - Customers
      summary: Set or clear a customer's overage cap
      description: >-
        Send capCents: null to clear the customer's cap and restore the plan
        default.
      operationId: setCustomerOverageCap
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 255
          required: true
          name: customerId
          in: query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetCustomerOverageCapInput'
      responses:
        '200':
          description: Customer overage cap saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerOverageCap'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerError'
        '401':
          description: Missing or invalid Ledger API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerError'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerError'
      security:
        - ApiKey: []
      x-codeSamples:
        - lang: python
          label: Python SDK
          source: >-
            import os

            from integrateledger import ledger


            client = ledger(api_key=os.environ["LEDGER_API_KEY"])

            client.set_customer_overage_cap(customer_id="user_123",
            cap_cents=5000)
        - lang: bash
          label: cURL
          source: >-
            curl --request POST
            'https://api.integrateledger.com/v1/customers/overage-cap?customerId=user_123'
            \
              -H "Authorization: Bearer $LEDGER_API_KEY" \
              -H 'Content-Type: application/json' \
              --data '{"capCents":5000}'
        - lang: typescript
          label: TypeScript SDK
          source: >-
            import ledger from "integrateledger";


            const client = new ledger({ apiKey: process.env.LEDGER_API_KEY ?? ""
            });

            await client.setCustomerOverageCap({ customerId: "user_123", body: {
            capCents: 5000 } });
components:
  schemas:
    SetCustomerOverageCapInput:
      type: object
      properties:
        capCents:
          type: integer
          nullable: true
          minimum: 0
          maximum: 2147483647
          description: >-
            The customer's monthly overage cap in cents. It replaces the plan
            default, higher or lower. Null clears it and restores the plan
            default.
      required:
        - capCents
      additionalProperties: false
    CustomerOverageCap:
      type: object
      properties:
        customerId:
          type: string
        capCents:
          type: integer
          nullable: true
          minimum: 0
        overage:
          $ref: '#/components/schemas/CustomerOverage'
      required:
        - customerId
        - capCents
        - overage
    CustomerError:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    CustomerOverage:
      type: object
      nullable: true
      properties:
        credits:
          type: integer
          minimum: 0
          description: Overage credits recorded in the current billing period.
        costCents:
          type: integer
          minimum: 0
          description: >-
            This period's overage cost: ceil(credits / billingUnits) ×
            unitAmountCents per recorded rate.
        unitAmountCents:
          type: integer
          exclusiveMinimum: 0
        billingUnits:
          type: integer
          exclusiveMinimum: 0
        capCents:
          type: integer
          nullable: true
          minimum: 0
          description: 'Effective monthly overage cap. Null: no cap.'
        capSource:
          type: string
          nullable: true
          enum:
            - customer
            - override
            - plan
            - null
          description: >-
            customer: the customer's own cap; override: the customer's overage
            override; plan: the plan default; null: no cap.
        remainingCents:
          type: integer
          nullable: true
          minimum: 0
        source:
          type: string
          enum:
            - plan
            - override
          description: >-
            Where the overage rate comes from: the plan, or an override set with
            setCustomerOverageOverride.
        override:
          $ref: '#/components/schemas/CustomerOverageOverride'
        periodStart:
          type: string
          format: date-time
        periodEnd:
          type: string
          format: date-time
      required:
        - credits
        - costCents
        - unitAmountCents
        - billingUnits
        - capCents
        - capSource
        - remainingCents
        - source
        - override
        - periodStart
        - periodEnd
    CustomerOverageOverride:
      type: object
      nullable: true
      properties:
        planId:
          type: string
          nullable: true
          description: 'The plan it applies to. Null: any plan.'
        unitAmountCents:
          type: integer
          exclusiveMinimum: 0
        billingUnits:
          type: integer
          exclusiveMinimum: 0
        capCents:
          type: integer
          nullable: true
          minimum: 0
          description: 'The override''s cap. Null: the plan default applies.'
        effectiveFrom:
          type: string
          format: date-time
      required:
        - planId
        - unitAmountCents
        - billingUnits
        - capCents
        - effectiveFrom
      description: The override behind the rate when source is override. Null otherwise.
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.