Python SDK
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)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}'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 } });{
"customerId": "<string>",
"planId": "<string>",
"override": {
"planId": "<string>",
"unitAmountCents": 123,
"billingUnits": 123,
"capCents": 1,
"effectiveFrom": "2023-11-07T05:31:56Z"
},
"overage": {
"credits": 1,
"costCents": 1,
"unitAmountCents": 123,
"billingUnits": 123,
"capCents": 1,
"capSource": "customer",
"remainingCents": 1,
"source": "plan",
"override": {
"planId": "<string>",
"unitAmountCents": 123,
"billingUnits": 123,
"capCents": 1,
"effectiveFrom": "2023-11-07T05:31:56Z"
},
"periodStart": "2023-11-07T05:31:56Z",
"periodEnd": "2023-11-07T05:31:56Z"
}
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}Customers and usage
Set a customer's overage rate
Set or clear a negotiated overage rate for one customer.
POST
/
v1
/
customers
/
overage-override
Python SDK
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)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}'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 } });{
"customerId": "<string>",
"planId": "<string>",
"override": {
"planId": "<string>",
"unitAmountCents": 123,
"billingUnits": 123,
"capCents": 1,
"effectiveFrom": "2023-11-07T05:31:56Z"
},
"overage": {
"credits": 1,
"costCents": 1,
"unitAmountCents": 123,
"billingUnits": 123,
"capCents": 1,
"capSource": "customer",
"remainingCents": 1,
"source": "plan",
"override": {
"planId": "<string>",
"unitAmountCents": 123,
"billingUnits": 123,
"capCents": 1,
"effectiveFrom": "2023-11-07T05:31:56Z"
},
"periodStart": "2023-11-07T05:31:56Z",
"periodEnd": "2023-11-07T05:31:56Z"
}
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}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.
planIdscopes 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 sendnullto apply the override to any plan with overage. A plan-specific override beats one for any plan.unitAmountCentsis the price perbillingUnitsoverage credits (default 1), in whole cents. For example,{ "unitAmountCents": 100, "billingUnits": 10 }is $1.00 per 10 credits.capCentsis 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 still wins over both.
{ "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 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 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.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
Required string length:
1 - 255Body
application/json
Negotiated price in cents per billingUnits overage credits. Null clears the override for this planId and restores the plan rate.
Required range:
x <= 2147483647The plan this override applies to. Omit or null to apply it to any plan; a plan-specific override beats one for any plan.
Required string length:
1 - 255Credits billed per unitAmountCents. Defaults to 1. Omit when clearing.
Required range:
x <= 2147483647Monthly 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 range:
0 <= x <= 2147483647Response
Customer overage override saved or cleared
The scope that was set or cleared. Null: any plan.
The override now in force for this planId scope. Null once cleared.
Show child attributes
Show child attributes
The effective overage terms on the customer's active paid plan, after this change.
Show child attributes
Show child attributes