--- title: "Preview upcoming subscription charges" method: POST path: "/subscriptions/{id}/preview" tags: ["Subscriptions"] --- # Preview upcoming subscription charges `POST /subscriptions/{id}/preview` 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. - `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 - `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 — Recurring payment interval type. - `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 - `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 — Recurring payment interval type. - `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. --- [API](https://skmtc.net/smokeball/apis/api.md) · [All operations](https://skmtc.net/smokeball/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smokeball/api/revisions/197984da9b42/schema)