--- title: "Preview upcoming subscription charges" method: POST path: "/subscriptions/{id}/preview" tags: ["Subscriptions"] --- # Preview upcoming subscription charges `POST /subscriptions/{id}/preview` ## Request - Base URL: `https://api.smokeball.com` - URL: `https://api.smokeball.com/subscriptions/{id}/preview` - Auth: API key in header `x-api-key` and API key in header `Authorization` Returns a preview of upcoming subscription charges or refunds for any specified update to subscriptions tiers, add-ons, or interval. ## Path parameters - `id` string, required ## Request body - PreviewSubscriptionRequest - `tierId` string, uuid, nullable: Optional tier id subscription update to preview. An error is thrown if the supplied or existing add-ons are not valid for the supplied tier id. - `archieTierId` string, uuid, nullable: Optional Archie tier id subscription update to preview. Omit or supply null to preserve the current Archie tier. - `addOnIds` string[], nullable: Optional add-on ids subscription update to preview. An error is thrown if the supplied or existing add-ons are not valid for the existing or supplied tier id. - `promotionIds` string[], nullable: Optional promotion ids subscription update to preview. - `interval` string, nullable: Optional billing interval/pricing option change in subscription tier to preview. If an interval is not supplied and a tier id is supplied, the default interval option for the supplied tier will be used. If an interval is supplied but a tier is not supplied, the existing tier is used and the interval is changed. ## Response `200` When request is successful. Returns a 'SubscriptionPreview' object. - SubscriptionPreview - `immediateProrationPayment` InvoicePreview - `dueDate` string, date-time, nullable: The date when the payment is due. - `total` integer: The payment total amount. - `subTotal` integer: The payment subtotal amount. - `tax` integer: The payment tax amount. - `preTaxCredit` integer: Total pre-tax credits applied to this payment. - `previewLineItems` InvoicePreviewLineItem[], nullable: The invoice line items showing breakdown of charges. - `product` Product - `id` string, nullable: The id of the Product. - `smokeballId` string, nullable: The Smokeball id. For example the tier or add-on id. - `source` string, nullable: Source of the promotion (e.g. Stripe). - `externalProductId` string, nullable: The external id of the Product. - `smokeballProductType` 0 | 1 | 2 | 3 | 4 - `productSuite` string, nullable: The suite that the Product belongs to. - `iconIdentifier` string, nullable: Opaque icon identifier of the product. - `name` string, nullable: The name of the Product. - `description` string, nullable: The description of the Product. - `trialPeriodDays` integer, nullable: If the product is trialable, how many days it will be trialed for. Note: This will return null or 0 if the product is not trialable. - `created` string, date-time: The created date of the Product. - `updated` string, date-time: The updated date of the Product. - `prices` ProductPrice[], nullable: The prices of the Product (e.g. Monthly or Yearly). - `id` string, nullable: The id of the Price. - `externalPriceId` string, nullable: The external Price id. - `active` boolean: Returns `true` if the Price is active. - `default` boolean: Returns `true` if the Price is the default price. - `type` string: The Price type (e.g. recurring) - `name` string, nullable: The Price display name e.g. "$109 per user/month" - `amount` number, double, nullable: The per unit amount for this pricing option for the specified interval. The value is stored as cents. - `interval` string: The interval of the Price. - `meter` ProductPriceMeter - `externalMeterId` string, nullable: The external meter id to incur charges. - `eventName` string, nullable: The meter event name used to record usage. - `metadata` Metadata[], nullable: The metadata of the Price. - `key` string, nullable - `value` string, nullable - `metadata` Metadata[], nullable: The metadata of the Product. - `key` string, nullable - `value` string, nullable - `testEnvironment` boolean: Returns `true` if this Product is from the Test environment. - `active` boolean: Returns `true` if this Product is active. - `isDeleted` boolean: Returns `true` if this Product has been deleted. - `description` string, nullable: Description of this line item. - `interval` string: Billing interval associated to this line item. Possible values: None, Daily, Weekly, Monthly, Yearly. - `amount` integer: The amount charged for this line item. - `tax` integer: The tax amount in this line item. - `preTaxCredit` integer: Pre-tax credits applied to this line item. - `nextBillingCyclePayment` InvoicePreview - `dueDate` string, date-time, nullable: The date when the payment is due. - `total` integer: The payment total amount. - `subTotal` integer: The payment subtotal amount. - `tax` integer: The payment tax amount. - `preTaxCredit` integer: Total pre-tax credits applied to this payment. - `previewLineItems` InvoicePreviewLineItem[], nullable: The invoice line items showing breakdown of charges. - `product` Product - `id` string, nullable: The id of the Product. - `smokeballId` string, nullable: The Smokeball id. For example the tier or add-on id. - `source` string, nullable: Source of the promotion (e.g. Stripe). - `externalProductId` string, nullable: The external id of the Product. - `smokeballProductType` 0 | 1 | 2 | 3 | 4 - `productSuite` string, nullable: The suite that the Product belongs to. - `iconIdentifier` string, nullable: Opaque icon identifier of the product. - `name` string, nullable: The name of the Product. - `description` string, nullable: The description of the Product. - `trialPeriodDays` integer, nullable: If the product is trialable, how many days it will be trialed for. Note: This will return null or 0 if the product is not trialable. - `created` string, date-time: The created date of the Product. - `updated` string, date-time: The updated date of the Product. - `prices` ProductPrice[], nullable: The prices of the Product (e.g. Monthly or Yearly). - `id` string, nullable: The id of the Price. - `externalPriceId` string, nullable: The external Price id. - `active` boolean: Returns `true` if the Price is active. - `default` boolean: Returns `true` if the Price is the default price. - `type` string: The Price type (e.g. recurring) - `name` string, nullable: The Price display name e.g. "$109 per user/month" - `amount` number, double, nullable: The per unit amount for this pricing option for the specified interval. The value is stored as cents. - `interval` string: The interval of the Price. - `meter` ProductPriceMeter - `externalMeterId` string, nullable: The external meter id to incur charges. - `eventName` string, nullable: The meter event name used to record usage. - `metadata` Metadata[], nullable: The metadata of the Price. - `key` string, nullable - `value` string, nullable - `metadata` Metadata[], nullable: The metadata of the Product. - `key` string, nullable - `value` string, nullable - `testEnvironment` boolean: Returns `true` if this Product is from the Test environment. - `active` boolean: Returns `true` if this Product is active. - `isDeleted` boolean: Returns `true` if this Product has been deleted. - `description` string, nullable: Description of this line item. - `interval` string: Billing interval associated to this line item. Possible values: None, Daily, Weekly, Monthly, Yearly. - `amount` integer: The amount charged for this line item. - `tax` integer: The tax amount in this line item. - `preTaxCredit` integer: Pre-tax credits applied to this line item. - `quantity` integer, nullable: The number of users on the subscription. - `taxRates` TaxRate[], nullable: The current active tax rate. - `externalId` string, nullable - `name` string, nullable - `description` string, nullable - `country` string, nullable - `state` string, nullable - `rate` number, double - `behaviour` 0 | 1: The behavior set on Tax Rate. - `createdDate` string, date-time ## Other responses - `400`: When an unsupported request is made. - `404`: When subscription with specified id does not exist. - `500`: When an error occurs while updating the subscription. ## Changes - **2026-10-28** `2fe552c5d11d`: 3 info - added the new optional request property `allOf[#/components/schemas/PreviewSubscriptionRequest]/archieTierId` (media type: application/json-patch+json) - added the new optional request property `allOf[#/components/schemas/PreviewSubscriptionRequest]/archieTierId` (media type: application/json) - added the new optional request property `allOf[#/components/schemas/PreviewSubscriptionRequest]/archieTierId` (media type: application/*+json) - **2026-09-12** `30062b3c3dd5`: 2 warning - added the new `4.00` enum value to the `immediateProrationPayment/allOf[#/components/schemas/InvoicePreview]/previewLineItems/items/product/allOf[#/components/schemas/Product]/smokeballProductType/allOf[#/components/schemas/SmokeballProductType]/` response property for the response status `200` - added the new `4.00` enum value to the `nextBillingCyclePayment/allOf[#/components/schemas/InvoicePreview]/previewLineItems/items/product/allOf[#/components/schemas/Product]/smokeballProductType/allOf[#/components/schemas/SmokeballProductType]/` response property for the response status `200` [Operation history](https://skmtc.dev/smokeball/apis/smokeball-api/changes/subscriptions/:id/preview/post.md) --- [API](https://skmtc.dev/smokeball/apis/smokeball-api.md) - [All operations](https://skmtc.dev/smokeball/apis/smokeball-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smokeball/apis/smokeball-api/revisions/6e350cf667d4?raw)