> ## 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 rate

> Set or clear a negotiated overage rate for one customer.

Pass the exact `customerId` as a URL-encoded query value. The plan stays the default: an override replaces its overage price for one customer, for example after you agree a lower rate with them. It never turns overage on. The plan must already have overage, otherwise the request returns `409 plan_has_no_overage`.

* `planId` scopes the override to one plan (by its API ID, so it keeps applying after you publish a new version of that plan). Omit it or send `null` to apply the override to any plan with overage. A plan-specific override beats one for any plan.
* `unitAmountCents` is the price per `billingUnits` overage credits (default 1), in whole cents. For example, `{ "unitAmountCents": 100, "billingUnits": 10 }` is \$1.00 per 10 credits.
* `capCents` is an optional monthly cap for this override. Leave it out to keep the plan's default cap. A cap the customer set with [Set a customer's overage cap](https://docs.integrateledger.com/api-reference/customers/overage-cap.md) still wins over both.

Send `{ "planId": "pro", "unitAmountCents": null }` to clear the override for that scope and restore the plan rate. There is no delete route. Ledger keeps every change, so the rate history stays.

The new rate applies from the next [Track usage](https://docs.integrateledger.com/api-reference/usage/track.md) request. Usage already recorded keeps the rate it was recorded at, so a change mid-period bills as two lines on the renewal invoice: one at the plan rate and one marked "(negotiated rate)". [Get a customer](https://docs.integrateledger.com/api-reference/customers/get.md) returns the effective rate with `overage.source` set to `override`.

Overrides aren't available for live customers yet, because live plans can't have overage yet: live requests return `409 overage_not_available_in_live_mode`. Unknown customers return `404 customer_not_found`, and an unknown `planId` returns `404 plan_not_found`. The key needs the `customers:write` permission.


## OpenAPI

````yaml openapi.json POST /v1/customers/overage-override
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-override:
    post:
      tags:
        - Customers
      summary: Set or clear a customer's negotiated overage rate
      description: >-
        Overrides only change the terms of a plan that already has overage. Send
        unitAmountCents: null (with the same planId) to clear the override and
        restore the plan rate.
      operationId: setCustomerOverageOverride
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 255
          required: true
          name: customerId
          in: query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetCustomerOverageOverrideInput'
      responses:
        '200':
          description: Customer overage override saved or cleared
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerOverageOverrideResult'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerError'
        '401':
          description: Missing or invalid Ledger API key, or a key without customers:write
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerError'
        '404':
          description: Customer or plan not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerError'
        '409':
          description: >-
            The plan has no overage to override, or overage isn't available in
            live mode yet
          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_override(customer_id="user_123",
            plan_id="pro", unit_amount_cents=8, billing_units=1)
        - lang: bash
          label: cURL
          source: >-
            curl --request POST
            'https://api.integrateledger.com/v1/customers/overage-override?customerId=user_123'
            \
              -H "Authorization: Bearer $LEDGER_API_KEY" \
              -H 'Content-Type: application/json' \
              --data '{"planId":"pro","unitAmountCents":8,"billingUnits":1}'
        - lang: typescript
          label: TypeScript SDK
          source: >-
            import ledger from "integrateledger";


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

            await client.setCustomerOverageOverride({ customerId: "user_123",
            body: { planId: "pro", unitAmountCents: 8, billingUnits: 1 } });
components:
  schemas:
    SetCustomerOverageOverrideInput:
      type: object
      properties:
        planId:
          type: string
          nullable: true
          minLength: 1
          maxLength: 255
          description: >-
            The plan this override applies to. Omit or null to apply it to any
            plan; a plan-specific override beats one for any plan.
        unitAmountCents:
          type: integer
          nullable: true
          exclusiveMinimum: 0
          maximum: 2147483647
          description: >-
            Negotiated price in cents per billingUnits overage credits. Null
            clears the override for this planId and restores the plan rate.
        billingUnits:
          type: integer
          exclusiveMinimum: 0
          maximum: 2147483647
          description: >-
            Credits billed per unitAmountCents. Defaults to 1. Omit when
            clearing.
        capCents:
          type: integer
          nullable: true
          minimum: 0
          maximum: 2147483647
          description: >-
            Monthly overage cap in cents for this override. Omit or null to keep
            the plan default. The customer's own cap (setCustomerOverageCap)
            still wins. Omit when clearing.
      required:
        - unitAmountCents
      additionalProperties: false
    CustomerOverageOverrideResult:
      type: object
      properties:
        customerId:
          type: string
        planId:
          type: string
          nullable: true
          description: 'The scope that was set or cleared. Null: any plan.'
        override:
          allOf:
            - $ref: '#/components/schemas/CustomerOverageOverride'
            - description: >-
                The override now in force for this planId scope. Null once
                cleared.
        overage:
          allOf:
            - $ref: '#/components/schemas/CustomerOverage'
            - description: >-
                The effective overage terms on the customer's active paid plan,
                after this change.
      required:
        - customerId
        - planId
        - override
        - overage
    CustomerError:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    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.
    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
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer

````

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