> ## 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. # List credit grants > A customer's credit grants, newest first, in every currency and credit unit unless filtered. ## OpenAPI ````yaml https://api.meteroid.com/api-docs/openapi.json get /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: get: tags: - Credits summary: List credit grants description: >- A customer's credit grants, newest first, in every currency and credit unit unless filtered. operationId: list_credit_grants parameters: - name: id_or_alias in: path description: Customer ID or alias required: true schema: type: string - name: currency in: query description: Only grants in this currency. required: false schema: $ref: '#/components/schemas/Currency' - name: credit_unit in: query description: Only grants in this credit unit (its code); excludes `currency`. required: false schema: type: string - name: status in: query required: false schema: type: string enum: - PENDING - ACTIVE - DEPLETED - EXPIRED - name: subscription_id in: query description: |- Only the grants that belong to this subscription (`sub_…`); excludes `usable_by_subscription_id`. required: false schema: type: string - name: usable_by_subscription_id in: query description: >- Only the credit this subscription (`sub_…`) can use: its own grants and the customer's grants that belong to no subscription. Excludes `subscription_id`. required: false schema: type: string - name: page in: query description: Page number (0-indexed) required: false schema: type: integer format: int32 minimum: 0 - name: per_page in: query description: Number of items per page required: false schema: type: integer format: int32 maximum: 100 minimum: 1 responses: '200': description: Credit grants, newest first content: application/json: schema: $ref: '#/components/schemas/CreditGrantListResponse' '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' '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: 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 CreditGrantListResponse: type: object description: A page of credit grants. required: - data - pagination_meta properties: data: type: array items: $ref: '#/components/schemas/CreditGrant' pagination_meta: $ref: '#/components/schemas/PaginationResponse' RestErrorResponse: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string 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.' PaginationResponse: type: object required: - page - per_page - total_items - total_pages properties: page: type: integer format: int32 minimum: 0 per_page: type: integer format: int32 minimum: 0 total_items: type: integer format: int64 minimum: 0 total_pages: type: integer format: int32 minimum: 0 ErrorCode: type: string enum: - BAD_REQUEST - NOT_FOUND - CONFLICT - FORBIDDEN - UNAUTHORIZED - TOKEN_EXPIRED - TOO_MANY_REQUESTS - INTERNAL_SERVER_ERROR 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 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 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 securitySchemes: bearer_auth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.