> ## Documentation Index > Fetch the complete documentation index at: https://docs.meteroid.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a credit grant > Grants credit without charging or invoicing: PROMOTIONAL credit for free, or PAID credit the customer paid for outside Meteroid ("Paid outside Meteroid"). A PAID currency grant whose `cost` is below its `amount` is split into a PAID grant for the cost and a PROMOTIONAL bonus grant for the rest, returned as `bonus_grant_id`; a `cost` above the `amount` is refused. For a customer of a French invoicing entity, PAID credit that cost more than zero needs a `reference` to the invoice or receipt of its payment. Sell credit through Meteroid with a top-up. ## OpenAPI ````yaml https://api.meteroid.com/api-docs/openapi.json post /api/v1/customers/{id_or_alias}/credit-grants openapi: 3.1.0 info: title: meteroid description: '' license: name: LicenseRef-Proprietary identifier: LicenseRef-Proprietary version: 0.1.0 servers: [] security: [] tags: - name: Meteroid description: Meteroid API - name: Add-ons - name: Batch Jobs - name: Budgets description: >- Beta: may change before general availability. Spending limits on a customer's usage, or one subscription's, per currency, with alerts at percentages of the amount. x-beta: true - name: Checkout Sessions - name: Checks description: >- Beta: may change before general availability. Whether a customer may consume more of a feature right now. x-beta: true - name: Connect description: Manage connected accounts (Express & Standard) - name: Coupons - name: Credit Notes - name: Credit units description: >- Custom denominations, such as "credits", that usage can be priced in and credit granted or sold in, instead of money. - name: Credits description: >- Prepaid credit: a customer's wallets, credit grants, ledger and top-ups. Promotional credit applies before tax like a discount; paid credit applies after tax like a payment. - name: Custom Properties - name: Customers - name: Entitlements - name: Events - name: Features - name: Invoices - name: Licenses description: >- Licenses for your customers' self-hosted installations: signed tokens carrying their plan's entitlements, activated and refreshed by the installation over the public licensing endpoints. - name: Metrics - name: OAuth description: OAuth 2.0 token endpoints (public, client-credentials auth) - name: OAuth Apps description: Manage OAuth applications for Connect integrations - name: Plans - name: Product Families - name: Products - name: Subscriptions - name: Usage - name: Usage costs description: >- Beta: may change before general availability. A customer's or a subscription's usage events and usage over time, with what they cost. x-beta: true - name: Webhook Endpoints description: Manage outbound webhook endpoints and inspect their deliveries paths: /api/v1/customers/{id_or_alias}/credit-grants: post: tags: - Credits summary: Create a credit grant description: >- Grants credit without charging or invoicing: PROMOTIONAL credit for free, or PAID credit the customer paid for outside Meteroid ("Paid outside Meteroid"). A PAID currency grant whose `cost` is below its `amount` is split into a PAID grant for the cost and a PROMOTIONAL bonus grant for the rest, returned as `bonus_grant_id`; a `cost` above the `amount` is refused. For a customer of a French invoicing entity, PAID credit that cost more than zero needs a `reference` to the invoice or receipt of its payment. Sell credit through Meteroid with a top-up. operationId: create_credit_grant parameters: - name: id_or_alias in: path description: Customer ID or alias required: true schema: type: string - name: Idempotency-Key in: header description: Required; reuse it only to retry the same request required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateCreditGrantRequest' required: true responses: '201': description: Credit granted content: application/json: schema: $ref: '#/components/schemas/CreditGrant' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '404': description: Customer not found content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '409': description: Idempotency-Key reused with another request content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '429': description: Too many requests content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' security: - bearer_auth: [] components: schemas: CreateCreditGrantRequest: type: object description: Credit granted without charging or invoicing. required: - amount - type properties: amount: type: integer format: int64 description: >- Credit granted, in minor units of `currency`, or of `credit_unit` when set (e.g. 500000 is 5,000.00 credits of a unit with precision 2). Positive. applicable_product_ids: type: - array - 'null' items: $ref: '#/components/schemas/ProductId' description: >- Restricts the credit to charges of these products; absent applies to every product. Combined with `applies_to`. Not available for credit units. applies_to: $ref: '#/components/schemas/CreditAppliesTo' description: ALL pays any charge on an invoice; USAGE only usage charges. cost: oneOf: - $ref: '#/components/schemas/CreditCostRequest' description: >- What the customer paid for the credit, net of tax. Required for PAID credit in a credit unit; defaults to zero for PROMOTIONAL credit and to `amount` for PAID currency credit. PAID currency credit cannot cost more than `amount`. When it costs less, the cost is granted as PAID credit and the rest as a separate PROMOTIONAL bonus grant with the same expiry, which applies before tax; PAID credit that cost nothing is granted as PROMOTIONAL. - type: 'null' credit_unit: type: - string - 'null' description: >- Grants in this credit unit (its code) instead of a currency; excludes `currency`. Credit in a credit unit pays the usage priced in that unit, so `applies_to` must stay ALL. currency: oneOf: - $ref: '#/components/schemas/Currency' description: Defaults to the customer's currency. - type: 'null' expires_at: type: - string - 'null' format: date-time description: When unspent credit lapses; absent never expires. priority: type: - integer - 'null' format: int32 description: >- Lower values are drawn first among grants of the same type that pay the same charges; defaults to 100. reason: type: - string - 'null' description: Shown on the credit ledger. reference: type: - string - 'null' description: >- Your own reference, e.g. a contract or support ticket. Required for PAID credit that cost more than zero when the customer's invoicing entity is in France: the number of the invoice or receipt for the payment, as French law requires a supporting document for every accounting entry. Refused with 400 when missing. subscription_id: type: - string - 'null' description: >- The customer's subscription (`sub_…`) the credit belongs to: it pays only that subscription's charges and lapses when the subscription ends. It must not have ended, and its currency must be the grant's. Absent pays any of the customer's subscriptions. type: $ref: '#/components/schemas/CreditGrantType' description: >- PROMOTIONAL gives credit for free (a goodwill or marketing grant). PAID records credit the customer paid for outside of Meteroid: nothing is charged or invoiced, and the grant is shown as "Paid outside Meteroid". Usage paid with PAID currency credit is taxed on the invoice that bills it, so do not charge tax on the external sale of currency credit, or the customer is taxed twice. Credit in a credit unit is the exception: its usage is billed in credits, untaxed, so tax its sale as you would any other. Use a top-up to sell credit through Meteroid. additionalProperties: false CreditGrant: type: object description: >- A lot of credit given to or bought by a customer. An invoice applies promotional currency credit before tax and paid credit after it. Within each, it draws the grants that belong to the invoiced subscription first, then grants restricted to products (the fewest products first), then usage-only grants, then the others; then by lowest `priority`, then the soonest to lapse. required: - id - type - status - source - applies_to - applicable_product_ids - kind - kind_label - amount - remaining - priority - effective_at - reason - created_at properties: amount: type: integer format: int64 description: Amount granted, in minor units of `currency` or `credit_unit`. applicable_product_ids: type: array items: $ref: '#/components/schemas/ProductId' description: >- The products whose charges the credit pays, combined with `applies_to`; empty when it applies to every product. applies_to: $ref: '#/components/schemas/CreditAppliesTo' description: ALL pays any charge on an invoice; USAGE only usage charges. bonus_grant_id: type: - string - 'null' description: >- Only on the response that created a PAID currency grant whose `cost` was below its amount: the PROMOTIONAL "Bonus credit" grant created beside it for the difference, with the same expiry, scope and priority. cost: oneOf: - $ref: '#/components/schemas/CreditCost' description: >- What the whole grant was paid, net of tax: zero for promotional or included credit. A PAID grant created through the API without an invoice ("Paid outside Meteroid") carries the cost it was given. Absent for credit granted before costs were recorded. - type: 'null' cost_basis: type: - string - 'null' description: >- `cost` per one major unit of credit, in major units of the cost currency (e.g. "0.008"), rounded to 12 decimal places, for display only. created_at: type: string format: date-time description: When the grant was recorded. credit_note_id: type: - string - 'null' description: The credit note that gave the credit back. credit_unit: type: - string - 'null' description: >- The credit unit (its code) the amounts are in; absent for a currency. credit_unit_precision: type: - integer - 'null' format: int32 description: >- Decimal places of `credit_unit`: amounts are integers of 10^-precision credit. minimum: 0 currency: oneOf: - $ref: '#/components/schemas/Currency' description: Absent when the grant is in a credit unit. - type: 'null' effective_at: type: string format: date-time description: When the credit became spendable. ended_at: type: - string - 'null' format: date-time description: >- When the subscription the grant belongs to ended, if it ended. Unspent credit lapses then (status EXPIRED), even before `expires_at`. expired_amount: type: - integer - 'null' format: int64 description: Lost to expiry; present only on an expired grant. expires_at: type: - string - 'null' format: date-time description: When unspent credit lapses; absent never expires. id: type: string description: The grant's id (`cgr_…`). invoice_id: type: - string - 'null' description: >- The invoice that sold the credit, or whose void or negative total gave it back. kind: $ref: '#/components/schemas/CreditGrantKind' description: >- The group the grant is shown in: INCLUDED, PREPAID, BONUS or ACCOUNT_BALANCE. kind_label: type: string description: >- The group's name as Meteroid shows it: "Included with ", "Purchased credit", "Free credit" or "Account balance". priority: type: integer format: int32 description: >- Lower values are drawn first among grants of the same type that pay the same charges; 100 by default. reason: type: string description: Shown on the credit ledger. reference: type: - string - 'null' description: Your own reference, e.g. a contract or support ticket. remaining: type: integer format: int64 description: Not spent yet, in the same minor units. source: $ref: '#/components/schemas/CreditGrantSource' description: Where the credit came from. status: $ref: '#/components/schemas/CreditGrantStatus' description: >- PENDING until `effective_at`, then ACTIVE, DEPLETED once spent, or EXPIRED. subscription_id: type: - string - 'null' description: >- The subscription the grant belongs to (`sub_…`): it pays only that subscription's charges, and lapses when the subscription ends. Null when it pays any of the customer's subscriptions. type: $ref: '#/components/schemas/CreditGrantType' description: 'PAID or PROMOTIONAL: whether it applies after or before tax.' RestErrorResponse: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string ProductId: type: string format: MeteroidId examples: - prd_7n42DGM5Tflk9n8mt7Fhc7 CreditAppliesTo: type: string description: >- Which charges credit pays: ALL pays any part of an invoice, USAGE only its usage charges. enum: - ALL - USAGE CreditCostRequest: type: object description: Money in minor units of `currency`, net of tax. required: - amount - currency properties: amount: type: integer format: int64 description: In minor units of `currency`; zero or positive. currency: $ref: '#/components/schemas/Currency' additionalProperties: false Currency: type: string enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BRL - BSD - BTN - BWP - BYN - BZD - CAD - CDF - CHF - CLP - CNH - CNY - COP - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRU - MUR - MVR - MWK - MXN - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - UYU - UZS - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL examples: - EUR CreditGrantType: type: string description: >- PAID credit was bought, through Meteroid or outside it, and applies after tax like a payment. PROMOTIONAL credit was given (included with a plan, a coupon, bonus credit, a goodwill grant): it applies before tax, like a discount, so it is spent before paid credit. Credit-unit grants are drawn together, whatever their type. enum: - PAID - PROMOTIONAL CreditCost: type: object description: Money in minor units of `currency`, net of tax. required: - amount - currency properties: amount: type: integer format: int64 description: In minor units of `currency`. currency: $ref: '#/components/schemas/Currency' CreditGrantKind: type: string description: >- The group a grant is shown in, from where it came from and what it pays: - INCLUDED: credit a subscription's plan includes, which renews with it; - PREPAID: credit bought (purchases, top-ups, paid packs, credit paid for outside Meteroid); - BONUS: credit given (the bonus part of discounted credit, promo codes, welcome credit); - ACCOUNT_BALANCE: the customer's money that pays any invoice (credit notes, returned invoices, the balance carried from before credit grants, credit added for any charge). enum: - INCLUDED - PREPAID - BONUS - ACCOUNT_BALANCE CreditGrantSource: type: string enum: - MANUAL - PURCHASE - PLAN - CREDIT_NOTE - ADJUSTMENT - MIGRATED - ROLLOVER - COUPON - OVERPAYMENT CreditGrantStatus: type: string enum: - PENDING - ACTIVE - DEPLETED - EXPIRED ErrorCode: type: string enum: - BAD_REQUEST - NOT_FOUND - CONFLICT - FORBIDDEN - UNAUTHORIZED - TOKEN_EXPIRED - TOO_MANY_REQUESTS - INTERNAL_SERVER_ERROR securitySchemes: bearer_auth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.