> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CreditGrant

Represents a credit grant in the Stigg system. Credit grants add credits to a customer's balance that can be used to pay for usage-based features.

## Type Definition

```graphql theme={null}
type CreditGrant {
  id: UUID!
  grantId: String!
  displayName: String!
  grantType: CreditGrantType!
  status: CreditGrantStatus!

  # Amounts
  amount: Float!
  consumedAmount: Float!
  cost: Money!

  # Customer
  customerId: String!
  resourceId: String

  # Currency
  currencyId: String!

  # Dates
  effectiveAt: DateTime!
  expireAt: DateTime
  voidedAt: DateTime
  createdAt: DateTime!
  updatedAt: DateTime!

  # Invoice
  invoiceId: String
  latestInvoice: CreditGrantInvoice

  # Payment
  paymentCollection: PaymentCollection!
  priority: Float!

  # Recharge
  automaticRechargeConfigurationId: UUID

  # Metadata
  comment: String
  additionalMetaData: JSON
}
```

## Fields

### Core Fields

| Field         | Type                                                                              | Description                             |
| ------------- | --------------------------------------------------------------------------------- | --------------------------------------- |
| `id`          | `UUID!`                                                                           | Unique identifier for the credit grant  |
| `grantId`     | `String!`                                                                         | Auto-generated readable identifier      |
| `displayName` | `String!`                                                                         | Display name for the grant              |
| `grantType`   | [`CreditGrantType!`](/api-and-sdks/api-reference/types/enums#creditgranttype)     | Type of grant (PROMOTIONAL, PAID, etc.) |
| `status`      | [`CreditGrantStatus!`](/api-and-sdks/api-reference/types/enums#creditgrantstatus) | Current status of the grant             |

### Amounts

| Field            | Type     | Description                               |
| ---------------- | -------- | ----------------------------------------- |
| `amount`         | `Float!` | Total credits in this grant               |
| `consumedAmount` | `Float!` | Credits already consumed                  |
| `cost`           | `Money!` | Fiat cost of this grant (for paid grants) |

### Customer

| Field        | Type      | Description                      |
| ------------ | --------- | -------------------------------- |
| `customerId` | `String!` | Customer who received the grant  |
| `resourceId` | `String`  | Resource this grant is scoped to |

### Currency

| Field        | Type      | Description                          |
| ------------ | --------- | ------------------------------------ |
| `currencyId` | `String!` | Custom currency ID for these credits |

### Dates

| Field         | Type        | Description                     |
| ------------- | ----------- | ------------------------------- |
| `effectiveAt` | `DateTime!` | When credits become available   |
| `expireAt`    | `DateTime`  | When credits expire             |
| `voidedAt`    | `DateTime`  | When the grant was voided       |
| `createdAt`   | `DateTime!` | When the grant was created      |
| `updatedAt`   | `DateTime!` | When the grant was last updated |

### Invoice

| Field           | Type                 | Description                |
| --------------- | -------------------- | -------------------------- |
| `invoiceId`     | `String`             | Associated invoice ID      |
| `latestInvoice` | `CreditGrantInvoice` | Latest invoice information |

### Payment

| Field               | Type                                                                              | Description                           |
| ------------------- | --------------------------------------------------------------------------------- | ------------------------------------- |
| `paymentCollection` | [`PaymentCollection!`](/api-and-sdks/api-reference/types/enums#paymentcollection) | Payment collection status             |
| `priority`          | `Float!`                                                                          | Priority for credit consumption order |

### Recharge

| Field                              | Type   | Description                                             |
| ---------------------------------- | ------ | ------------------------------------------------------- |
| `automaticRechargeConfigurationId` | `UUID` | ID of automatic recharge config that created this grant |

### Metadata

| Field                | Type     | Description           |
| -------------------- | -------- | --------------------- |
| `comment`            | `String` | Optional comment/note |
| `additionalMetaData` | `JSON`   | Custom metadata       |

## CreditGrantType Enum

| Value          | Description                              |
| -------------- | ---------------------------------------- |
| `PROMOTIONAL`  | Free promotional credits                 |
| `PAID`         | Credits purchased by customer            |
| `ROLLOVER`     | Credits rolled over from previous period |
| `SUBSCRIPTION` | Credits from subscription                |

## CreditGrantStatus Enum

| Value      | Description                           |
| ---------- | ------------------------------------- |
| `PENDING`  | Grant is pending activation           |
| `ACTIVE`   | Grant is active and credits available |
| `CONSUMED` | All credits have been consumed        |
| `EXPIRED`  | Grant has expired                     |
| `VOIDED`   | Grant was voided/cancelled            |

## CreditGrantCadence Enum

| Value                         | Description                                |
| ----------------------------- | ------------------------------------------ |
| `BEGINNING_OF_BILLING_PERIOD` | Credits granted at start of billing period |
| `MONTHLY`                     | Credits granted monthly                    |

## Example Response

### Active Credit Grant

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "grantId": "grant-123",
  "displayName": "Welcome Bonus",
  "grantType": "PROMOTIONAL",
  "status": "ACTIVE",
  "amount": 1000,
  "consumedAmount": 350,
  "cost": {
    "amount": 0,
    "currency": "USD"
  },
  "customerId": "customer-123",
  "currencyId": "api-credits",
  "effectiveAt": "2024-01-15T00:00:00Z",
  "expireAt": "2024-12-31T23:59:59Z",
  "priority": 1,
  "paymentCollection": "NOT_REQUIRED",
  "comment": "Welcome bonus for new customers",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-18T14:22:00Z"
}
```

### Paid Credit Grant

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "grantId": "grant-456",
  "displayName": "Credit Top-up",
  "grantType": "PAID",
  "status": "ACTIVE",
  "amount": 5000,
  "consumedAmount": 0,
  "cost": {
    "amount": 50.00,
    "currency": "USD"
  },
  "customerId": "customer-123",
  "currencyId": "api-credits",
  "effectiveAt": "2024-01-20T00:00:00Z",
  "priority": 2,
  "paymentCollection": "PAID",
  "invoiceId": "inv-789",
  "latestInvoice": {
    "status": "PAID",
    "hostedInvoiceUrl": "https://billing.example.com/invoice/789"
  },
  "createdAt": "2024-01-20T09:15:00Z",
  "updatedAt": "2024-01-20T09:15:00Z"
}
```

### Voided Credit Grant

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "grantId": "grant-789",
  "displayName": "Test Grant",
  "grantType": "PROMOTIONAL",
  "status": "VOIDED",
  "amount": 500,
  "consumedAmount": 100,
  "cost": {
    "amount": 0,
    "currency": "USD"
  },
  "customerId": "customer-123",
  "currencyId": "api-credits",
  "effectiveAt": "2024-01-10T00:00:00Z",
  "voidedAt": "2024-01-18T12:00:00Z",
  "priority": 1,
  "paymentCollection": "NOT_REQUIRED",
  "comment": "Voided due to policy change",
  "createdAt": "2024-01-10T10:00:00Z",
  "updatedAt": "2024-01-18T12:00:00Z"
}
```

## Related Types

* [Customer](/api-and-sdks/api-reference/types/customer) - Customer type
* [Price](/api-and-sdks/api-reference/types/price) - Price type (for credit-based pricing)

## Related Operations

* [Create Credit Grant](/api-and-sdks/api-reference/mutations/create-credit-grant) - Grant credits
* [Void Credit Grant](/api-and-sdks/api-reference/mutations/void-credit-grant) - Cancel a grant
* [Credit Balance](/api-and-sdks/api-reference/queries/credit-balance) - Query balance
* [Credit Grants](/api-and-sdks/api-reference/queries/credit-grants) - List grants
* [Credit Ledger](/api-and-sdks/api-reference/queries/credit-ledger) - View transactions