Skip to main content
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

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

FieldTypeDescription
idUUID!Unique identifier for the credit grant
grantIdString!Auto-generated readable identifier
displayNameString!Display name for the grant
grantTypeCreditGrantType!Type of grant (PROMOTIONAL, PAID, etc.)
statusCreditGrantStatus!Current status of the grant

​
Amounts

FieldTypeDescription
amountFloat!Total credits in this grant
consumedAmountFloat!Credits already consumed
costMoney!Fiat cost of this grant (for paid grants)

​
Customer

FieldTypeDescription
customerIdString!Customer who received the grant
resourceIdStringResource this grant is scoped to

​
Currency

FieldTypeDescription
currencyIdString!Custom currency ID for these credits

​
Dates

FieldTypeDescription
effectiveAtDateTime!When credits become available
expireAtDateTimeWhen credits expire
voidedAtDateTimeWhen the grant was voided
createdAtDateTime!When the grant was created
updatedAtDateTime!When the grant was last updated

​
Invoice

FieldTypeDescription
invoiceIdStringAssociated invoice ID
latestInvoiceCreditGrantInvoiceLatest invoice information

​
Payment

FieldTypeDescription
paymentCollectionPaymentCollection!Payment collection status
priorityFloat!Priority for credit consumption order

​
Recharge

FieldTypeDescription
automaticRechargeConfigurationIdUUIDID of automatic recharge config that created this grant

​
Metadata

FieldTypeDescription
commentStringOptional comment/note
additionalMetaDataJSONCustom metadata

​
CreditGrantType Enum

ValueDescription
PROMOTIONALFree promotional credits
PAIDCredits purchased by customer
ROLLOVERCredits rolled over from previous period
SUBSCRIPTIONCredits from subscription

​
CreditGrantStatus Enum

ValueDescription
PENDINGGrant is pending activation
ACTIVEGrant is active and credits available
CONSUMEDAll credits have been consumed
EXPIREDGrant has expired
VOIDEDGrant was voided/cancelled

​
CreditGrantCadence Enum

ValueDescription
BEGINNING_OF_BILLING_PERIODCredits granted at start of billing period
MONTHLYCredits 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"
}

{
  "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"
}
  • Customer - Customer type
  • Price - Price type (for credit-based pricing)