> ## Documentation Index > Fetch the complete documentation index at: https://docs.sequencehq.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a customer credit grant > Create a one-off cash credit grant held by a customer directly, outside any billing schedule. Its credit is issued after this request returns, so the response shows the grant as it stands at that moment: usually `state.issuance` PENDING with a zero `availableBalance`, becoming ISSUED with the full balance once funded. Retrying with the same `Idempotency-Key` returns the original grant without creating another. Keys never expire within your account, and a key reused with different terms is rejected. ## OpenAPI ````yaml billing.2024-07-30.product.live POST /credit-grants openapi: 3.0.0 info: title: Billing description: Manage Billing version: 0.0.1 servers: - url: https://dev.seqhq.io description: E2E - url: https://dev.seqhq.io description: DEV - url: https://sandbox.sequencehq.com description: SANDBOX - url: https://eu.sequencehq.com description: PRODUCTION security: [] tags: - name: Prices - name: Credits - name: Billing Schedules - name: Discounts paths: /credit-grants: servers: [] parameters: [] post: tags: - Credits summary: Create a customer credit grant description: >- Create a one-off cash credit grant held by a customer directly, outside any billing schedule. Its credit is issued after this request returns, so the response shows the grant as it stands at that moment: usually `state.issuance` PENDING with a zero `availableBalance`, becoming ISSUED with the full balance once funded. Retrying with the same `Idempotency-Key` returns the original grant without creating another. Keys never expire within your account, and a key reused with different terms is rejected. operationId: postCreditGrants parameters: - name: Authorization in: header description: >- Your [API credentials](/reference/authentication). Eg. `Basic {credentials}`. required: true schema: type: string - name: Idempotency-Key in: header description: >- Unique ID for this request, at most 255 printable ASCII characters. Retrying with the same ID returns the original grant. IDs are never reusable within your account. required: true schema: type: string - name: sequence-version in: header description: Use this header to select an API version required: false schema: type: string enum: - '2024-07-30' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateCustomerCreditGrantRequest' example: customerId: 61b083e0-1faa-47ca-9aeb-6205da8f6c47 name: Onboarding credit currency: GBP amount: 500 costOfCredit: 400 effectiveDate: '2026-01-01' expiryDate: '2026-12-31' examples: CreateCustomerCreditGrantRequest: summary: '' value: customerId: 61b083e0-1faa-47ca-9aeb-6205da8f6c47 name: Onboarding credit currency: GBP amount: 500 costOfCredit: 400 effectiveDate: '2026-01-01' expiryDate: '2026-12-31' required: true responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/CreditGrantV2Response' example: id: 0199ca8a-e7e8-73b3-bd69-a316a23231d3 sequenceAccountId: dce9ae85-d8d0-42b4-bcad-f221a64363c6 customerId: 61b083e0-1faa-47ca-9aeb-6205da8f6c47 scope: CUSTOMER name: Onboarding credit creditUnitType: CURRENCY currency: GBP amount: 500 availableBalance: 0 state: issuance: PENDING validity: CURRENT costOfCredit: 400 effectiveDate: '2026-01-01' expiryDate: '2026-12-31' createdAt: '2026-01-01T10:00:00Z' updatedAt: '2026-01-01T10:00:00Z' grantRefreshFrequency: NONE billingFrequency: ONE_TIME rolloverMode: NONE restrictToPrices: [] integrationIds: [] examples: CreditGrantV2Response: summary: '' value: id: 0199ca8a-e7e8-73b3-bd69-a316a23231d3 sequenceAccountId: dce9ae85-d8d0-42b4-bcad-f221a64363c6 customerId: 61b083e0-1faa-47ca-9aeb-6205da8f6c47 scope: CUSTOMER name: Onboarding credit creditUnitType: CURRENCY currency: GBP amount: 500 availableBalance: 0 state: issuance: PENDING validity: CURRENT costOfCredit: 400 effectiveDate: '2026-01-01' expiryDate: '2026-12-31' createdAt: '2026-01-01T10:00:00Z' updatedAt: '2026-01-01T10:00:00Z' grantRefreshFrequency: NONE billingFrequency: ONE_TIME rolloverMode: NONE restrictToPrices: [] integrationIds: [] '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: type: validationError message: The request was invalid. errors: - code: invalidField message: The request was invalid. examples: ApiError: summary: '' value: error: type: validationError message: The request was invalid. errors: - code: invalidField message: The request was invalid. '401': description: Unauthorized content: {} '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: type: customerCreditGrantError message: Customer not found. errors: - code: customerNotFound message: Customer not found. examples: ApiError: summary: '' value: error: type: customerCreditGrantError message: Customer not found. errors: - code: customerNotFound message: Customer not found. '500': description: Internal Server Error content: {} components: schemas: CreateCustomerCreditGrantRequest: required: - amount - costOfCredit - currency - customerId - effectiveDate type: object example: customerId: 61b083e0-1faa-47ca-9aeb-6205da8f6c47 name: Onboarding credit currency: GBP amount: 500 costOfCredit: 400 effectiveDate: '2026-01-01' expiryDate: '2026-12-31' properties: customerId: type: string description: ID of the customer receiving the credit. example: 61b083e0-1faa-47ca-9aeb-6205da8f6c47 name: type: string description: >- Name of the credit grant, up to 256 characters. Defaults to "Credit grant" when omitted. nullable: true example: Onboarding credit currency: $ref: '#/components/schemas/Currency' description: Currency of the credit. Must be a currency your account invoices in. amount: type: number description: >- Amount of credit granted, in the grant's currency. Must be positive, with at most 15 digits before the decimal point and 10 after it. example: 500 costOfCredit: type: number description: >- Amount the customer pays for the credit, in the grant's currency. Zero for free credit; cannot be negative or exceed the amount granted. At most 15 digits before the decimal point and 10 after it. example: 400 effectiveDate: type: string description: First day the credit can be used, inclusive, in UTC. example: '2026-01-01' expiryDate: type: string description: >- Last day the credit can be used, inclusive, in UTC. Cannot be before the effective date. Omit for credit that does not expire. nullable: true example: '2026-12-31' CreditGrantV2Response: required: - amount - availableBalance - billingFrequency - createdAt - creditUnitType - customerId - grantRefreshFrequency - id - integrationIds - name - restrictToPrices - rolloverMode - scope - sequenceAccountId - state - updatedAt type: object example: id: 0199ca8a-e7e8-73b3-bd69-a316a23231a0 sequenceAccountId: dce9ae85-d8d0-42b4-bcad-f221a64363c6 customerId: 61b083e0-1faa-47ca-9aeb-6205da8f6c47 scope: SCHEDULE billingScheduleId: 0199ca86-560e-7ac4-999f-bee364f7e4e7 phaseId: 0199ca87-6d80-7836-aa09-10386a08d761 name: Monthly usage credits creditUnitType: CURRENCY currency: GBP metricId: f092246c-6b90-4106-bcca-304ccf06bf45 amount: 100 availableBalance: 79.35 state: issuance: ISSUED validity: CURRENT costOfCredit: 100 taxRateId: 179d1ab3-cc96-48e2-9310-067b0b42d47c effectiveDate: '2026-01-01' expiryDate: '2026-01-31' createdAt: '2026-01-01T10:00:00Z' updatedAt: '2026-01-01T10:00:00Z' grantRefreshFrequency: MONTHLY billingFrequency: MONTHLY rolloverMode: NONE sourceGrantId: 0199ca8a-e7e8-73b3-bd69-a316a2323100 restrictToPrices: - 0199ca89-2d9e-7e3d-914c-7de86e8fc7ce integrationIds: - service: Xero id: 74ed2615-4730-49ab-9445-74f31723a206 isPending: false properties: id: type: string description: Credit grant ID. example: 0199ca8a-e7e8-73b3-bd69-a316a23231a0 sequenceAccountId: type: string description: Sequence account ID. example: dce9ae85-d8d0-42b4-bcad-f221a64363c6 customerId: type: string description: ID of the customer receiving the credit. example: 61b083e0-1faa-47ca-9aeb-6205da8f6c47 scope: $ref: '#/components/schemas/GrantScope' description: >- Whether the grant is held by the customer directly (CUSTOMER) or belongs to one of their billing schedules (SCHEDULE). billingScheduleId: type: string description: >- ID of the billing schedule the grant belongs to. Absent for a customer grant. nullable: true example: 0199ca86-560e-7ac4-999f-bee364f7e4e7 phaseId: type: string description: >- ID of the billing schedule phase the grant belongs to. Absent for a customer grant. nullable: true example: 0199ca87-6d80-7836-aa09-10386a08d761 name: type: string description: Name of the credit grant. example: Monthly usage credits creditUnitType: $ref: '#/components/schemas/CreditUnitType' description: Whether credit is measured in currency or usage-metric units. currency: $ref: '#/components/schemas/Currency' description: >- Currency the grant is denominated in. Null when creditUnitType is METRIC. nullable: true metricId: type: string description: >- ID of the usage metric the credit is measured in when creditUnitType is METRIC. nullable: true example: f092246c-6b90-4106-bcca-304ccf06bf45 amount: type: number description: >- The configured credit allowance. Available credit may exceed this amount after rollover. The difference between this amount and available credit does not represent usage. example: 100 availableBalance: type: number description: >- Credit currently available for eligible prices. Never negative. Zero before the effective date, while awaiting issuance, when no credit remains, or after expiry. Usage awaiting processing is not yet deducted. Dates are evaluated in UTC and are inclusive. example: 79.35 state: $ref: '#/components/schemas/CreditGrantStateResponse' costOfCredit: type: number description: The amount charged to the customer for the credit grant. nullable: true example: 100 taxRateId: type: string description: Tax rate ID for the credit grant. nullable: true example: 179d1ab3-cc96-48e2-9310-067b0b42d47c effectiveDate: type: string description: First day the credit can be used, inclusive, in UTC. nullable: true example: '2026-01-01' expiryDate: type: string description: Last day the credit can be used, inclusive, in UTC. nullable: true example: '2026-01-31' createdAt: type: string description: When the credit grant was created. example: '2026-01-01T10:00:00Z' updatedAt: type: string description: >- When the grant's configuration last changed. Changes to the available balance do not update this timestamp. example: '2026-01-01T10:00:00Z' grantRefreshFrequency: $ref: '#/components/schemas/GrantRefreshFrequency' description: How often the credit grant refreshes its balance. billingFrequency: $ref: '#/components/schemas/GrantBillingFrequency' description: How often the customer is charged for the credit grant. rolloverMode: $ref: '#/components/schemas/RolloverMode' description: Whether unused balance carries over when the grant refreshes. sourceGrantId: type: string description: ID of the grant whose unused credit was rolled over into this grant. nullable: true example: 0199ca8a-e7e8-73b3-bd69-a316a2323100 restrictToPrices: type: array description: >- IDs of prices eligible to use this credit. Includes all prices in the phase when no restriction was specified. Empty for a customer grant. example: - 0199ca89-2d9e-7e3d-914c-7de86e8fc7ce items: type: string integrationIds: type: array description: Identifiers for this credit grant in external integrations. example: - service: Xero id: 74ed2615-4730-49ab-9445-74f31723a206 isPending: false items: $ref: '#/components/schemas/IntegrationId' ApiError: required: - error type: object example: error: type: validationError message: The request was invalid. errors: - code: invalidField message: The request was invalid. properties: error: $ref: '#/components/schemas/ErrorObject' Currency: type: string example: GBP enum: - AED - ARS - AUD - BRL - BGN - CAD - CHF - CLP - CNY - COP - CZK - DKK - EGP - EUR - GBP - HKD - ILS - INR - ISK - JPY - KRW - MXN - NOK - NZD - PLN - SAR - SEK - SGD - THB - USD - UYU - ZAR GrantScope: type: string example: SCHEDULE enum: - CUSTOMER - SCHEDULE CreditUnitType: type: string example: CURRENCY enum: - CURRENCY - METRIC CreditGrantStateResponse: required: - issuance - validity type: object description: >- Independent issuance and date-validity states. availableBalance reports the credit usable now. example: issuance: ISSUED validity: CURRENT properties: issuance: $ref: '#/components/schemas/CreditGrantIssuance' description: >- PENDING until the grant's credits are issued; ISSUED thereafter, including after depletion or expiry. Cash credits are issued when their charging invoice is finalised; this does not confirm payment. Metric grants are always ISSUED. Applies to the grant, not individual recurring allowances. validity: $ref: '#/components/schemas/CreditGrantValidity' description: >- SCHEDULED before the effective date, CURRENT within the validity window, or EXPIRED after the expiry date. Dates are inclusive and evaluated in UTC; a missing date leaves that boundary unrestricted. CURRENT does not imply issued credits or a positive available balance. GrantRefreshFrequency: type: string example: MONTHLY enum: - NONE - MONTHLY - QUARTERLY - HALF_YEARLY - YEARLY GrantBillingFrequency: type: string example: MONTHLY enum: - ONE_TIME - MONTHLY - QUARTERLY - HALF_YEARLY - YEARLY RolloverMode: type: string example: NONE enum: - NONE - ON_GRANT_REFRESH - ON_GRANT_REFRESH_AND_PHASE IntegrationId: required: - id - isPending - service type: object example: service: Xero id: '123' isPending: false properties: service: $ref: '#/components/schemas/IntegrationService' id: type: string example: '123' isPending: type: boolean example: false ErrorObject: required: - message - type type: object description: Top level wrapper for all errors example: type: validationError message: The request was invalid. errors: - code: invalidField message: The request was invalid. properties: type: type: string description: Type of the error example: validationError message: type: string description: Plain text description of the error example: The request was invalid. errors: type: array description: A list of detailed errors nullable: true example: - code: invalidField message: The request was invalid. items: $ref: '#/components/schemas/ErrorItem' CreditGrantIssuance: type: string example: ISSUED enum: - PENDING - ISSUED CreditGrantValidity: type: string example: CURRENT enum: - SCHEDULED - CURRENT - EXPIRED IntegrationService: type: string example: Xero enum: - Amazon_Redshift - GoCardless - Google_BigQuery - Google_Sheets - HubSpot - NetSuite - QuickBooks_Online - Salesforce - Slack - Snowflake - Stripe - Xero - Avalara - Anrok - Attio - Numeral - Rillet - Sphere ErrorItem: required: - code - message type: object example: code: invalidField message: The request was invalid. properties: code: type: string description: Code of the error example: invalidField message: type: string description: Plain text description of the error example: The request was invalid. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.