Type Definition
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! | Type of grant (PROMOTIONAL, PAID, etc.) |
status | 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! | 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
{
"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
{
"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
{
"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
Related Operations
- Create Credit Grant - Grant credits
- Void Credit Grant - Cancel a grant
- Credit Balance - Query balance
- Credit Grants - List grants
- Credit Ledger - View transactions