---
title: "Provision subscription"
method: POST
path: "/api/v1/subscriptions"
tags: ["Subscriptions"]
---

# Provision subscription

`POST /api/v1/subscriptions`

Creates a new subscription for an existing customer. When payment is required and no payment method exists, returns a checkout URL.

## Headers

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

## Request body

- ProvisionSubscriptionRequestDto — Provision a subscription. Returns subscription or checkout URL.
  - `id` string — Unique identifier for the subscription
  - `customerId` string, required — Customer ID to provision the subscription for
  - `planId` string, required — Plan ID to provision
  - `payingCustomerId` string, nullable — Optional paying customer ID for split billing scenarios
  - `resourceId` string, nullable — Optional resource ID for multi-instance subscriptions
  - `billingPeriod` 'MONTHLY' | 'ANNUALLY' — Billing period (MONTHLY or ANNUALLY)
  - `addons` object[]
    - `id` string, required — Addon ID
    - `quantity` integer, required — Number of addon instances
  - `charges` object[]
    - `type` 'FEATURE' | 'CREDIT', required — Charge type
    - `id` string, required — Charge ID
    - `quantity` number, required — Charge quantity. Minimum is 0 (zero is allowed).
  - `startDate` string, date-time — Subscription start date
  - `cancellationDate` string, date-time — Subscription cancellation date
  - `billingInformation` object
    - `taxRateIds` string[] — Tax rate identifiers to apply
    - `taxPercentage` number — Tax percentage (0-100)
    - `billingAddress` object — Billing address for the subscription
      - `city` string
      - `country` string
      - `line1` string
      - `line2` string
      - `postalCode` string
      - `state` string
    - `metadata` object — Additional metadata for the subscription
    - `chargeOnBehalfOfAccount` string, nullable — Stripe Connect account to charge on behalf of
    - `isBackdated` boolean — Whether the subscription is backdated
    - `isInvoicePaid` boolean — Whether the invoice is marked as paid
    - `invoiceDaysUntilDue` number — Number of days until invoice is due
    - `integrationId` string, nullable — Billing integration identifier
    - `prorationBehavior` 'INVOICE_IMMEDIATELY' | 'CREATE_PRORATIONS' | 'NONE' — How to handle proration for billing changes
    - `taxIds` object[] — Customer tax identification numbers
      - `type` string, required — The type of tax exemption identifier, such as VAT.
      - `value` string, required — The actual tax identifier value
  - `billingId` string, nullable — External billing system identifier
  - `billingCountryCode` string, nullable — The ISO 3166-1 alpha-2 country code for billing
  - `entitlements` union[]
    - union
      - object — Feature entitlement configuration for a subscription
        - `type` 'FEATURE', required — SubscriptionFeatureEntitlementRequest
        - `id` string, required — The feature ID to attach the entitlement to
        - `usageLimit` integer — Maximum allowed usage for the feature
        - `hasUnlimitedUsage` boolean — Whether usage is unlimited
        - `hasSoftLimit` boolean — Whether the usage limit is a soft limit
        - `resetPeriod` 'YEAR' | 'MONTH' | 'WEEK' | 'DAY' | 'HOUR' — Period at which usage resets
        - `yearlyResetPeriodConfiguration` object, nullable — Configuration for yearly reset period
          - `accordingTo` 'SubscriptionStart', required — Reset anchor (SubscriptionStart)
        - `monthlyResetPeriodConfiguration` object, nullable — Configuration for monthly reset period
          - `accordingTo` 'SubscriptionStart' | 'StartOfTheMonth', required — Reset anchor (SubscriptionStart or StartOfTheMonth)
        - `weeklyResetPeriodConfiguration` object, nullable — Configuration for weekly reset period
          - `accordingTo` 'SubscriptionStart' | 'EverySunday' | 'EveryMonday' | 'EveryTuesday' | 'EveryWednesday' | 'EveryThursday' | 'EveryFriday' | 'EverySaturday', required — Reset anchor (SubscriptionStart or specific day)
      - object — Credit entitlement configuration for a subscription
        - `type` 'CREDIT', required — SubscriptionCreditEntitlementRequest
        - `id` string, required — The custom currency ID for the credit entitlement
        - `amount` number, required — Credit grant amount
        - `cadence` 'MONTH' | 'YEAR', required — Credit grant cadence (MONTH or YEAR)
  - `trialOverrideConfiguration` object — Trial period override settings
    - `isTrial` boolean, required — Whether the subscription should start with a trial period
    - `trialEndBehavior` 'CONVERT_TO_PAID' | 'CANCEL_SUBSCRIPTION' — Behavior when trial ends: CONVERT_TO_PAID or CANCEL_SUBSCRIPTION
    - `trialEndDate` string, date-time — Custom trial end date
  - `scheduleStrategy` 'END_OF_BILLING_PERIOD' | 'END_OF_BILLING_MONTH' | 'IMMEDIATE' — Strategy for scheduling subscription changes
  - `checkoutOptions` object — Checkout page configuration for payment collection
    - `successUrl` string, uri, required — URL to redirect to after successful checkout
    - `cancelUrl` string, uri, required — URL to redirect to if checkout is canceled
    - `allowPromoCodes` boolean — Allow promotional codes during checkout
    - `allowTaxIdCollection` boolean — Allow tax ID collection during checkout
    - `collectBillingAddress` boolean — Collect billing address during checkout
    - `referenceId` string, nullable — Optional reference ID for the checkout session
    - `collectPhoneNumber` boolean — Collect phone number during checkout
  - `metadata` object — Additional metadata for the subscription
  - `salesforceId` string, nullable — Salesforce ID
  - `budget` object, nullable
    - `limit` number, required — Maximum spending limit
    - `hasSoftLimit` boolean, required — Whether the budget is a soft limit
  - `minimumSpend` object, nullable — Minimum spend amount
    - `amount` number — 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' — The price currency
  - `priceOverrides` object[]
    - `amount` number — 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' — The price currency
    - `featureId` string, nullable — Feature identifier for the price override
    - `addonId` string, nullable — Addon identifier for the price override
    - `baseCharge` boolean — Whether this is a base charge override
    - `billingCountryCode` string — The billing country code of the price
    - `blockSize` number — Block size for pricing
    - `tiers` object[] — Pricing tiers configuration
      - `upTo` number — The up to quantity of the price tier
      - `unitPrice` object — The unit price of the price tier
        - `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
      - `flatPrice` object — The flat fee price of the price tier
        - `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
    - `creditRate` object
      - `amount` number, required — The credit rate amount
      - `currencyId` string, required — The custom currency refId for the credit rate
      - `costFormula` string, nullable — A custom formula for calculating cost based on single event dimensions
    - `creditGrantCadence` 'BEGINNING_OF_BILLING_PERIOD' | 'MONTHLY'
  - `paymentCollectionMethod` 'CHARGE' | 'INVOICE' | 'NONE' — How payments should be collected for this subscription
  - `appliedCoupon` object — Coupon configuration
    - `couponId` string — Stigg coupon ID
    - `billingCouponId` string — Billing provider coupon ID
    - `promotionCode` string — Promotion code to apply
    - `discount` object — Ad-hoc discount configuration
      - `name` string — Discount name
      - `description` string — Ad-hoc discount
      - `durationInMonths` number — Duration in months
      - `percentOff` number — Percentage discount
      - `amountsOff` object[], nullable — Fixed amounts off by currency
        - `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
    - `configuration` object — Coupon timing configuration
      - `startDate` string, date-time — Coupon start date
  - `awaitPaymentConfirmation` boolean — Whether to wait for payment confirmation before returning the subscription
  - `unitQuantity` integer — Unit quantity for per-unit pricing. Minimum is 0 (zero is allowed).
  - `billingCycleAnchor` 'UNCHANGED' | 'NOW' — Billing cycle anchor behavior for the subscription

## Response `201`

The newly created subscription object.

- ProvisionSubscriptionResponseDto — Response object
  - `data` object, required — Provisioning result with status and subscription or checkout URL.
    - `id` string, required — Unique identifier for the provisioned subscription
    - `status` 'SUCCESS' | 'PAYMENT_REQUIRED', required — Provision status: SUCCESS or PAYMENT_REQUIRED
    - `checkoutBillingId` string — Checkout billing ID when payment is required
    - `checkoutUrl` string — URL to complete payment when PAYMENT_REQUIRED
    - `subscription` object, nullable, required — Created subscription (when status is SUCCESS)
      - `id` string, required — Subscription ID
      - `customerId` string, required — Customer ID
      - `payingCustomerId` string, nullable — Paying customer ID for delegated billing
      - `resourceId` string, nullable — Resource ID
      - `billingId` string, nullable, required — Billing ID
      - `contractId` string, nullable — The Stigg contract this subscription is linked to, when any
      - `createdAt` string, date-time, required — Created at
      - `startDate` string, date-time, required — Subscription start date
      - `endDate` string, date-time, nullable — Subscription end date
      - `effectiveEndDate` string, date-time, nullable — Subscription effective end date
      - `cancellationDate` string, date-time, nullable — Subscription cancellation date
      - `trialEndDate` string, date-time, nullable — Subscription trial end date
      - `status` 'PAYMENT_PENDING' | 'ACTIVE' | 'EXPIRED' | 'IN_TRIAL' | 'CANCELED' | 'NOT_STARTED', required — Subscription status
      - `cancelReason` 'UPGRADE_OR_DOWNGRADE' | 'CANCELLED_BY_BILLING' | 'EXPIRED' | 'DETACH_BILLING' | 'TRIAL_ENDED' | 'Immediate' | 'TRIAL_CONVERTED' | 'PENDING_PAYMENT_EXPIRED' | 'ScheduledCancellation' | 'CustomerArchived' | 'AutoCancellationRule', nullable — Subscription cancel reason
      - `metadata` object — Additional metadata for the subscription
      - `currentBillingPeriodStart` string, date-time, nullable — Start of the current billing period
      - `currentBillingPeriodEnd` string, date-time, nullable — End of the current billing period
      - `pricingType` 'FREE' | 'PAID' | 'CUSTOM', required — Pricing type
      - `paymentCollection` 'NOT_REQUIRED' | 'PROCESSING' | 'FAILED' | 'ACTION_REQUIRED', required — Payment collection
      - `paymentCollectionMethod` 'CHARGE' | 'INVOICE' | 'NONE', nullable — The method used to collect payments for a subscription
      - `billingCycleAnchor` string, date-time, nullable — Billing cycle anchor date
      - `planId` string, required — Plan ID
      - `prices` object[]
        - `amount` number — 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' — The price currency
        - `featureId` string, nullable — Feature identifier for the price override
        - `addonId` string, nullable — Addon identifier for the price override
        - `baseCharge` boolean — Whether this is a base charge override
        - `billingCountryCode` string — The billing country code of the price
        - `blockSize` number — Block size for pricing
        - `tiers` object[] — Pricing tiers configuration
          - `upTo` number — The up to quantity of the price tier
          - `unitPrice` object — The unit price of the price tier
            - `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
          - `flatPrice` object — The flat fee price of the price tier
            - `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
      - `addons` object[]
        - `id` string, required — Addon ID
        - `quantity` integer, required — Number of addon instances
      - `coupons` object[] — Coupons applied to the subscription
        - `id` string, required — Coupon ID
        - `name` string, required — Coupon name
        - `status` 'ACTIVE' | 'EXPIRED' | 'REMOVED', required — Coupon status
        - `percentOff` number, nullable — Percentage discount
        - `amountsOff` object[], nullable — Fixed amount discounts by currency
          - `amount` number — 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' — The price currency
      - `futureUpdates` object[] — Scheduled future updates for the subscription
        - `scheduledExecutionTime` string, date-time, required — Scheduled execution time
        - `subscriptionScheduleType` 'DOWNGRADE' | 'PLAN' | 'BILLING_PERIOD' | 'UNIT_AMOUNT' | 'RECURRING_CREDITS' | 'PRICE_OVERRIDE' | 'ADDON' | 'COUPON' | 'MIGRATE_TO_LATEST' | 'ADDITIONAL_META_DATA' | 'BILLING_INFO_METADATA', required — Type of scheduled change
        - `scheduleStatus` 'PENDING_PAYMENT' | 'SCHEDULED' | 'CANCELED' | 'DONE' | 'FAILED', required — Status of the scheduled update
        - `targetPackage` object, nullable — Target package for the update
          - `id` string, required — Target package for the update
      - `budget` object, nullable — Budget configuration
        - `limit` number, required — Maximum spending limit
        - `hasSoftLimit` boolean, required — Whether the budget is a soft limit
      - `minimumSpend` object, nullable — Minimum spend configuration
        - `amount` number — 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' — The price currency
      - `subscriptionEntitlements` object[] — Entitlements associated with the subscription
        - `type` 'FEATURE' | 'CREDIT', required — Entitlement type (FEATURE or CREDIT)
        - `id` string, required — Feature ID or currency ID
      - `latestInvoice` object, nullable — Latest invoice for the subscription
        - `billingId` string, required — Invoice billing ID
        - `status` 'OPEN' | 'CANCELED' | 'PAID', required — Invoice status
        - `createdAt` string, date-time, required — Invoice creation date
        - `total` number, nullable — Total amount
        - `amountDue` number, nullable — Amount due
        - `currency` string, nullable — Invoice currency
        - `pdfUrl` string, nullable — Invoice PDF URL
        - `requiresAction` boolean, required — Whether payment requires action
        - `billingReason` 'BILLING_CYCLE' | 'SUBSCRIPTION_CREATION' | 'SUBSCRIPTION_UPDATE' | 'MANUAL' | 'MINIMUM_INVOICE_AMOUNT_EXCEEDED' | 'OTHER', nullable — Billing reason
      - `trial` object, nullable — Trial configuration
        - `trialEndBehavior` 'CONVERT_TO_PAID' | 'CANCEL_SUBSCRIPTION', required — Behavior when the trial ends
    - `isScheduled` boolean — Whether the subscription is scheduled for future activation
    - `entitlements` union[], nullable, required
      - union
        - UnionObjectVariant0
          - `isGranted` boolean, required
          - `type` 'FEATURE', required
          - `accessDeniedReason` 'FeatureNotFound' | 'CustomerNotFound' | 'CustomerIsArchived' | 'CustomerResourceNotFound' | 'NoActiveSubscription' | 'NoFeatureEntitlementInSubscription' | 'RequestedUsageExceedingLimit' | 'RequestedValuesMismatch' | 'BudgetExceeded' | 'Unknown' | 'FeatureTypeMismatch' | 'Revoked' | 'InsufficientCredits' | 'EntitlementNotFound', nullable, required
          - `feature` object
            - `id` string, required — The unique reference ID of the entitlement.
            - `displayName` string, required — The human-readable name of the entitlement, shown in UI elements.
            - `featureType` 'BOOLEAN' | 'NUMBER' | 'ENUM', required — The type of feature associated with the entitlement.
            - `featureStatus` 'NEW' | 'SUSPENDED' | 'ACTIVE', required — The current status of the feature.
          - `usageLimit` number, nullable
          - `hasUnlimitedUsage` boolean
          - `resetPeriod` 'YEAR' | 'MONTH' | 'WEEK' | 'DAY' | 'HOUR', nullable
          - `currentUsage` number
          - `usagePeriodAnchor` string, date-time — The anchor for calculating the usage period for metered entitlements with a reset period configured
          - `usagePeriodStart` string, date-time — The start date of the usage period for metered entitlements with a reset period configured
          - `usagePeriodEnd` string, date-time — The end date of the usage period for metered entitlements with a reset period configured
          - `entitlementUpdatedAt` string, date-time — Timestamp of the last update to the entitlement grant or configuration.
          - `validUntil` string, date-time — The next time the entitlement should be recalculated
        - UnionObjectVariant1
          - `isGranted` boolean, required
          - `type` 'CREDIT', required
          - `accessDeniedReason` 'FeatureNotFound' | 'CustomerNotFound' | 'CustomerIsArchived' | 'CustomerResourceNotFound' | 'NoActiveSubscription' | 'NoFeatureEntitlementInSubscription' | 'RequestedUsageExceedingLimit' | 'RequestedValuesMismatch' | 'BudgetExceeded' | 'Unknown' | 'FeatureTypeMismatch' | 'Revoked' | 'InsufficientCredits' | 'EntitlementNotFound', nullable, required
          - `usageLimit` number, required
          - `currentUsage` number, required
          - `usageUpdatedAt` string, date-time, required — Timestamp of the last update to the credit usage.
          - `currency` object, required — The currency associated with a credit entitlement.
            - `currencyId` string, required — The unique identifier of the custom currency.
            - `displayName` string, required — The display name of the currency.
            - `description` string, nullable — A description of the currency.
            - `unitSingular` string, nullable — The singular form of the currency unit.
            - `unitPlural` string, nullable — The plural form of the currency unit.
            - `metadata` object, nullable — Additional metadata associated with the currency.
          - `entitlementUpdatedAt` string, date-time — Timestamp of the last update to the entitlement grant or configuration.
          - `validUntil` string, date-time — The next time the entitlement should be recalculated
          - `usagePeriodEnd` string, date-time — The end date of the current billing period for recurring credit grants.

## Other responses

- `400` — bad request.
- `401` — User is not authenticated.
- `403` — User is not allowed to access this resource.
- `409` — Subscription 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/versions/ffc977f1c07e/schema)