# Create a credit grant

Creates a credit grant.

## Prerequisites

Before you can run the following code snippet, you need to call these APIs with the provided parameters to set up the prerequisite API object(s).

1. createCustomer
POST /v1/customers {"name":"Jenny Rosen","email":"jennyrosen@example.com"}

## Request

```curl
curl https://api.stripe.com/v1/billing/credit_grants \
  -u "<<YOUR_SECRET_KEY>>" \
  -d "name=Purchased Credits" \
  -d customer={{CUSTOMER_ID}} \
  -d "amount[monetary][currency]=usd" \
  -d "amount[monetary][value]=1000" \
  -d "amount[type]=monetary" \
  -d "applicability_config[scope][price_type]=metered" \
  -d category=paid
```

### Response

```json
{
  "id": "credgr_test_61R9a6NUWsRmOW3RM41L6nFOS1ekDGHo",
  "object": "billing.credit_grant",
  "amount": {
    "monetary": {
      "currency": "usd",
      "value": 1000
    },
    "type": "monetary"
  },
  "applicability_config": {
    "scope": {
      "price_type": "metered"
    }
  },
  "category": "paid",
  "created": 1726620803,
  "customer": "cus_QrvQguzkIK8zTj",
  "effective_at": 1729297860,
  "expires_at": null,
  "livemode": false,
  "metadata": {},
  "name": "Purchased Credits",
  "priority": 50,
  "test_clock": null,
  "updated": 1726620803
}
```

## Returns

Returns a credit grant.

## Parameters

- [`amount`](https://docs.stripe.com/api/billing/credit-grant/create.md?query=amount) (object, required)
  Amount of this credit grant.

- [`applicability_config`](https://docs.stripe.com/api/billing/credit-grant/create.md?query=applicability_config) (object, required)
  Configuration specifying what this credit grant applies to. We currently only support `metered` prices that have a [Billing Meter](https://docs.stripe.com/api/billing/meter.md) attached to them.

- `category` (enum, optional)
  The category of this credit grant. It defaults to `paid` if not specified.
Possible enum values:
  - `paid`
    The credit grant was purchased by the customer for some amount.

  - `promotional`
    The credit grant was given to the customer for free.

- `customer` (string, optional)
  ID of the customer receiving the billing credits.

- `customer_account` (string, optional)
  ID of the account representing the customer receiving the billing credits.

- `effective_at` (timestamp, optional)
  The time when the billing credits become effective-when they’re eligible for use. It defaults to the current timestamp if not specified.

- `expires_at` (timestamp, optional)
  The time when the billing credits expire. If not specified, the billing credits don’t expire.

- `metadata` (map, optional)
  Set of key-value pairs that you can attach to an object. You can use this to store additional information about the object (for example, cost basis) in a structured format.

- `name` (string, optional)
  A descriptive name shown in the Dashboard.

  The maximum length is 100 characters.

- `priority` (integer, optional)
  The desired priority for applying this credit grant. If not specified, it will be set to the default value of 50. The highest priority is 0 and the lowest is 100.