--- title: "Preview subscription" method: POST path: "/api/v1/subscriptions/preview" tags: ["Subscriptions"] --- # Preview subscription `POST /api/v1/subscriptions/preview` Previews the pricing impact of creating or updating a subscription without making changes. Returns estimated costs, taxes, and proration details. ## Headers - `X-ACCOUNT-ID` string - `X-ENVIRONMENT-ID` string ## Request body - PreviewSubscriptionRequestDto — Preview subscription pricing and invoice details before provisioning. Returns calculated totals, line items, taxes, and discounts based on the provided subscription configuration. - `customerId` string, required — Customer ID - `payingCustomerId` string — Paying customer ID for delegated billing - `resourceId` string — Resource ID for multi-instance subscriptions - `planId` string, required — Plan ID - `billingPeriod` 'MONTHLY' | 'ANNUALLY' — Billing period (MONTHLY or ANNUALLY) - `billingCountryCode` string — ISO 3166-1 country code for localization - `unitQuantity` integer — Unit quantity for per-unit pricing. Minimum is 0 (zero is allowed). - `billableFeatures` object[] — Billable features with quantities - `featureId` string, required — Feature ID - `quantity` number, required — Quantity of feature units. Minimum is 0 (zero is allowed). - `charges` object[] — One-time or recurring charges - `type` 'FEATURE' | 'CREDIT', required — Charge type - `id` string, required — Charge ID - `quantity` number, required — Charge quantity. Minimum is 0 (zero is allowed). - `addons` object[] — Addons to include - `id` string, required — Addon ID - `quantity` integer, required — Number of addon instances - `startDate` string, date-time — Subscription start date - `billingInformation` object — Billing and tax configuration - `taxRateIds` string[] — Tax rate IDs from billing provider - `taxPercentage` number — Tax percentage to apply - `billingAddress` object — Billing address - `city` string - `country` string - `line1` string - `line2` string - `postalCode` string - `state` string - `metadata` object — Additional billing metadata - `chargeOnBehalfOfAccount` string — Connected account ID for platform billing - `isBackdated` boolean — Whether subscription is backdated - `isInvoicePaid` boolean — Whether invoice is already paid - `invoiceDaysUntilDue` number — Days until invoice is due - `integrationId` string — Billing integration ID - `prorationBehavior` 'INVOICE_IMMEDIATELY' | 'CREATE_PRORATIONS' | 'NONE' — Proration behavior - `taxIds` object[] — Customer tax IDs - `type` string, required — Tax exemption type (e.g., vat, gst) - `value` string, required — Tax exemption identifier value - `scheduleStrategy` 'END_OF_BILLING_PERIOD' | 'END_OF_BILLING_MONTH' | 'IMMEDIATE' — When to apply subscription changes - `appliedCoupon` object — Coupon or discount to apply - `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 - `trialOverrideConfiguration` object — Trial period override settings - `isTrial` boolean, required — Whether to start as trial - `trialEndDate` string, date-time — Trial end date - `trialEndBehavior` 'CONVERT_TO_PAID' | 'CANCEL_SUBSCRIPTION' — Behavior when trial ends - `billingCycleAnchor` 'UNCHANGED' | 'NOW' — Billing cycle anchor behavior for the subscription ## Response `201` The subscription preview with pricing breakdown. - PreviewSubscriptionResponseDto — Response object - `data` object, required — Pricing preview with invoices - `immediateInvoice` object, required — Invoice due immediately - `total` number, required — Invoice total - `subTotal` number, required — Subtotal before discounts - `discount` number — Total discount amount - `tax` number — Tax amount - `currency` string, nullable — Currency code - `billingPeriodRange` object — Billing period covered - `start` string, date-time, required — Billing period start date - `end` string, date-time, required — Billing period end date - `lines` object[] — Line items - `description` string, required — Line item description - `quantity` number — Quantity - `unitPrice` number, required — Price per unit - `subTotal` number, required — Line subtotal - `currency` string, required — Currency code - `discounts` object[] — Applied discounts - `description` string, required — Discount description - `amount` number, required — Discount amount - `currency` string, required — Currency code - `discountDetails` object — Discount breakdown - `code` string — Promo code used - `percentage` number — Percentage discount - `fixedAmount` number — Fixed discount amount - `recurringInvoice` object — Recurring invoice preview - `total` number, required — Invoice total - `subTotal` number, required — Subtotal before discounts - `discount` number — Total discount amount - `tax` number — Tax amount - `currency` string, nullable — Currency code - `billingPeriodRange` object — Billing period covered - `start` string, date-time, required — Billing period start date - `end` string, date-time, required — Billing period end date - `lines` object[] — Line items - `description` string, required — Line item description - `quantity` number — Quantity - `unitPrice` number, required — Price per unit - `subTotal` number, required — Line subtotal - `currency` string, required — Currency code - `discounts` object[] — Applied discounts - `description` string, required — Discount description - `amount` number, required — Discount amount - `currency` string, required — Currency code - `discountDetails` object — Discount breakdown - `code` string — Promo code used - `percentage` number — Percentage discount - `fixedAmount` number — Fixed discount amount - `billingPeriodRange` object — Billing period range - `start` string, date-time — Billing period start date - `end` string, date-time — Billing period end date - `isPlanDowngrade` boolean — Whether this is a downgrade - `hasScheduledUpdates` boolean — Whether updates are scheduled - `freeItems` object[] — Free items included - `id` string, required — Addon ID - `quantity` integer, required — Number of addon instances ## Other responses - `400` — bad request. - `401` — User is not authenticated. - `403` — User is not allowed to access this resource. - `409` — SubscriptionPreview 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)