---
title: "Create billing plan credit grant"
method: POST
path: "/billing/credits/plan-grants"
tags: ["credits"]
---

# Create billing plan credit grant

`POST /billing/credits/plan-grants`

## Request body

- CreateBillingPlanCreditGrantRequestBody
  - `apply_to_existing` boolean, nullable
  - `auto_topup_amount` integer, nullable
  - `auto_topup_amount_type` 'credit'
  - `auto_topup_availability` 'off' | 'automatic' | 'user_controlled'
  - `auto_topup_enabled` boolean, nullable
  - `auto_topup_expiry_type` 'duration' | 'end_of_billing_period' | 'end_of_next_billing_period' | 'end_of_trial' | 'no_expiry'
  - `auto_topup_expiry_unit` 'billing_periods' | 'days'
  - `auto_topup_expiry_unit_count` integer, nullable
  - `auto_topup_self_service` boolean, nullable
  - `auto_topup_threshold_credits` integer, nullable
  - `auto_topup_threshold_percent` integer, nullable
  - `can_buy_bundles` boolean, nullable
  - `credit_amount` integer, required
  - `credit_id` string, required
  - `expiry_type` 'duration' | 'end_of_billing_period' | 'end_of_next_billing_period' | 'end_of_trial' | 'no_expiry'
  - `expiry_unit` 'billing_periods' | 'days'
  - `expiry_unit_count` integer, nullable
  - `license_id` string, nullable — The license whose quantity scales this grant. Required when scaling is per_license.
  - `plan_id` string, required
  - `plan_version_id` string, nullable
  - `reset_cadence` 'daily' | 'every_6_months' | 'monthly' | 'quarterly' | 'weekly' | 'yearly', required
  - `reset_start` 'billing_period' | 'first_of_month', required
  - `reset_type` 'no_reset' | 'plan_period'
  - `rollover_percentage` integer, nullable — Percentage of unused credits that carry over when this grant resets. Only applies when reset_type is plan_period. Rolled-over credits expire at the next reset and are not rolled again. Defaults to 0.
  - `scaling` 'fixed' | 'per_license'

## Response `201`

Created

- object
  - `data` BillingPlanCreditGrantResponseData, required
    - `auto_topup_amount` integer, nullable
    - `auto_topup_amount_type` string, nullable
    - `auto_topup_availability` 'off' | 'automatic' | 'user_controlled', required
    - `auto_topup_enabled` boolean, required — Derived from auto_topup_availability; use that instead.
    - `auto_topup_expiry_type` 'duration' | 'end_of_billing_period' | 'end_of_next_billing_period' | 'end_of_trial' | 'no_expiry'
    - `auto_topup_expiry_unit` 'billing_periods' | 'days'
    - `auto_topup_expiry_unit_count` integer, nullable
    - `auto_topup_self_service` boolean, required — Derived from auto_topup_availability; use that instead.
    - `auto_topup_threshold_credits` integer, nullable
    - `auto_topup_threshold_percent` integer, nullable
    - `can_buy_bundles` boolean, required — Whether buyers can purchase one-time credit bundles on this grant, independent of auto top-up availability.
    - `created_at` string, date-time, required
    - `credit` BillingCreditResponseData
      - `burn_strategy` 'expiration_priority' | 'first_in_first_out' | 'last_in_first_out' | 'plan_first_then_credit_bundles_first_in_first_out', required
      - `cost_editable` boolean, required
      - `created_at` string, date-time, required
      - `currency_prices` CreditCurrencyPriceResponseData[], required
        - `currency` string, required
        - `price` BillingPriceResponseData
          - `currency` string, required
          - `external_price_id` string, required
          - `id` string, required
          - `interval` 'day' | 'month' | 'one-time' | 'year', required
          - `interval_count` integer, required
          - `nickname` string, nullable
          - `price` integer, required
          - `price_decimal` string, nullable
          - `provider_type` 'metronome' | 'orb' | 'schematic' | 'stripe', required
          - `scheme` 'per_unit' | 'tiered', required
      - `default_expiry_unit` 'billing_periods' | 'days', required
      - `default_expiry_unit_count` integer, nullable
      - `default_rollover_policy` 'expire' | 'none' | 'rollover', required
      - `description` string, required
      - `icon` string, nullable
      - `id` string, required
      - `name` string, required
      - `plural_name` string, nullable
      - `price` BillingPriceResponseData
        - `currency` string, required
        - `external_price_id` string, required
        - `id` string, required
        - `interval` 'day' | 'month' | 'one-time' | 'year', required
        - `interval_count` integer, required
        - `nickname` string, nullable
        - `price` integer, required
        - `price_decimal` string, nullable
        - `provider_type` 'metronome' | 'orb' | 'schematic' | 'stripe', required
        - `scheme` 'per_unit' | 'tiered', required
      - `product` BillingProductResponseData
        - `account_id` string, required
        - `created_at` string, date-time, required
        - `currency` string, nullable — Deprecated; currencies are associated with prices, not products
        - `environment_id` string, required
        - `external_id` string, required
        - `is_active` boolean, required
        - `name` string, required
        - `price` number, double, required
        - `price_decimal` string, nullable
        - `product_id` string, required
        - `provider_type` 'metronome' | 'orb' | 'schematic' | 'stripe', required
        - `quantity` number, double, required
        - `updated_at` string, date-time, required
      - `singular_name` string, nullable
      - `updated_at` string, date-time, required
    - `credit_amount` integer, required
    - `credit_id` string, required
    - `credit_name` string, required — Use credit.name from the nested credit object instead
    - `credit_plural_name` string, nullable — Use plural_name from the nested credit object instead
    - `credit_singular_name` string, nullable — Use singular_name from the nested credit object instead
    - `expiry_type` 'duration' | 'end_of_billing_period' | 'end_of_next_billing_period' | 'end_of_trial' | 'no_expiry'
    - `expiry_unit` 'billing_periods' | 'days'
    - `expiry_unit_count` integer, nullable
    - `id` string, required
    - `license_id` string, nullable — The license whose quantity scales this grant. Set only when scaling is per_license.
    - `plan` PreviewObjectResponseData
      - `description` string, nullable
      - `id` string, required
      - `image_url` string, nullable
      - `name` string, required
    - `plan_id` string, required
    - `plan_name` string, required — Use plan.name from the nested plan object instead
    - `plan_version_id` string, nullable
    - `reset_cadence` 'daily' | 'every_6_months' | 'monthly' | 'quarterly' | 'weekly' | 'yearly'
    - `reset_start` 'billing_period' | 'first_of_month'
    - `reset_type` 'no_reset' | 'plan_period'
    - `rollover_percentage` integer, required — Percentage of unused credits that carry over when this grant resets. Only meaningful when reset_type is plan_period.
    - `scaling` 'fixed' | 'per_license', required
    - `updated_at` string, date-time, required
  - `params` object, required — Input parameters

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `500` — Server error

---

[API](https://skmtc.net/schematichq/apis/schematic-api.md) · [All operations](https://skmtc.net/schematichq/apis/schematic-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/schematichq/schematic-api/versions/873fb318b08a/schema)