> ## Documentation Index > Fetch the complete documentation index at: https://docs.salesive.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a usage record > Bill usage on a capped subscription, never past the cap the merchant approved. Requires the WRITE_CHARGES scope. Records usage against a subscription created with a `cappedAmount`. Usage is billed at the end of the period. See [Usage-based charges](https://docs.salesive.com/apps/payments.md#usage-based-charges). ## OpenAPI ````yaml apps-api/specs/billing.json POST /app-billing/subscriptions/{id}/usage openapi: 3.1.0 info: title: 'Salesive Apps API: Billing' version: 1.0.0 description: >- Charge the merchant a store is installed for, once or on a schedule. Every endpoint authenticates with an installed-app access token (prefix `app_`). Creating a charge or subscription never moves money: the store owner approves it in the dashboard first. Salesive keeps 5% of every payment and credits the rest to your payout store's wallet. servers: - url: https://api.salesive.com/api/v1 description: Production security: - AppToken: [] paths: /app-billing/subscriptions/{id}/usage: post: tags: - Subscriptions summary: Create a usage record description: >- Records usage against a subscription that has a `cappedAmount`. Records add up within the period's cap and a record that would pass it is refused with `402` and code `CAP_REACHED` (the response carries `remaining`). Usage is billed at the end of the period, added to the next renewal charge, or as one final charge after the subscription ends. Usage cannot be recorded during a free trial (`409`, `IN_TRIAL`). `idempotencyKey` is required: a retry with the same key returns the record already made with `200`. Requires `WRITE_CHARGES`. Authenticate with `Authorization: Bearer app_`. The store is bound to the token server-side, never send a shop id. operationId: createUsageRecord parameters: - $ref: '#/components/parameters/SubscriptionId' requestBody: required: true content: application/json: schema: type: object required: - description - amount - idempotencyKey properties: description: type: string maxLength: 200 description: What was used, for example `120 SMS sent`. amount: type: number description: In the subscription currency, two decimals at most. idempotencyKey: type: string maxLength: 120 example: description: 120 SMS sent amount: 6 idempotencyKey: sms-2026-11-05 responses: '200': description: A record with this idempotencyKey already exists; it is returned. '201': description: The record, and where the period stands. content: application/json: schema: allOf: - $ref: '#/components/schemas/EnvelopeBase' - type: object properties: data: allOf: - $ref: '#/components/schemas/UsageRecord' - type: object properties: usage: $ref: '#/components/schemas/Usage' '400': description: >- Invalid body, or the subscription has no usage terms (`NOT_USAGE_BASED`). '401': $ref: '#/components/responses/Unauthorized' '402': description: The record would pass the cap (`CAP_REACHED`). '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: >- The subscription is not active (`NOT_ACTIVE`), is in its free trial (`IN_TRIAL`), or a new period just started (`PERIOD_CHANGED`, send it again). components: parameters: SubscriptionId: name: id in: path required: true description: The subscription id. schema: type: string schemas: EnvelopeBase: type: object description: >- Standard Salesive response envelope. The operation-specific payload is carried in `data`. required: - status - success - message properties: status: type: integer description: HTTP status code, echoed in the body. success: type: boolean description: Whether the request succeeded. message: type: string description: Human-readable result message. UsageRecord: type: object properties: id: type: string subscriptionId: type: string description: type: string amount: type: number currency: type: string enum: - USD - NGN periodStart: type: string format: date-time billed: type: boolean description: True once a charge has billed it. chargeId: type: - string - 'null' description: The charge that billed it. idempotencyKey: type: string test: type: boolean createdAt: type: string format: date-time Usage: type: object description: >- The usage terms of a capped subscription and where the current period stands. properties: cappedAmount: type: number description: >- The most usage that can be billed in one period, in the subscription currency. The merchant approved it and it can never be passed. terms: type: string description: The usage terms the merchant approved, for example `$0.05 per SMS`. periodStart: type: - string - 'null' format: date-time description: Start of the usage period that records count against now. balance: type: number description: Usage recorded in this period. remaining: type: number description: '`cappedAmount` minus `balance`.' Envelope: allOf: - $ref: '#/components/schemas/EnvelopeBase' - type: object properties: data: description: Operation-specific payload (object, array, or null). responses: Unauthorized: description: Missing or invalid app access token. content: application/json: schema: $ref: '#/components/schemas/Envelope' example: status: 401 success: false message: Authentication required data: null Forbidden: description: The app token is missing the OAuth scope required for this operation. content: application/json: schema: $ref: '#/components/schemas/Envelope' example: status: 403 success: false message: Insufficient scope data: null NotFound: description: >- The resource does not exist or does not belong to the installation's store. content: application/json: schema: $ref: '#/components/schemas/Envelope' example: status: 404 success: false message: Resource not found data: null securitySchemes: AppToken: type: http scheme: bearer description: >- Installed-app access token (prefix app_), issued by the OAuth install flow. The store is bound to the token server-side, never send a shop id. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.