[{"data":1,"prerenderedAt":745},["ShallowReactive",2],{"navigation_docs":3,"-guides-usage-billing":132,"-guides-usage-billing-surround":740},[4,30,47,128],{"title":5,"path":6,"stem":7,"children":8,"page":29},"Getting Started","\u002Fgetting-started","1.getting-started",[9,13,17,21,25],{"title":10,"path":11,"stem":12},"Introduction","\u002Fgetting-started\u002Fintroduction","1.getting-started\u002F1.introduction",{"title":14,"path":15,"stem":16},"Quickstart","\u002Fgetting-started\u002Fquickstart","1.getting-started\u002F2.quickstart",{"title":18,"path":19,"stem":20},"Authentication","\u002Fgetting-started\u002Fauthentication","1.getting-started\u002F3.authentication",{"title":22,"path":23,"stem":24},"Self-Hosting","\u002Fgetting-started\u002Fself-hosting","1.getting-started\u002F4.self-hosting",{"title":26,"path":27,"stem":28},"Build an Integration","\u002Fgetting-started\u002Fbuild-an-integration","1.getting-started\u002F5.build-an-integration",false,{"title":31,"path":32,"stem":33,"children":34,"page":29},"Sdks","\u002Fsdks","2.sdks",[35,39,43],{"title":36,"path":37,"stem":38},"TypeScript SDK","\u002Fsdks\u002Ftypescript","2.sdks\u002F1.typescript",{"title":40,"path":41,"stem":42},"Python SDK","\u002Fsdks\u002Fpython","2.sdks\u002F2.python",{"title":44,"path":45,"stem":46},"PHP SDK","\u002Fsdks\u002Fphp","2.sdks\u002F3.php",{"title":48,"path":49,"stem":50,"children":51,"page":29},"Guides","\u002Fguides","3.guides",[52,56,60,64,68,72,76,80,84,88,92,96,100,104,108,112,116,120,124],{"title":53,"path":54,"stem":55},"Customers","\u002Fguides\u002Fcustomers","3.guides\u002F1.customers",{"title":57,"path":58,"stem":59},"Usage-Based Billing","\u002Fguides\u002Fusage-billing","3.guides\u002F10.usage-billing",{"title":61,"path":62,"stem":63},"Wallets","\u002Fguides\u002Fwallets","3.guides\u002F11.wallets",{"title":65,"path":66,"stem":67},"Coupons, Add-ons and Credit Notes","\u002Fguides\u002Fcoupons-add-ons-credit-notes","3.guides\u002F12.coupons-add-ons-credit-notes",{"title":69,"path":70,"stem":71},"Taxes","\u002Fguides\u002Ftaxes","3.guides\u002F13.taxes",{"title":73,"path":74,"stem":75},"Customer Portal","\u002Fguides\u002Fcustomer-portal","3.guides\u002F14.customer-portal",{"title":77,"path":78,"stem":79},"Ledger","\u002Fguides\u002Fledger","3.guides\u002F15.ledger",{"title":81,"path":82,"stem":83},"Plan Limits and Access","\u002Fguides\u002Fplan-limits-and-access","3.guides\u002F16.plan-limits-and-access",{"title":85,"path":86,"stem":87},"Currencies and Exchange Rates","\u002Fguides\u002Fcurrencies","3.guides\u002F17.currencies",{"title":89,"path":90,"stem":91},"Charge a Customer","\u002Fguides\u002Fcharge-a-customer","3.guides\u002F18.charge-a-customer",{"title":93,"path":94,"stem":95},"One-time Products & Partial Payments","\u002Fguides\u002Fone-time-products-and-partial-payments","3.guides\u002F19.one-time-products-and-partial-payments",{"title":97,"path":98,"stem":99},"Plans & Pricing","\u002Fguides\u002Fplans-and-pricing","3.guides\u002F2.plans-and-pricing",{"title":101,"path":102,"stem":103},"Subscriptions","\u002Fguides\u002Fsubscriptions","3.guides\u002F3.subscriptions",{"title":105,"path":106,"stem":107},"Invoices & Payments","\u002Fguides\u002Finvoices-and-payments","3.guides\u002F4.invoices-and-payments",{"title":109,"path":110,"stem":111},"Payment Providers","\u002Fguides\u002Fpayment-providers","3.guides\u002F5.payment-providers",{"title":113,"path":114,"stem":115},"Analytics","\u002Fguides\u002Fanalytics","3.guides\u002F6.analytics",{"title":117,"path":118,"stem":119},"Webhooks","\u002Fguides\u002Fwebhooks","3.guides\u002F7.webhooks",{"title":121,"path":122,"stem":123},"Sandbox","\u002Fguides\u002Fsandbox","3.guides\u002F8.sandbox",{"title":125,"path":126,"stem":127},"Money Movement","\u002Fguides\u002Fmoney-movement","3.guides\u002F9.money-movement",{"title":129,"path":130,"stem":131},"API Reference","\u002Fapi-reference","4.api-reference",{"id":133,"title":57,"body":134,"description":733,"extension":734,"links":735,"meta":736,"navigation":737,"path":58,"seo":738,"stem":59,"__hash__":739},"docs\u002F3.guides\u002F10.usage-billing.md",{"type":135,"value":136,"toc":727},"minimark",[137,154,159,263,272,372,387,391,394,495,565,587,591,671,706,712,716,723],[138,139,140,141,145,146,149,150,153],"p",{},"Usage billing has three parts: a ",[142,143,144],"strong",{},"billable metric"," says what to count, a ",[142,147,148],{},"charge"," puts a price on that metric in a plan, and ",[142,151,152],{},"events"," report what each subscription used. At the end of each billing period, usage is aggregated per subscription and invoiced with the plan's fixed price.",[155,156,158],"h2",{"id":157},"_1-define-a-billable-metric","1. Define a billable metric",[160,161,166],"pre",{"className":162,"code":163,"language":164,"meta":165,"style":165},"language-bash shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","curl -X POST https:\u002F\u002Fapi.pimabill.com\u002Fapi\u002Fbillable-metrics \\\n  -H \"Authorization: Bearer sk_live_a1b2c3d4...\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"name\": \"API Calls\",\n    \"code\": \"api_calls\",\n    \"aggregationType\": \"COUNT\"\n  }'\n","bash","",[167,168,169,192,210,224,236,242,248,254],"code",{"__ignoreMap":165},[170,171,174,178,182,185,188],"span",{"class":172,"line":173},"line",1,[170,175,177],{"class":176},"sBMFI","curl",[170,179,181],{"class":180},"sfazB"," -X",[170,183,184],{"class":180}," POST",[170,186,187],{"class":180}," https:\u002F\u002Fapi.pimabill.com\u002Fapi\u002Fbillable-metrics",[170,189,191],{"class":190},"sTEyZ"," \\\n",[170,193,195,198,202,205,208],{"class":172,"line":194},2,[170,196,197],{"class":180},"  -H",[170,199,201],{"class":200},"sMK4o"," \"",[170,203,204],{"class":180},"Authorization: Bearer sk_live_a1b2c3d4...",[170,206,207],{"class":200},"\"",[170,209,191],{"class":190},[170,211,213,215,217,220,222],{"class":172,"line":212},3,[170,214,197],{"class":180},[170,216,201],{"class":200},[170,218,219],{"class":180},"Content-Type: application\u002Fjson",[170,221,207],{"class":200},[170,223,191],{"class":190},[170,225,227,230,233],{"class":172,"line":226},4,[170,228,229],{"class":180},"  -d",[170,231,232],{"class":200}," '",[170,234,235],{"class":180},"{\n",[170,237,239],{"class":172,"line":238},5,[170,240,241],{"class":180},"    \"name\": \"API Calls\",\n",[170,243,245],{"class":172,"line":244},6,[170,246,247],{"class":180},"    \"code\": \"api_calls\",\n",[170,249,251],{"class":172,"line":250},7,[170,252,253],{"class":180},"    \"aggregationType\": \"COUNT\"\n",[170,255,257,260],{"class":172,"line":256},8,[170,258,259],{"class":180},"  }",[170,261,262],{"class":200},"'\n",[138,264,265,267,268,271],{},[167,266,167],{}," is what your events refer to. ",[167,269,270],{},"aggregationType"," decides how events become a quantity:",[273,274,275,294],"table",{},[276,277,278],"thead",{},[279,280,281,285,288],"tr",{},[282,283,284],"th",{},"Type",[282,286,287],{},"Quantity for the period",[282,289,290,291],{},"Needs ",[167,292,293],{},"fieldName",[295,296,297,311,324,336,348,360],"tbody",{},[279,298,299,305,308],{},[300,301,302],"td",{},[167,303,304],{},"COUNT",[300,306,307],{},"Number of events",[300,309,310],{},"No",[279,312,313,318,321],{},[300,314,315],{},[167,316,317],{},"SUM",[300,319,320],{},"Sum of a property, e.g. tokens used",[300,322,323],{},"Yes",[279,325,326,331,334],{},[300,327,328],{},[167,329,330],{},"MAX",[300,332,333],{},"Highest value seen, e.g. peak seats",[300,335,323],{},[279,337,338,343,346],{},[300,339,340],{},[167,341,342],{},"UNIQUE_COUNT",[300,344,345],{},"Distinct values of a property, e.g. active users",[300,347,323],{},[279,349,350,355,358],{},[300,351,352],{},[167,353,354],{},"LATEST",[300,356,357],{},"Last value reported, e.g. storage used",[300,359,323],{},[279,361,362,367,370],{},[300,363,364],{},[167,365,366],{},"WEIGHTED_SUM",[300,368,369],{},"Value weighted by how long it applied",[300,371,323],{},[138,373,374,375,378,379,382,383,386],{},"Set ",[167,376,377],{},"recurring: true"," for quantities that carry over between periods (such as seats). Add ",[167,380,381],{},"filters"," to price the same metric differently by property value, for example by ",[167,384,385],{},"region",".",[155,388,390],{"id":389},"_2-price-it-on-a-plan","2. Price it on a plan",[138,392,393],{},"A charge attaches a metric to a plan with a pricing model:",[160,395,397],{"className":162,"code":396,"language":164,"meta":165,"style":165},"curl -X POST https:\u002F\u002Fapi.pimabill.com\u002Fapi\u002Fcharges \\\n  -H \"Authorization: Bearer sk_live_a1b2c3d4...\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"planId\": \"plan_pro\",\n    \"billableMetricId\": \"bm_api_calls\",\n    \"chargeModel\": \"GRADUATED\",\n    \"invoiceDisplayName\": \"API calls\",\n    \"graduatedRanges\": [\n      { \"fromValue\": 0, \"toValue\": 10000, \"perUnitAmount\": 0 },\n      { \"fromValue\": 10001, \"perUnitAmount\": 0.002 }\n    ]\n  }'\n",[167,398,399,412,424,436,444,449,454,459,464,470,476,482,488],{"__ignoreMap":165},[170,400,401,403,405,407,410],{"class":172,"line":173},[170,402,177],{"class":176},[170,404,181],{"class":180},[170,406,184],{"class":180},[170,408,409],{"class":180}," https:\u002F\u002Fapi.pimabill.com\u002Fapi\u002Fcharges",[170,411,191],{"class":190},[170,413,414,416,418,420,422],{"class":172,"line":194},[170,415,197],{"class":180},[170,417,201],{"class":200},[170,419,204],{"class":180},[170,421,207],{"class":200},[170,423,191],{"class":190},[170,425,426,428,430,432,434],{"class":172,"line":212},[170,427,197],{"class":180},[170,429,201],{"class":200},[170,431,219],{"class":180},[170,433,207],{"class":200},[170,435,191],{"class":190},[170,437,438,440,442],{"class":172,"line":226},[170,439,229],{"class":180},[170,441,232],{"class":200},[170,443,235],{"class":180},[170,445,446],{"class":172,"line":238},[170,447,448],{"class":180},"    \"planId\": \"plan_pro\",\n",[170,450,451],{"class":172,"line":244},[170,452,453],{"class":180},"    \"billableMetricId\": \"bm_api_calls\",\n",[170,455,456],{"class":172,"line":250},[170,457,458],{"class":180},"    \"chargeModel\": \"GRADUATED\",\n",[170,460,461],{"class":172,"line":256},[170,462,463],{"class":180},"    \"invoiceDisplayName\": \"API calls\",\n",[170,465,467],{"class":172,"line":466},9,[170,468,469],{"class":180},"    \"graduatedRanges\": [\n",[170,471,473],{"class":172,"line":472},10,[170,474,475],{"class":180},"      { \"fromValue\": 0, \"toValue\": 10000, \"perUnitAmount\": 0 },\n",[170,477,479],{"class":172,"line":478},11,[170,480,481],{"class":180},"      { \"fromValue\": 10001, \"perUnitAmount\": 0.002 }\n",[170,483,485],{"class":172,"line":484},12,[170,486,487],{"class":180},"    ]\n",[170,489,491,493],{"class":172,"line":490},13,[170,492,259],{"class":180},[170,494,262],{"class":200},[273,496,497,507],{},[276,498,499],{},[279,500,501,504],{},[282,502,503],{},"Model",[282,505,506],{},"How it prices the quantity",[295,508,509,522,532,542,555],{},[279,510,511,516],{},[300,512,513],{},[167,514,515],{},"STANDARD",[300,517,518,519],{},"One price per unit: ",[167,520,521],{},"properties: { \"amount\": \"0.10\", \"currency\": \"USD\" }",[279,523,524,529],{},[300,525,526],{},[167,527,528],{},"GRADUATED",[300,530,531],{},"Each range priced on its own (first 10,000 free, the rest at 0.002)",[279,533,534,539],{},[300,535,536],{},[167,537,538],{},"VOLUME",[300,540,541],{},"The whole quantity at the price of the range it lands in",[279,543,544,549],{},[300,545,546],{},[167,547,548],{},"PACKAGE",[300,550,551,552],{},"Per block of units: ",[167,553,554],{},"properties: { \"amount\": \"5\", \"packageSize\": 1000, \"currency\": \"USD\" }",[279,556,557,562],{},[300,558,559],{},[167,560,561],{},"PERCENTAGE",[300,563,564],{},"A share of a value in the events, with optional fixed amounts and free units",[138,566,567,570,571,574,575,578,579,582,583,586],{},[167,568,569],{},"billingTiming"," is ",[167,572,573],{},"IN_ARREARS"," (bill what was used, at the end of the period; the default) or ",[167,576,577],{},"IN_ADVANCE",". A range's ",[167,580,581],{},"flatAmount"," adds a fixed fee for entering it, and ",[167,584,585],{},"minAmountCents"," sets a floor for the charge.",[155,588,590],{"id":589},"_3-send-usage-events","3. Send usage events",[160,592,594],{"className":162,"code":593,"language":164,"meta":165,"style":165},"curl -X POST https:\u002F\u002Fapi.pimabill.com\u002Fapi\u002Fevents \\\n  -H \"Authorization: Bearer sk_live_a1b2c3d4...\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"transactionId\": \"req_8f2c91\",\n    \"subscriptionId\": \"sub_abc123\",\n    \"code\": \"api_calls\",\n    \"timestamp\": \"2026-10-25T12:00:00Z\",\n    \"properties\": { \"region\": \"kampala\" }\n  }'\n",[167,595,596,609,621,633,641,646,651,655,660,665],{"__ignoreMap":165},[170,597,598,600,602,604,607],{"class":172,"line":173},[170,599,177],{"class":176},[170,601,181],{"class":180},[170,603,184],{"class":180},[170,605,606],{"class":180}," https:\u002F\u002Fapi.pimabill.com\u002Fapi\u002Fevents",[170,608,191],{"class":190},[170,610,611,613,615,617,619],{"class":172,"line":194},[170,612,197],{"class":180},[170,614,201],{"class":200},[170,616,204],{"class":180},[170,618,207],{"class":200},[170,620,191],{"class":190},[170,622,623,625,627,629,631],{"class":172,"line":212},[170,624,197],{"class":180},[170,626,201],{"class":200},[170,628,219],{"class":180},[170,630,207],{"class":200},[170,632,191],{"class":190},[170,634,635,637,639],{"class":172,"line":226},[170,636,229],{"class":180},[170,638,232],{"class":200},[170,640,235],{"class":180},[170,642,643],{"class":172,"line":238},[170,644,645],{"class":180},"    \"transactionId\": \"req_8f2c91\",\n",[170,647,648],{"class":172,"line":244},[170,649,650],{"class":180},"    \"subscriptionId\": \"sub_abc123\",\n",[170,652,653],{"class":172,"line":250},[170,654,247],{"class":180},[170,656,657],{"class":172,"line":256},[170,658,659],{"class":180},"    \"timestamp\": \"2026-10-25T12:00:00Z\",\n",[170,661,662],{"class":172,"line":466},[170,663,664],{"class":180},"    \"properties\": { \"region\": \"kampala\" }\n",[170,666,667,669],{"class":172,"line":472},[170,668,259],{"class":180},[170,670,262],{"class":200},[672,673,674,684,690,696],"ul",{},[675,676,677,683],"li",{},[142,678,679,682],{},[167,680,681],{},"transactionId"," makes events safe to retry",": an event with a transaction ID already seen is ignored, so send the same ID again after a timeout.",[675,685,686,689],{},[167,687,688],{},"subscriptionId"," takes the subscription's ID or your own external subscription ID.",[675,691,692,695],{},[167,693,694],{},"timestamp"," defaults to now; events are counted in the billing period they fall in.",[675,697,698,699,702,703,386],{},"Send up to 100 at a time with ",[167,700,701],{},"POST \u002Fapi\u002Fevents\u002Fbatch"," and ",[167,704,705],{},"{ \"events\": [ ... ] }",[138,707,708,711],{},[167,709,710],{},"GET \u002Fapi\u002Fevents\u002Fsubscription\u002F{subscriptionId}"," lists what a subscription has reported, which helps when a customer asks about a bill.",[155,713,715],{"id":714},"per-customer-prices","Per-customer prices",[138,717,718,719,722],{},"To give one customer different usage prices without a new plan, use plan overrides (",[167,720,721],{},"\u002Fapi\u002Fplan-overrides","): they replace a plan's prices for a single customer.",[724,725,726],"style",{},"html pre.shiki code .sBMFI, html code.shiki .sBMFI{--shiki-light:#E2931D;--shiki-default:#FFCB6B;--shiki-dark:#FFCB6B}html pre.shiki code .sfazB, html code.shiki .sfazB{--shiki-light:#91B859;--shiki-default:#C3E88D;--shiki-dark:#C3E88D}html pre.shiki code .sTEyZ, html code.shiki .sTEyZ{--shiki-light:#90A4AE;--shiki-default:#EEFFFF;--shiki-dark:#BABED8}html pre.shiki code .sMK4o, html code.shiki .sMK4o{--shiki-light:#39ADB5;--shiki-default:#89DDFF;--shiki-dark:#89DDFF}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":165,"searchDepth":194,"depth":194,"links":728},[729,730,731,732],{"id":157,"depth":194,"text":158},{"id":389,"depth":194,"text":390},{"id":589,"depth":194,"text":590},{"id":714,"depth":194,"text":715},"Meter what customers use, price it on their plan, and bill it automatically.","md",null,{},true,{"title":57,"description":733},"hV_LvVDCK0XKdht3NyO4WYW9gOXLkwsVi5O71Zj8tRI",[741,743],{"title":53,"path":54,"stem":55,"description":742,"children":-1},"Learn how to create, manage, and query customers in PimaBill.",{"title":61,"path":62,"stem":63,"description":744,"children":-1},"Prepaid credit that customers buy or you grant, used automatically on their invoices.",1793401244902]