> ## 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. # Create a credit grant > Creates a new credit grant for a customer with specified amount, type, and optional billing configuration. ## OpenAPI ````yaml /openapi/stigg-api.documented.yml post /api/v1/credits/grants openapi: 3.0.0 info: title: Stigg API description: Stigg API documentation version: 8.66.2 contact: {} servers: - url: https://api.stigg.io description: Production security: - ApiKeyAuth: [] tags: - name: Customers description: Operations related to customers - name: Subscriptions description: Operations related to subscriptions - name: Coupons description: Operations related to coupons - name: Bulk Import description: Operations related to import of customers and subscriptions - name: Usage description: Operations related to usage & metering - name: Promotional Entitlements description: Operations related to promotional entitlements - name: Products description: Operations related to products - name: Features description: Operations related to features - name: Addons description: Operations related to addons - name: Plans description: Operations related to plans - name: Credit grants description: Operations related to credit grants - name: Credit ledger description: Operations related to credit ledger - name: Custom currencies description: Operations related to custom currencies paths: /api/v1/credits/grants: post: tags: - Credit grants summary: Create a credit grant description: >- Creates a new credit grant for a customer with specified amount, type, and optional billing configuration. operationId: CreditGrantController_grantCredits parameters: - name: X-ACCOUNT-ID in: header description: >- Account ID — optional when authenticating with a user JWT (Bearer token); falls back to the user's first membership. Ignored for API-key auth. required: false schema: type: string - name: X-ENVIRONMENT-ID in: header description: >- Environment ID — required when authenticating with a user JWT (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is intrinsic to the key). required: false schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GrantCreditRequestDto' responses: '201': description: The newly created credit grant object. content: application/json: schema: $ref: '#/components/schemas/CreditGrantResponseDto' examples: default: value: 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 syncStates: - vendorIdentifier: STRIPE status: PENDING syncedEntityId: null paymentCollection: NOT_REQUIRED status: ACTIVE createdAt: '2025-10-26T10:00:00.000Z' updatedAt: '2025-10-26T10:00:00.000Z' '400': description: bad request. content: application/json: schema: $ref: '#/components/schemas/BadInputErrorResponseDto' '401': description: User is not authenticated. content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedErrorResponseDto' '403': description: User is not allowed to access this resource. content: application/json: schema: $ref: '#/components/schemas/ForbiddenErrorResponseDto' '409': description: CreditGrant conflict error. content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponseDto' '429': description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponseDto' x-codeSamples: - lang: JavaScript source: |- import Stigg from '@stigg/typescript'; const client = new Stigg({ apiKey: process.env['STIGG_API_KEY'], // This is the default and can be omitted }); const creditGrantResponse = await client.v1.credits.grants.create({ amount: 0, currencyId: 'currencyId', customerId: 'customerId', displayName: 'displayName', grantType: 'PAID', }); console.log(creditGrantResponse.data); - lang: Python source: |- import os from stigg import Stigg client = Stigg( api_key=os.environ.get("STIGG_API_KEY"), # This is the default and can be omitted ) credit_grant_response = client.v1.credits.grants.create( amount=0, currency_id="currencyId", customer_id="customerId", display_name="displayName", grant_type="PAID", ) print(credit_grant_response.data) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/stiggio/stigg-go\"\n\t\"github.com/stiggio/stigg-go/option\"\n)\n\nfunc main() {\n\tclient := stigg.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tcreditGrantResponse, err := client.V1.Credits.Grants.New(context.TODO(), stigg.V1CreditGrantNewParams{\n\t\tAmount: 0,\n\t\tCurrencyID: \"currencyId\",\n\t\tCustomerID: \"customerId\",\n\t\tDisplayName: \"displayName\",\n\t\tGrantType: stigg.V1CreditGrantNewParamsGrantTypePaid,\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", creditGrantResponse.Data)\n}\n" - lang: Java source: |- package io.stigg.example; import io.stigg.client.StiggClient; import io.stigg.client.okhttp.StiggOkHttpClient; import io.stigg.models.v1.credits.grants.CreditGrantResponse; import io.stigg.models.v1.credits.grants.GrantCreateParams; public final class Main { private Main() {} public static void main(String[] args) { StiggClient client = StiggOkHttpClient.fromEnv(); GrantCreateParams params = GrantCreateParams.builder() .amount(0.0) .currencyId("currencyId") .customerId("customerId") .displayName("displayName") .grantType(GrantCreateParams.GrantType.PAID) .build(); CreditGrantResponse creditGrantResponse = client.v1().credits().grants().create(params); } } - lang: Ruby source: |- require "stigg" stigg = Stigg::Client.new(api_key: "My API Key") credit_grant_response = stigg.v1.credits.grants.create( amount: 0, currency_id: "currencyId", customer_id: "customerId", display_name: "displayName", grant_type: :PAID ) puts(credit_grant_response) - lang: C# source: >- using System; using Stigg.Client; using Stigg.Client.Models.V1.Credits.Grants; StiggClient client = new(); GrantCreateParams parameters = new() { Amount = 0, CurrencyID = "currencyId", CustomerID = "customerId", DisplayName = "displayName", GrantType = GrantType.Paid, }; var creditGrantResponse = await client.V1.Credits.Grants.Create(parameters); Console.WriteLine(creditGrantResponse); - lang: CLI source: |- stigg v1:credits:grants create \ --api-key 'My API Key' \ --amount 0 \ --currency-id currencyId \ --customer-id customerId \ --display-name displayName \ --grant-type PAID components: schemas: GrantCreditRequestDto: type: object properties: displayName: type: string maxLength: 255 description: The display name for the credit grant amount: type: number description: The credit amount to grant grantType: type: string enum: - PAID - PROMOTIONAL description: The type of credit grant (PAID, PROMOTIONAL) priority: type: integer minimum: 0 maximum: 100 description: >- Determines which grant is drawn down first when the customer has multiple active grants in the same currency (0-100). Lower numbers are consumed first. Defaults to 50 — the same default used for recurring credits granted by a plan or price — so without setting this explicitly, draw order against plan-included credits falls back to expiration date and grant type. To have this grant consumed before or after plan-included credits, set a lower or higher priority than the plan/price credit configuration. effectiveAt: type: string format: date-time description: The date when the credit grant becomes effective expireAt: type: string format: date-time description: The date when the credit grant expires metadata: type: object additionalProperties: type: string description: Additional metadata for the credit grant cost: type: object properties: amount: type: number description: The price amount currency: description: ISO 4217 currency code type: string enum: - 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 title: Currency required: - amount - currency title: Money description: The monetary cost of the credit grant comment: type: string maxLength: 255 description: An optional comment on the credit grant customerId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$ description: The customer ID to grant credits to (required) resourceId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: The resource ID to scope the grant to currencyId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: The credit currency ID (required) paymentCollectionMethod: type: string enum: - CHARGE - INVOICE - NONE description: >- The payment collection method (CHARGE, INVOICE, NONE). Optional if the grant has no `cost`, since there is nothing to collect payment for. With NONE or CHARGE, the grant is active and its credits are usable right away (or as soon as the charge succeeds). With INVOICE, the grant stays pending — its credits are not usable — until the generated invoice is paid. awaitPaymentConfirmation: type: boolean description: >- Whether to wait for payment confirmation before returning (default: true). When false, the request returns immediately while payment (if any) is collected asynchronously; check the returned status to see whether the credits are already usable. billingInformation: type: object properties: isInvoicePaid: type: boolean description: Whether the invoice is already paid invoiceDaysUntilDue: type: number description: Days until the invoice is due billingAddress: type: object properties: city: type: string description: City name country: type: string description: Country code or name line1: type: string description: Street address line 1 line2: type: string description: Street address line 2 postalCode: type: string description: Postal or ZIP code state: type: string description: State or province additionalProperties: false title: Address description: The billing address additionalProperties: false title: CreditGrantBillingInfo description: >- Billing information for the credit grant, used when the grant has a payment collection method that requires collecting payment (e.g. invoice due date, billing address). required: - displayName - amount - grantType - customerId - currencyId additionalProperties: false title: GrantCreditRequest description: >- Request body for creating a credit grant. Grants cannot be edited after creation — void and re-grant if the amount, priority, or expiration needs to change. CreditGrantResponseDto: type: object properties: data: type: object properties: id: type: string maxLength: 255 description: The unique readable identifier of the credit grant displayName: type: string maxLength: 255 description: The display name of the credit grant amount: type: number description: The total credits granted consumedAmount: type: number description: The total credits consumed from this grant grantType: type: string enum: - PAID - PROMOTIONAL - RECURRING - OVERDRAFT description: >- The type of credit grant (PAID, PROMOTIONAL, RECURRING, OVERDRAFT) sourceType: type: string enum: - PRICE - PLAN_ENTITLEMENT - ADDON_ENTITLEMENT nullable: true description: >- The source type of the grant (PRICE, PLAN_ENTITLEMENT, ADDON_ENTITLEMENT) priority: type: number description: >- The priority of the credit grant (lower number = higher priority) effectiveAt: type: string format: date-time description: The date when the credit grant becomes effective expireAt: type: string format: date-time description: The date when the credit grant expires nullable: true voidedAt: type: string format: date-time description: The date when the credit grant was voided nullable: true metadata: type: object additionalProperties: type: string description: Metadata associated with the entity cost: type: object properties: amount: type: number description: The cost amount currency: type: string maxLength: 255 description: The currency code required: - amount - currency description: The monetary cost of the credit grant comment: type: string maxLength: 255 description: An optional comment on the credit grant nullable: true customerId: type: string maxLength: 255 description: The customer ID this grant belongs to resourceId: type: string maxLength: 255 description: The resource ID this grant is scoped to nullable: true currencyId: type: string maxLength: 255 description: The currency identifier for this grant invoiceId: type: string maxLength: 255 description: The billing invoice ID associated with this grant nullable: true latestInvoice: type: object properties: billingId: type: string maxLength: 255 description: The billing provider invoice ID status: type: string enum: - OPEN - PAID - CANCELED description: The invoice status createdAt: type: string format: date-time description: The invoice creation date updatedAt: type: string format: date-time description: The invoice last update date dueDate: type: string format: date-time description: The invoice due date nullable: true requiresAction: type: boolean description: Whether the invoice requires user action billingReason: type: string enum: - MANUAL - OTHER nullable: true description: The billing reason for the invoice paymentUrl: type: string maxLength: 255 description: The payment URL for settling the invoice nullable: true errorMessage: type: string maxLength: 255 description: Error message if payment failed nullable: true pdfUrl: type: string maxLength: 255 description: The PDF URL of the invoice nullable: true currency: type: string maxLength: 255 description: The invoice currency nullable: true subTotal: type: number description: The subtotal amount before tax nullable: true total: type: number description: The total amount including tax nullable: true tax: type: number description: The tax amount nullable: true required: - billingId - status - createdAt - updatedAt - dueDate - requiresAction - billingReason - paymentUrl - errorMessage - pdfUrl - currency - subTotal - total - tax title: CreditGrantInvoice description: The latest invoice details for this grant nullable: true syncStates: type: array items: type: object properties: vendorIdentifier: type: string enum: - AUTH0 - ZUORA - STRIPE - HUBSPOT - AWS_MARKETPLACE - SNOWFLAKE - SALESFORCE - BIG_QUERY - OPEN_FGA - APP_STORE - RECEIVED - PREQUEL - AIRWALLEX - STRIPE_INVOICING description: >- The vendor identifier of the integration (e.g. STRIPE, SALESFORCE, SNOWFLAKE) status: type: string enum: - PENDING - ERROR - SUCCESS - NO_SYNC_REQUIRED description: Status of the integration sync syncedEntityId: type: string maxLength: 255 description: >- The external entity ID this record is linked to in the vendor system (e.g. the Stripe customer ID). Null until the link has synced; required when creating the link. nullable: true required: - vendorIdentifier - status - syncedEntityId nullable: true description: The synchronization states of the entity with external systems paymentCollection: type: string enum: - NOT_REQUIRED - PROCESSING - FAILED - ACTION_REQUIRED description: The payment collection status status: type: string enum: - PAYMENT_PENDING - ACTIVE - EXPIRED - VOIDED - SCHEDULED description: >- The effective status of the credit grant. A grant with paymentCollectionMethod NONE or CHARGE becomes ACTIVE (and its credits become usable) as soon as it's created (or as soon as the charge succeeds). A grant with paymentCollectionMethod INVOICE stays PAYMENT_PENDING — its credits are not usable — until the invoice is paid. createdAt: type: string format: date-time description: Timestamp of when the record was created updatedAt: type: string format: date-time description: Timestamp of when the record was last updated required: - id - displayName - amount - consumedAmount - grantType - sourceType - priority - effectiveAt - expireAt - voidedAt - metadata - cost - comment - customerId - resourceId - currencyId - invoiceId - latestInvoice - syncStates - paymentCollection - status - createdAt - updatedAt title: CreditGrant description: >- Credit grant object representing allocated credits for a customer. Credit grants cannot be edited after creation via this API — void the grant to stop further consumption from it, then create a new grant with the corrected amount, priority, or expiration. required: - data title: Response description: Response object BadInputErrorResponseDto: type: object properties: message: type: string code: type: string enum: - BadUserInput - EnvironmentMismatch - BillingContractOperationRejected - DuplicateIntegrationNotAllowed - EntityIsArchivedError - IntegrityViolation - FreePlanCantHaveCompatiblePackageGroupError - SubscriptionMustHaveSinglePlanError - AddonIsCompatibleWithPlan - AddonIsCompatibleWithGroup - DuplicateAddonProvisionedError - ScheduledMigrationAlreadyExistsError - SubscriptionAlreadyOnLatestPlan - EntityIdDifferentFromRefIdError - UnsupportedFeatureType - UnsupportedVendorIdentifier - UnsupportedSubscriptionScheduleType - InvalidEntitlementResetPeriod - IncompatibleSubscriptionAddon - UnPublishedPackage - MeteringNotAvailableForFeatureType - AuthCustomerMismatch - AuthCustomerReadonly - FetchAllCountriesPricesNotAllowed - MemberInvitationError - PlansCircularDependencyError - NoFeatureEntitlementInSubscription - CheckoutIsNotSupported - UnsupportedParameter - PricingModelNotSupportedByBillingIntegration - BillingIntegrationMissing - BillingIntegrationAlreadyExistsError - InvalidMemberDelete - PackageAlreadyPublished - DraftPlanCantBeArchived - DraftAddonCantBeArchived - PlanWithChildCantBeDeleted - PlanCannotBePublishWhenBasePlanIsDraft - PlanCannotBePublishWhenCompatibleAddonIsDraft - PlanIsUsedAsDefaultStartPlan - PlanIsUsedAsDowngradePlan - InvalidAddressError - InvalidQuantity - BillingPeriodMissingError - DowngradeBillingPeriodNotSupportedError - CustomerAlreadyUsesCouponError - CustomerAlreadyHaveCustomerCoupon - SubscriptionAlreadyCanceledOrExpired - TrialMustBeCancelledImmediately - SubscriptionDoesNotHaveBillingPeriod - InvalidCancellationDate - FailedToImportCustomer - FailedToImportSubscriptions - PackagePricingTypeNotSet - InvalidSubscriptionStatus - InvalidArgumentError - EditAllowedOnDraftPackageOnlyError - ResyncAlreadyInProgress - ArchivedCouponCantBeApplied - ImportAlreadyInProgress - AddonHasToHavePriceError - SelectedBillingModelDoesntMatchImportedItemError - CannotArchiveProductError - CannotUnarchiveProductError - CannotDeleteCustomerError - CannotRemovePaymentMethodFromCustomerError - CannotDeleteFeatureError - CannotArchiveFeatureError - InvalidUpdatePriceUnitAmountError - ExperimentAlreadyRunning - ExperimentStatusError - OperationNotAllowedDuringInProgressExperiment - EntitlementsMustBelongToSamePackage - CanNotUpdateEntitlementsFeatureGroup - MeterMustBeAssociatedToMeteredFeature - CannotUpdateMeterOfFeatureInUse - CannotEditPackageInNonDraftMode - CannotAddOverrideEntitlementToPlan - MissingEntityIdError - NoProductsAvailable - PromotionCodeNotForCustomer - PromotionCodeNotActive - PromotionCodeMaxRedemptionsReached - PromotionCodeMinimumAmountNotReached - PromotionCodeCustomerNotFirstPurchase - AddonWithDraftCannotBeDeletedError - CannotReportUsageForEntitlementWithMeterError - RecalculateEntitlementsError - ImportSubscriptionsBulkError - InvalidMetadataError - CannotUpsertToPackageThatHasDraft - IntegrationValidationError - AwsMarketplaceIntegrationValidationError - AwsMarketplaceIntegrationError - DataExportIntegrationError - HubspotIntegrationError - DuplicateProductValidationError - AmountTooLarge - CustomerHasNoEmailAddress - MergeEnvironmentValidationError - EntitlementLimitExceededError - EntitlementUsageOutOfRangeError - UsageMeasurementDiffOutOfRangeError - AddonQuantityExceedsLimitError - AddonDependencyMissingError - PackageGroupMinItemsError - CannotUpdateUnitTransformationError - SingleSubscriptionCantBeAutoCancellationTargetError - MultiSubscriptionCantBeAutoCancellationSourceError - ChangingPayingCustomerIsNotSupportedError - RequiredSsoAuthenticationError - InvalidDoggoSignatureError - InvalidReceivedSignatureError - CannotDeleteDefaultIntegration - CannotChangeBillingIntegration - FailedToResolveBillingIntegration - WorkflowTriggerNotFound - DeprecatedEstimateSubscriptionError - FeatureConfigurationExceededLimitError - FeatureNotBelongToFeatureGroupError - FeatureGroupMissingFeaturesError - VersionExceedsMaxValueError - CannotUpdateExpireAtForExpiredCreditGrantError - ExpireAtMustBeLaterThanEffectiveAtError - OfferAlreadyExists - DraftAlreadyExists - CreditGrantAlreadyVoided - CreditGrantCannotBeVoided - InvalidTaxId - ObjectAlreadyBeingUsedByAnotherRequestError - TooManySubscriptionsPerCustomer - TooManyCustomCurrencies - StripeError - SchedulingAtEndOfBillingPeriod - ApiKeyExpired - ApiKeyHasExpiry - OveragePriceNotSupportedOnAddon - OveragePriceRequiresUsageLimit - InvalidCreditOverageBillingModel - CreditOveragePriceCurrencyNotFound - InvoicePreviewNotAvailableForDraftContract nullable: true reason: type: string maxLength: 255 description: >- The billing side's machine-readable code for a billing-contract refusal. Present only when the code is BillingContractOperationRejected and the refusal carried one. required: - message - code UnauthenticatedErrorResponseDto: type: object properties: message: type: string code: type: string enum: - Unauthenticated nullable: true required: - message - code ForbiddenErrorResponseDto: type: object properties: message: type: string code: type: string enum: - IdentityForbidden - AccessDeniedError - NoFeatureEntitlementError - GovernanceNotEnabled nullable: true required: - message - code ConflictErrorResponseDto: type: object properties: message: type: string code: type: string enum: - DuplicatedEntityNotAllowed - EntitlementBelongsToFeatureGroupError nullable: true required: - message - code TooManyRequestsErrorResponseDto: type: object properties: message: type: string code: type: string enum: - RateLimitExceeded nullable: true required: - message - code securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: Server API Key ```` ## Related topics - [Credit grant created](/api-reference/credit-grants/credit-grant-created.md) - [Grant credits as entitlements in plans and add-ons](/guides/i-want-to/grant-credits-in-plans-and-add-ons.md) - [Adjust credit balance](/documentation/modeling-your-pricing-in-stigg/credits/adjust-credits.md) - [Monetize my product using credits](/guides/i-want-to/set-up-credits.md) - [Custom flows](/documentation/native-integrations/crm/salesforce/salesforce-create-your-flow.md)