--- title: "Preview a subscription by subscription key" method: POST path: "/v1/subscriptions/{subscription-key}/preview" tags: ["Subscriptions"] --- # Preview a subscription by subscription key `POST /v1/subscriptions/{subscription-key}/preview` Describes how to preview an existing subscription to view information about existing and future invoices or credit memos. **Note**: The `Zuora-Version` parameter must be `207.0` or later. ## Path parameters - `subscription-key` string, required ## Headers - `Accept-Encoding` string - `Content-Encoding` string - `Zuora-Track-Id` string - `Zuora-Entity-Ids` string - `Zuora-Version` string ## Request body - PreviewExistingSubscriptionRequest — Preview the existing subscription by subscription ID or number. - `previewStartDate` PreviewStartDate — The start date of the preview. - `previewStartDatePolicy` 'startOfTerm' | 'today' | 'specificDate' — The options on how the preview start date is calculated. - If you set this field to `startOfTerm`, the preview start date is the start date of the subscription term. - If you set this field to `today`, the preview start date is today. - If you set this field to `specificDate`, you must specify a specific date in the `specificDate` field. The date must be in the format `yyyy-mm-dd`. - `specificDate` string — The specific date for the preview start date. Required if `previewStartDatePolicy` is `specificDate`. - `previewThroughDate` PreviewThroughDate — The preview through date. - `previewThruDatePolicy` 'nextBillingPeriods' | 'endOfTerm' | 'specificDate' — The options on how the preview through date is calculated. - If you set this field to `nextBillingPeriods`, you must specify the number of billing periods to preview in the `nextBillingPeriods` field. - If you set this field to `endOfTerm`, the preview through date is the end date of the subscription term. - If you set this field to `specificDate`, you must specify a specific date in the `specificDate` field. The date must be in the format `yyyy-mm-dd`. - `nextBillingPeriods` number — The number of billing periods to preview. Required if `previewThruDatePolicy` is `nextBillingPeriods`. - `specificDate` string — The specific date for the preview start date. Required if `previewThruDatePolicy` is `specificDate`. - `quantityForUsageCharges` QuantityForUsageCharges[] — Container for usage charges. - `chargeId` string — The ID of the subscription charge. - `quantity` number — The quantity of the subscription charge. - `skipTax` boolean — If set to `true`, the system will bypass the tax calculation during subscription preview. ## Response `200` OK - PreviewExistingSubscriptionResponse - `processId` string — The ID of the process that handles the operation. - `reasons` object[] — The container of the error code and message. This field is available only if the `success` field is `false`. - `code` string — The error code of response. - `message` string — The detail information of the error response - `requestId` string, uuid — Unique identifier of the request. - `success` boolean — Indicates whether the call succeeded. - `invoices` PreviewExistingSubscriptionResultInvoices[] — Container for invoices. - `invoiceNumber` string — The invoice number. - `amount` number, double — Invoice amount. - `amountWithoutTax` number, double — Invoice amount minus tax. - `taxAmount` number, double — The tax amount of the invoice. - `targetDate` string, date — Date through which to calculate charges if an invoice is generated, as yyyy-mm-dd. - `invoiceItems` PreviewExistingSubscriptionInvoiceItemResult[] — The container for invoice items. - `serviceStartDate` string, date — Service start date as yyyy-mm-dd. If the charge is a one-time fee, this is the date of that charge. - `serviceEndDate` string, date — End date of the service period for this item, i.e., the last day of the period, as yyyy-mm-dd. - `amountWithoutTax` number, double — Invoice amount minus tax. - `taxAmount` number, double — The tax amount of the invoice item. - `chargeDescription` string — Description of the charge. - `chargeName` string — Name of the charge. - `chargeNumber` string — Available when the `chargeNumber` field was specified in the request or when the order is amending an existing subscription. - `productName` string — Name of the product. - `productRatePlanChargeId` string — The ID of the product rate plan charge. - `processingType` 'Charge' | 'Discount' | 'Tax' — The processing type of the invoice item. - `unitPrice` number, double — The unit price of the charge. - `quantity` number — The quantity of the charge. - `unitOfMeasure` string, nullable — The unit of measure of the charge. - `discountDetails` PreviewExistingSubscriptionDiscountDetails[] — Container for discount details. - `discountChargeName` string — The charge name of the discount. - `discountChargeNumber` string — The charge number of the discount. - `discountRate` number — The discount rate. - `serviceStartDate` string, date — Start date of the service period for this discount charge. - `serviceEndDate` string, date — End date of the service period for this discount charge. - `status` 'Draft' | 'Posted' | 'null', nullable — The status of the invoice. - `isFromExistingInvoice` boolean — Indicates whether the invoice information is from an existing invoice. - `creditMemos` PreviewExistingSubscriptionResultCreditMemos[] — Container for credit memos. **Note**: This field is only available if you have the Invoice Settlement feature enabled. - `creditMemoNumber` string — The credit memo number. - `amount` number, double — Credit memo amount. - `amountWithoutTax` number, double — Credit memo amount minus tax. - `taxAmount` number, double — The tax amount of the credit memo. - `targetDate` string, date — Date through which to calculate charges if a credit memo is generated, as yyyy-mm-dd. - `creditMemoItems` PreviewExistingSubscriptionCreditMemoItemResult[] — Container for credit memo items. - `serviceStartDate` string, date — Service start date as yyyy-mm-dd. If the charge is a one-time fee, this is the date of that charge. - `serviceEndDate` string, date — End date of the service period for this item, i.e., the last day of the period, as yyyy-mm-dd. - `amountWithoutTax` number, double — Credit memo amount minus tax. - `taxAmount` number, double — The tax amount of the credit memo item. - `chargeDescription` string — Description of the charge. - `chargeName` string — Name of the charge. - `chargeNumber` string — Available when the `chargeNumber` field was specified in the request or when the order is amending an existing subscription. - `productName` string — Name of the product. - `productRatePlanChargeId` string — The ID of the product rate plan charge. - `processingType` 'Charge' | 'Discount' | 'Tax' — The processing type of the credit memo item. - `unitPrice` number, double — The unit price of the charge. - `quantity` number — The quantity of the charge. - `unitOfMeasure` string, nullable — The unit of measure of the charge. - `discountDetails` PreviewExistingSubscriptionDiscountDetails[] — Container for discount details. - `discountChargeName` string — The charge name of the discount. - `discountChargeNumber` string — The charge number of the discount. - `discountRate` number — The discount rate. - `serviceStartDate` string, date — Start date of the service period for this discount charge. - `serviceEndDate` string, date — End date of the service period for this discount charge. - `status` string, nullable — The status of the credit memo. - `isFromExistingCreditMemo` boolean — Indicates whether the credit memo information is from an existing credit memo. ## Other responses - `500` — Internal Server Error - `4XX` — Request Errors --- [API](https://skmtc.dev/zuora/apis/api-reference.md) · [All operations](https://skmtc.dev/zuora/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/zuora/api-reference/revisions/d11e237f3e54/schema)