> ## 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. # Preview Subscription > Previews the pricing impact of creating or updating a subscription without making changes. Returns estimated costs, taxes, and proration details. ## OpenAPI ````yaml POST /api/v1/subscriptions/preview openapi: 3.0.0 info: title: Stigg API description: Stigg API documentation version: 7.93.1 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/subscriptions/preview: post: tags: - Subscriptions summary: Preview subscription description: >- Previews the pricing impact of creating or updating a subscription without making changes. Returns estimated costs, taxes, and proration details. operationId: SubscriptionController_previewSubscription 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/PreviewSubscriptionRequestDto' responses: '201': description: The subscription preview with pricing breakdown. content: application/json: schema: $ref: '#/components/schemas/PreviewSubscriptionResponseDto' '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: SubscriptionPreview 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 response = await client.v1.subscriptions.preview({ customerId: 'customerId', planId: 'planId', }); console.log(response.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 ) response = client.v1.subscriptions.preview( customer_id="customerId", plan_id="planId", ) print(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\tresponse, err := client.V1.Subscriptions.Preview(context.TODO(), stigg.V1SubscriptionPreviewParams{\n\t\tCustomerID: \"customerId\",\n\t\tPlanID: \"planId\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.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.subscriptions.SubscriptionPreviewParams; import io.stigg.models.v1.subscriptions.SubscriptionPreviewResponse; public final class Main { private Main() {} public static void main(String[] args) { StiggClient client = StiggOkHttpClient.fromEnv(); SubscriptionPreviewParams params = SubscriptionPreviewParams.builder() .customerId("customerId") .planId("planId") .build(); SubscriptionPreviewResponse response = client.v1().subscriptions().preview(params); } } - lang: Ruby source: >- require "stigg" stigg = Stigg::Client.new(api_key: "My API Key") response = stigg.v1.subscriptions.preview(customer_id: "customerId", plan_id: "planId") puts(response) - lang: C# source: |- using System; using Stigg.Client; using Stigg.Client.Models.V1.Subscriptions; StiggClient client = new(); SubscriptionPreviewParams parameters = new() { CustomerID = "customerId", PlanID = "planId", }; var response = await client.V1.Subscriptions.Preview(parameters); Console.WriteLine(response); - lang: CLI source: |- stigg v1:subscriptions preview \ --api-key 'My API Key' \ --customer-id customerId \ --plan-id planId components: schemas: PreviewSubscriptionRequestDto: type: object properties: customerId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$ description: Customer ID payingCustomerId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$ description: Paying customer ID for delegated billing resourceId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Resource ID for multi-instance subscriptions planId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Plan ID billingPeriod: type: string enum: - MONTHLY - ANNUALLY description: Billing period (MONTHLY or ANNUALLY) billingCountryCode: type: string maxLength: 255 description: ISO 3166-1 country code for localization unitQuantity: type: integer minimum: 0 description: Unit quantity for per-unit pricing. Minimum is 0 (zero is allowed). billableFeatures: type: array items: type: object properties: featureId: type: string maxLength: 255 description: Feature ID quantity: type: number minimum: 0 description: Quantity of feature units. Minimum is 0 (zero is allowed). required: - featureId - quantity additionalProperties: false title: BillableFeature description: Feature with quantity description: Billable features with quantities charges: type: array items: type: object properties: type: type: string enum: - FEATURE - CREDIT description: Charge type id: type: string maxLength: 255 description: Charge ID quantity: type: number minimum: 0 description: Charge quantity. Minimum is 0 (zero is allowed). required: - type - id - quantity additionalProperties: false title: SubscriptionCharge description: >- A charge selection for a subscription (references a catalog charge with a quantity). description: One-time or recurring charges addons: type: array items: type: object properties: id: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Addon ID quantity: type: integer minimum: 0 description: Number of addon instances required: - id - quantity title: SubscriptionAddon description: Addon configuration description: Addons to include startDate: type: string format: date-time description: Subscription start date billingInformation: type: object properties: taxRateIds: type: array items: type: string maxLength: 255 description: Tax rate IDs from billing provider description: Tax rate IDs from billing provider taxPercentage: type: number minimum: 0 maximum: 100 description: Tax percentage to apply billingAddress: type: object properties: city: type: string country: type: string line1: type: string line2: type: string postalCode: type: string state: type: string description: Billing address metadata: type: object additionalProperties: type: string description: Additional billing metadata chargeOnBehalfOfAccount: type: string maxLength: 255 description: Connected account ID for platform billing isBackdated: default: false type: boolean description: Whether subscription is backdated isInvoicePaid: default: false type: boolean description: Whether invoice is already paid invoiceDaysUntilDue: type: number description: Days until invoice is due integrationId: type: string maxLength: 255 description: Billing integration ID prorationBehavior: type: string enum: - INVOICE_IMMEDIATELY - CREATE_PRORATIONS - NONE description: Proration behavior taxIds: type: array items: type: object properties: type: type: string maxLength: 255 description: Tax exemption type (e.g., vat, gst) value: type: string maxLength: 255 description: Tax exemption identifier value required: - type - value additionalProperties: false title: TaxExempt description: Tax exemption identifier description: Customer tax IDs additionalProperties: false title: SubscriptionBillingInfo description: Billing and tax configuration scheduleStrategy: type: string enum: - END_OF_BILLING_PERIOD - END_OF_BILLING_MONTH - IMMEDIATE description: When to apply subscription changes appliedCoupon: type: object properties: couponId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Stigg coupon ID billingCouponId: type: string maxLength: 255 description: Billing provider coupon ID promotionCode: type: string maxLength: 255 description: Promotion code to apply discount: type: object properties: name: type: string maxLength: 255 description: Discount name description: type: string maxLength: 255 description: Ad-hoc discount durationInMonths: type: number minimum: 1 description: Duration in months percentOff: type: number minimum: 1 maximum: 100 description: Percentage discount amountsOff: type: array items: 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 additionalProperties: false nullable: true description: Fixed amounts off by currency additionalProperties: false title: SubscriptionCouponDiscount description: Ad-hoc discount configuration configuration: type: object properties: startDate: type: string format: date-time description: Coupon start date additionalProperties: false description: Coupon timing configuration additionalProperties: false title: SubscriptionCoupon description: Coupon or discount to apply trialOverrideConfiguration: type: object properties: isTrial: type: boolean description: Whether to start as trial trialEndDate: type: string format: date-time description: Trial end date trialEndBehavior: type: string enum: - CONVERT_TO_PAID - CANCEL_SUBSCRIPTION description: Behavior when trial ends required: - isTrial additionalProperties: false title: TrialOverrideConfiguration description: Trial period override settings billingCycleAnchor: type: string enum: - UNCHANGED - NOW description: Billing cycle anchor behavior for the subscription required: - customerId - planId additionalProperties: false title: PreviewSubscriptionRequest description: >- Preview subscription pricing and invoice details before provisioning. Returns calculated totals, line items, taxes, and discounts based on the provided subscription configuration. PreviewSubscriptionResponseDto: type: object properties: data: type: object properties: immediateInvoice: type: object properties: total: type: number description: Invoice total subTotal: type: number description: Subtotal before discounts discount: type: number description: Total discount amount tax: type: number description: Tax amount currency: type: string maxLength: 255 description: Currency code nullable: true billingPeriodRange: type: object properties: start: type: string format: date-time description: Billing period start date end: type: string format: date-time description: Billing period end date required: - start - end description: Billing period covered lines: type: array items: type: object properties: description: type: string maxLength: 255 description: Line item description quantity: type: number description: Quantity unitPrice: type: number description: Price per unit subTotal: type: number description: Line subtotal currency: type: string maxLength: 255 description: Currency code required: - description - unitPrice - subTotal - currency title: PriceLineItem description: Invoice line item description: Line items discounts: type: array items: type: object properties: description: type: string maxLength: 255 description: Discount description amount: type: number description: Discount amount currency: type: string maxLength: 255 description: Currency code required: - description - amount - currency title: Discount description: Applied discount amount description: Applied discounts discountDetails: type: object properties: code: type: string maxLength: 255 description: Promo code used percentage: type: number description: Percentage discount fixedAmount: type: number description: Fixed discount amount title: InvoiceDiscountDetails description: Discount breakdown required: - total - subTotal description: Invoice due immediately recurringInvoice: type: object properties: total: type: number description: Invoice total subTotal: type: number description: Subtotal before discounts discount: type: number description: Total discount amount tax: type: number description: Tax amount currency: type: string maxLength: 255 description: Currency code nullable: true billingPeriodRange: type: object properties: start: type: string format: date-time description: Billing period start date end: type: string format: date-time description: Billing period end date required: - start - end description: Billing period covered lines: type: array items: type: object properties: description: type: string maxLength: 255 description: Line item description quantity: type: number description: Quantity unitPrice: type: number description: Price per unit subTotal: type: number description: Line subtotal currency: type: string maxLength: 255 description: Currency code required: - description - unitPrice - subTotal - currency title: PriceLineItem description: Invoice line item description: Line items discounts: type: array items: type: object properties: description: type: string maxLength: 255 description: Discount description amount: type: number description: Discount amount currency: type: string maxLength: 255 description: Currency code required: - description - amount - currency title: Discount description: Applied discount amount description: Applied discounts discountDetails: type: object properties: code: type: string maxLength: 255 description: Promo code used percentage: type: number description: Percentage discount fixedAmount: type: number description: Fixed discount amount title: InvoiceDiscountDetails description: Discount breakdown required: - total - subTotal title: SubscriptionPreviewInvoice description: Recurring invoice preview billingPeriodRange: type: object properties: start: type: string format: date-time description: Billing period start date end: type: string format: date-time description: Billing period end date description: Billing period range isPlanDowngrade: type: boolean description: Whether this is a downgrade hasScheduledUpdates: type: boolean description: Whether updates are scheduled freeItems: type: array items: type: object properties: id: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Addon ID quantity: type: integer minimum: 0 description: Number of addon instances required: - id - quantity title: SubscriptionAddon description: Addon configuration description: Free items included required: - immediateInvoice title: SubscriptionPreview description: Pricing preview with invoices 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 - GovernanceNotEnabled 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 ````