> ## 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 https://app.stainless.com/api/spec/documented/stigg/openapi.documented.yml post /api/v1/credits/grants openapi: 3.0.0 info: title: Stigg API description: Stigg API documentation version: 7.80.3 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 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: 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 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) awaitPaymentConfirmation: type: boolean description: >- Whether to wait for payment confirmation before returning (default: true) 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 required: - displayName - amount - grantType - customerId - currencyId additionalProperties: false title: GrantCreditRequest description: Request body for creating a credit grant 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) 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 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 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 - paymentCollection - status - createdAt - updatedAt title: CreditGrant description: Credit grant object representing allocated credits for a customer required: - data title: Response description: Response object BadInputErrorResponseDto: type: object properties: message: type: string code: type: string enum: - BadUserInput - 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 - 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 nullable: true 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 nullable: true required: - message - code ConflictErrorResponseDto: type: object properties: message: type: string code: type: string enum: - DuplicatedEntityNotAllowed - EntitlementBelongsToFeatureGroupError - InvoicePreviewNotAvailableForDraftContract 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 ````