---
title: "Create a credit grant"
method: POST
path: "/api/v1/credits/grants"
tags: ["Credit grants"]
---

# Create a credit grant

`POST /api/v1/credits/grants`

Creates a new credit grant for a customer with specified amount, type, and optional billing configuration.

## Headers

- `X-ACCOUNT-ID` string
- `X-ENVIRONMENT-ID` string

## Request body

- GrantCreditRequestDto — Request body for creating a credit grant
  - `displayName` string, required — The display name for the credit grant
  - `amount` number, required — The credit amount to grant
  - `grantType` 'PAID' | 'PROMOTIONAL', required — The type of credit grant (PAID, PROMOTIONAL)
  - `priority` integer — The priority of the credit grant (lower number = higher priority)
  - `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` object — The monetary cost of the credit grant
    - `amount` number, required — The price amount
    - `currency` 'usd' | 'aed' | 'all' | 'amd' | 'ang' | 'aud' | 'awg' | 'azn' | 'bam' | 'bbd' | 'bdt' | 'bgn' | 'bif' | 'bmd' | 'bnd' | 'bsd' | 'bwp' | 'byn' | 'bzd' | 'brl' | 'cad' | 'cdf' | 'chf' | 'cny' | 'czk' | 'dkk' | 'dop' | 'dzd' | 'egp' | 'etb' | 'eur' | 'fjd' | 'gbp' | 'gel' | 'gip' | 'gmd' | 'gyd' | 'hkd' | 'hrk' | 'htg' | 'idr' | 'ils' | 'inr' | 'isk' | 'jmd' | 'jpy' | 'kes' | 'kgs' | 'khr' | 'kmf' | 'krw' | 'kyd' | 'kzt' | 'lbp' | 'lkr' | 'lrd' | 'lsl' | 'mad' | 'mdl' | 'mga' | 'mkd' | 'mmk' | 'mnt' | 'mop' | 'mro' | 'mvr' | 'mwk' | 'mxn' | 'myr' | 'mzn' | 'nad' | 'ngn' | 'nok' | 'npr' | 'nzd' | 'pgk' | 'php' | 'pkr' | 'pln' | 'qar' | 'ron' | 'rsd' | 'rub' | 'rwf' | 'sar' | 'sbd' | 'scr' | 'sek' | 'sgd' | 'sle' | 'sll' | 'sos' | 'szl' | 'thb' | 'tjs' | 'top' | 'try' | 'ttd' | 'tzs' | 'uah' | 'uzs' | 'vnd' | 'vuv' | 'wst' | 'xaf' | 'xcd' | 'yer' | 'zar' | 'zmw' | 'clp' | 'djf' | 'gnf' | 'ugx' | 'pyg' | 'xof' | 'xpf', required — ISO 4217 currency code
  - `comment` string — An optional comment on the credit grant
  - `customerId` string, required — The customer ID to grant credits to (required)
  - `resourceId` string — The resource ID to scope the grant to
  - `currencyId` string, required — The credit currency ID (required)
  - `paymentCollectionMethod` 'CHARGE' | 'INVOICE' | 'NONE' — The payment collection method (CHARGE, INVOICE, NONE)
  - `awaitPaymentConfirmation` boolean — Whether to wait for payment confirmation before returning (default: true)
  - `billingInformation` object — Billing information for the credit grant
    - `isInvoicePaid` boolean — Whether the invoice is already paid
    - `invoiceDaysUntilDue` number — Days until the invoice is due
    - `billingAddress` object — The billing address
      - `city` string — City name
      - `country` string — Country code or name
      - `line1` string — Street address line 1
      - `line2` string — Street address line 2
      - `postalCode` string — Postal or ZIP code
      - `state` string — State or province

## Response `201`

The newly created credit grant object.

- CreditGrantResponseDto — Response object
  - `data` object, required — Credit grant object representing allocated credits for a customer
    - `id` string, required — The unique readable identifier of the credit grant
    - `displayName` string, required — The display name of the credit grant
    - `amount` number, required — The total credits granted
    - `consumedAmount` number, required — The total credits consumed from this grant
    - `grantType` 'PAID' | 'PROMOTIONAL' | 'RECURRING' | 'OVERDRAFT', required — The type of credit grant (PAID, PROMOTIONAL, RECURRING, OVERDRAFT)
    - `sourceType` 'PRICE' | 'PLAN_ENTITLEMENT' | 'ADDON_ENTITLEMENT', nullable, required — The source type of the grant (PRICE, PLAN_ENTITLEMENT, ADDON_ENTITLEMENT)
    - `priority` number, required — The priority of the credit grant (lower number = higher priority)
    - `effectiveAt` string, date-time, required — The date when the credit grant becomes effective
    - `expireAt` string, date-time, nullable, required — The date when the credit grant expires
    - `voidedAt` string, date-time, nullable, required — The date when the credit grant was voided
    - `metadata` object, required — Metadata associated with the entity
    - `cost` object, required — The monetary cost of the credit grant
      - `amount` number, required — The cost amount
      - `currency` string, required — The currency code
    - `comment` string, nullable, required — An optional comment on the credit grant
    - `customerId` string, required — The customer ID this grant belongs to
    - `resourceId` string, nullable, required — The resource ID this grant is scoped to
    - `currencyId` string, required — The currency identifier for this grant
    - `invoiceId` string, nullable, required — The billing invoice ID associated with this grant
    - `latestInvoice` object, nullable, required — The latest invoice details for this grant
      - `billingId` string, required — The billing provider invoice ID
      - `status` 'OPEN' | 'PAID' | 'CANCELED', required — The invoice status
      - `createdAt` string, date-time, required — The invoice creation date
      - `updatedAt` string, date-time, required — The invoice last update date
      - `dueDate` string, date-time, nullable, required — The invoice due date
      - `requiresAction` boolean, required — Whether the invoice requires user action
      - `billingReason` 'MANUAL' | 'OTHER', nullable, required — The billing reason for the invoice
      - `paymentUrl` string, nullable, required — The payment URL for settling the invoice
      - `errorMessage` string, nullable, required — Error message if payment failed
      - `pdfUrl` string, nullable, required — The PDF URL of the invoice
      - `currency` string, nullable, required — The invoice currency
      - `subTotal` number, nullable, required — The subtotal amount before tax
      - `total` number, nullable, required — The total amount including tax
      - `tax` number, nullable, required — The tax amount
    - `syncStates` object[], nullable, required — The synchronization states of the entity with external systems
      - `vendorIdentifier` 'AUTH0' | 'ZUORA' | 'STRIPE' | 'HUBSPOT' | 'AWS_MARKETPLACE' | 'SNOWFLAKE' | 'SALESFORCE' | 'BIG_QUERY' | 'OPEN_FGA' | 'APP_STORE' | 'RECEIVED' | 'PREQUEL' | 'AIRWALLEX' | 'STRIPE_INVOICING', required — The vendor identifier of integration
      - `status` 'PENDING' | 'ERROR' | 'SUCCESS' | 'NO_SYNC_REQUIRED', required — Status of the integration sync
      - `syncedEntityId` string, nullable, required — Synced entity id
    - `paymentCollection` 'NOT_REQUIRED' | 'PROCESSING' | 'FAILED' | 'ACTION_REQUIRED', required — The payment collection status
    - `status` 'PAYMENT_PENDING' | 'ACTIVE' | 'EXPIRED' | 'VOIDED' | 'SCHEDULED', required — The effective status of the credit grant
    - `createdAt` string, date-time, required — Timestamp of when the record was created
    - `updatedAt` string, date-time, required — Timestamp of when the record was last updated

## Other responses

- `400` — bad request.
- `401` — User is not authenticated.
- `403` — User is not allowed to access this resource.
- `409` — CreditGrant conflict error.
- `429` — Too many requests.

---

[API](https://skmtc.net/stiggio/apis/stigg-api.md) · [All operations](https://skmtc.net/stiggio/apis/stigg-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stiggio/stigg-api/revisions/3e2c8cfcd035/schema)