Skip to main content
POST
/
api
/
v1
/
credits
/
grants
Create a credit grant
curl --request POST \
  --url https://api.example.com/api/v1/credits/grants \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "displayName": "<string>",
  "amount": 123,
  "grantType": "PAID",
  "customerId": "<string>",
  "currencyId": "<string>",
  "priority": 50,
  "effectiveAt": "2023-11-07T05:31:56Z",
  "expireAt": "2023-11-07T05:31:56Z",
  "metadata": {},
  "cost": {
    "amount": 123,
    "currency": "usd"
  },
  "comment": "<string>",
  "resourceId": "<string>",
  "paymentCollectionMethod": "CHARGE",
  "awaitPaymentConfirmation": true,
  "billingInformation": {
    "isInvoicePaid": true,
    "invoiceDaysUntilDue": 123,
    "billingAddress": {
      "city": "<string>",
      "country": "<string>",
      "line1": "<string>",
      "line2": "<string>",
      "postalCode": "<string>",
      "state": "<string>"
    }
  }
}
'
{
  "data": {
    "id": "cred-grant-abc123",
    "displayName": "Monthly credits",
    "amount": 1000,
    "consumedAmount": 250,
    "grantType": "PROMOTIONAL",
    "sourceType": null,
    "priority": 1,
    "effectiveAt": "2024-01-01T00:00:00.000Z",
    "expireAt": "2024-12-31T23:59:59.000Z",
    "voidedAt": null,
    "metadata": {},
    "cost": {
      "amount": 0,
      "currency": "usd"
    },
    "comment": null,
    "customerId": "customer-123",
    "resourceId": null,
    "currencyId": "credits",
    "invoiceId": null,
    "latestInvoice": null,
    "paymentCollection": "NOT_REQUIRED",
    "status": "ACTIVE",
    "createdAt": "2027-01-13T05:56:18.153Z",
    "updatedAt": "2027-01-13T05:56:18.154Z"
  }
}

Authorizations

​
X-API-KEY
string
header
required

Server API Key

Body

application/json

Request body for creating a credit grant

​
displayName
string
required

The display name for the credit grant

Maximum string length: 255
​
amount
number
required

The credit amount to grant

​
grantType
enum<string>
required

The type of credit grant (PAID, PROMOTIONAL, RECURRING)

Available options:
PAID,
PROMOTIONAL,
RECURRING
​
customerId
string
required

The customer ID to grant credits to (required)

Required string length: 1 - 255
Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$
​
currencyId
string
required

The credit currency ID (required)

Required string length: 1 - 255
Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$
​
priority
integer

The priority of the credit grant (lower number = higher priority)

Required range: 0 <= x <= 100
​
effectiveAt
string<date-time>

The date when the credit grant becomes effective

​
expireAt
string<date-time>

The date when the credit grant expires

​
metadata
object

Additional metadata for the credit grant

​
cost
Money · object

The monetary cost of the credit grant

​
comment
string

An optional comment on the credit grant

Maximum string length: 255
​
resourceId
string

The resource ID to scope the grant to

Required string length: 1 - 255
Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$
​
paymentCollectionMethod
enum<string>

The payment collection method (CHARGE, INVOICE, NONE)

Available options:
CHARGE,
INVOICE,
NONE
​
awaitPaymentConfirmation
boolean

Whether to wait for payment confirmation before returning (default: true)

​
billingInformation
CreditGrantBillingInfo · object

Billing information for the credit grant

Response

The newly created credit grant object.

Response object

​
data
CreditGrant · object
required

Credit grant object representing allocated credits for a customer