> This page is for Developers. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://zuora.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://zuora.ferndocs.com/_mcp/server. # Preview a subscription by subscription key POST https://rest.test.zuora.com/v1/subscriptions/{subscription-key}/preview Content-Type: application/json 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. Reference: https://zuora.ferndocs.com/developers/api-reference/zuora-api/orders-and-subscriptions/subscriptions/preview-existing-subscription ## Authentication - `Authorization` header (bearer token, required) — Use `Bearer {{token}}` in the `Authorization` header for authentication. ## Servers - `https://rest.test.zuora.com` (US Developer & Central Sandbox (incl. Test Drive), default) - `https://rest.sandbox.na.zuora.com` (US API Sandbox Cloud 1) - `https://rest.apisandbox.zuora.com` (US API Sandbox Cloud 2) - `https://rest.na.zuora.com` (US Production Cloud 1) - `https://rest.zuora.com` (US Production Cloud 2) - `https://rest.test.eu.zuora.com` (EU Developer & Central Sandbox) - `https://rest.sandbox.eu.zuora.com` (EU API Sandbox) - `https://rest.eu.zuora.com` (EU Production) - `https://rest.test.ap.zuora.com` (APAC Developer & Central Sandbox) - `https://rest.ap.zuora.com` (APAC Production) ## Request ### Path parameters - `subscription-key` (string, required) — Subscription number or ID ### Headers - `Accept-Encoding` (string, optional) — Include the `Accept-Encoding: gzip` header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response. If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a `Content-Encoding` header with the compression algorithm so that your client can decompress it. - `Content-Encoding` (string, optional) — Include the `Content-Encoding: gzip` header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload. - `Zuora-Track-Id` (string, optional) — A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue. The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (`:`), semicolon (`;`), double quote (`"`), and quote (`'`). - `Zuora-Entity-Ids` (string, optional) — An entity ID. If you have [Zuora Multi-entity](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/Multi-entity) enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you should not set this header. - `Zuora-Version` (string, optional) — The minor version of the Zuora REST API. You need to set this parameter if you use the following fields: * targetDate * includeExistingDraftDocItems * previewType * taxationItems If you have the Invoice Settlement feature enabled, you need to specify this parameter. Otherwise, an error is returned. ### Body (application/json) This endpoint expects a PreviewExistingSubscriptionRequest. - `previewStartDate` (PreviewStartDate, optional) — The start date of the preview. - `previewThroughDate` (PreviewThroughDate, optional) — The preview through date. - `quantityForUsageCharges` (list of QuantityForUsageCharges, optional) — Container for usage charges. - `skipTax` (boolean, optional) — If set to `true`, the system will bypass the tax calculation during subscription preview. ## Response ### 200 OK - `processId` (string, optional) — The ID of the process that handles the operation. - `reasons` (list of PreviewExistingSubscriptionResponseReasonsItems, optional) — The container of the error code and message. This field is available only if the `success` field is `false`. - `requestId` (string, optional) — Unique identifier of the request. - `success` (boolean, optional) — Indicates whether the call succeeded. - `invoices` (list of PreviewExistingSubscriptionResultInvoices, optional) — Container for invoices. - `creditMemos` (list of PreviewExistingSubscriptionResultCreditMemos, optional) — Container for credit memos. **Note**: This field is only available if you have the Invoice Settlement feature enabled. ## Errors ### 500 Internal Server Error Internal Server Error - `reasons` (list of ErrorResponseReasonsItems, optional) ### 400 Client Request Error Request Errors - `processId` (string, optional) — The ID of the process that handles the operation. - `reasons` (list of CommonResponseReasonsItems, optional) — The container of the error code and message. This field is available only if the `success` field is `false`. - `requestId` (string, optional) — Unique identifier of the request. - `success` (boolean, optional) — Indicates whether the call succeeded. ## Types ### PreviewStartDate The start date of the preview. - `previewStartDatePolicy` (enum, optional) — 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`. - Allowed values: `startOfTerm`, `today`, `specificDate` - `specificDate` (string, optional) — The specific date for the preview start date. Required if `previewStartDatePolicy` is `specificDate`. ### PreviewThroughDate The preview through date. - `previewThruDatePolicy` (enum, optional) — 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`. - Allowed values: `nextBillingPeriods`, `endOfTerm`, `specificDate` - `nextBillingPeriods` (double, optional) — The number of billing periods to preview. Required if `previewThruDatePolicy` is `nextBillingPeriods`. - `specificDate` (string, optional) — The specific date for the preview start date. Required if `previewThruDatePolicy` is `specificDate`. ### QuantityForUsageCharges - `chargeId` (string, optional) — The ID of the subscription charge. - `quantity` (double, optional) — The quantity of the subscription charge. ### PreviewExistingSubscriptionResponseReasonsItems - `code` (string, optional) — The error code of response. - `message` (string, optional) — The detail information of the error response ### PreviewExistingSubscriptionResultInvoices - `invoiceNumber` (string, optional) — The invoice number. - `amount` (double, optional) — Invoice amount. - `amountWithoutTax` (double, optional) — Invoice amount minus tax. - `taxAmount` (double, optional) — The tax amount of the invoice. - `targetDate` (date, optional) — Date through which to calculate charges if an invoice is generated, as yyyy-mm-dd. - `invoiceItems` (list of PreviewExistingSubscriptionInvoiceItemResult, optional) — The container for invoice items. - `status` (enum, optional, nullable) — The status of the invoice. - Allowed values: `Draft`, `Posted` - `isFromExistingInvoice` (boolean, optional) — Indicates whether the invoice information is from an existing invoice. ### PreviewExistingSubscriptionResultCreditMemos - `creditMemoNumber` (string, optional) — The credit memo number. - `amount` (double, optional) — Credit memo amount. - `amountWithoutTax` (double, optional) — Credit memo amount minus tax. - `taxAmount` (double, optional) — The tax amount of the credit memo. - `targetDate` (date, optional) — Date through which to calculate charges if a credit memo is generated, as yyyy-mm-dd. - `creditMemoItems` (list of PreviewExistingSubscriptionCreditMemoItemResult, optional) — Container for credit memo items. - `status` (string, optional, nullable) — The status of the credit memo. - `isFromExistingCreditMemo` (boolean, optional) — Indicates whether the credit memo information is from an existing credit memo. ### ErrorResponseReasonsItems - `code` (string, optional) — The error code of response. - `message` (string, optional) — The detail information of the error response ### CommonResponseReasonsItems - `code` (string, optional) — The error code of response. - `message` (string, optional) — The detail information of the error response ### PreviewExistingSubscriptionInvoiceItemResult - `serviceStartDate` (date, optional) — Service start date as yyyy-mm-dd. If the charge is a one-time fee, this is the date of that charge. - `serviceEndDate` (date, optional) — End date of the service period for this item, i.e., the last day of the period, as yyyy-mm-dd. - `amountWithoutTax` (double, optional) — Invoice amount minus tax. - `taxAmount` (double, optional) — The tax amount of the invoice item. - `chargeDescription` (string, optional) — Description of the charge. - `chargeName` (string, optional) — Name of the charge. - `chargeNumber` (string, optional) — Available when the `chargeNumber` field was specified in the request or when the order is amending an existing subscription. - `productName` (string, optional) — Name of the product. - `productRatePlanChargeId` (string, optional) — The ID of the product rate plan charge. - `processingType` (enum, optional) — The processing type of the invoice item. - Allowed values: `Charge`, `Discount`, `Tax` - `unitPrice` (double, optional) — The unit price of the charge. - `quantity` (double, optional) — The quantity of the charge. - `unitOfMeasure` (string, optional, nullable) — The unit of measure of the charge. - `discountDetails` (list of PreviewExistingSubscriptionDiscountDetails, optional) — Container for discount details. ### PreviewExistingSubscriptionCreditMemoItemResult - `serviceStartDate` (date, optional) — Service start date as yyyy-mm-dd. If the charge is a one-time fee, this is the date of that charge. - `serviceEndDate` (date, optional) — End date of the service period for this item, i.e., the last day of the period, as yyyy-mm-dd. - `amountWithoutTax` (double, optional) — Credit memo amount minus tax. - `taxAmount` (double, optional) — The tax amount of the credit memo item. - `chargeDescription` (string, optional) — Description of the charge. - `chargeName` (string, optional) — Name of the charge. - `chargeNumber` (string, optional) — Available when the `chargeNumber` field was specified in the request or when the order is amending an existing subscription. - `productName` (string, optional) — Name of the product. - `productRatePlanChargeId` (string, optional) — The ID of the product rate plan charge. - `processingType` (enum, optional) — The processing type of the credit memo item. - Allowed values: `Charge`, `Discount`, `Tax` - `unitPrice` (double, optional) — The unit price of the charge. - `quantity` (double, optional) — The quantity of the charge. - `unitOfMeasure` (string, optional, nullable) — The unit of measure of the charge. - `discountDetails` (list of PreviewExistingSubscriptionDiscountDetails, optional) — Container for discount details. ### PreviewExistingSubscriptionDiscountDetails - `discountChargeName` (string, optional) — The charge name of the discount. - `discountChargeNumber` (string, optional) — The charge number of the discount. - `discountRate` (double, optional) — The discount rate. - `serviceStartDate` (date, optional) — Start date of the service period for this discount charge. - `serviceEndDate` (date, optional) — End date of the service period for this discount charge. ## Examples **Request** ```json { "previewStartDate": { "previewStartDatePolicy": "specificDate", "specificDate": "2024-01-01" }, "previewThroughDate": { "previewThruDatePolicy": "nextBillingPeriods", "nextBillingPeriods": 2 }, "quantityForUsageCharges": [ { "chargeId": "402880e78ccd1743018cce026efb002d", "quantity": 20 } ] } ``` **Response** ```json { "success": true, "invoices": [ { "invoiceNumber": "Preview Invoice", "amount": 10, "amountWithoutTax": 10, "taxAmount": 0, "targetDate": "2024-02-01", "invoiceItems": [ { "serviceStartDate": "2024-01-01", "serviceEndDate": "2024-01-31", "amountWithoutTax": 10, "taxAmount": 0, "chargeDescription": "Recurring Flat Fee Pricing", "chargeName": "Recurring_Flat Fee Pricing1628472350306", "chargeNumber": "C-0000001", "productName": "P_1628472348863", "productRatePlanChargeId": "402881547b216168017b2884182f12e7", "processingType": "Charge", "unitPrice": 10, "quantity": 1, "unitOfMeasure": null } ], "status": null, "isFromExistingInvoice": false } ], "creditMemos": [ { "creditMemoNumber": "Preview Credit Memo", "amount": 10, "amountWithoutTax": 10, "taxAmount": 0, "targetDate": "2024-02-01", "creditMemoItems": [ { "serviceStartDate": "2024-01-01", "serviceEndDate": "2024-01-31", "amountWithoutTax": 10, "taxAmount": 0, "chargeDescription": "Recurring Flat Fee Pricing", "chargeName": "Recurring_Flat Fee Pricing1628472350306", "chargeNumber": "C-0000001", "productName": "P_1628472348863", "productRatePlanChargeId": "402881547b216168017b2884182f12e7", "processingType": "Charge", "unitPrice": 10, "quantity": 1, "unitOfMeasure": null } ], "status": null, "isFromExistingCreditMemo": false } ] } ``` **SDK Code** ```python Subscriptions_PreviewExistingSubscription_example import requests url = "https://rest.test.zuora.com/v1/subscriptions/subscription-key/preview" payload = { "previewStartDate": { "previewStartDatePolicy": "specificDate", "specificDate": "2024-01-01" }, "previewThroughDate": { "previewThruDatePolicy": "nextBillingPeriods", "nextBillingPeriods": 2 }, "quantityForUsageCharges": [ { "chargeId": "402880e78ccd1743018cce026efb002d", "quantity": 20 } ] } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Subscriptions_PreviewExistingSubscription_example const url = 'https://rest.test.zuora.com/v1/subscriptions/subscription-key/preview'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"previewStartDate":{"previewStartDatePolicy":"specificDate","specificDate":"2024-01-01"},"previewThroughDate":{"previewThruDatePolicy":"nextBillingPeriods","nextBillingPeriods":2},"quantityForUsageCharges":[{"chargeId":"402880e78ccd1743018cce026efb002d","quantity":20}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Subscriptions_PreviewExistingSubscription_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://rest.test.zuora.com/v1/subscriptions/subscription-key/preview" payload := strings.NewReader("{\n \"previewStartDate\": {\n \"previewStartDatePolicy\": \"specificDate\",\n \"specificDate\": \"2024-01-01\"\n },\n \"previewThroughDate\": {\n \"previewThruDatePolicy\": \"nextBillingPeriods\",\n \"nextBillingPeriods\": 2\n },\n \"quantityForUsageCharges\": [\n {\n \"chargeId\": \"402880e78ccd1743018cce026efb002d\",\n \"quantity\": 20\n }\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Subscriptions_PreviewExistingSubscription_example require 'uri' require 'net/http' url = URI("https://rest.test.zuora.com/v1/subscriptions/subscription-key/preview") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"previewStartDate\": {\n \"previewStartDatePolicy\": \"specificDate\",\n \"specificDate\": \"2024-01-01\"\n },\n \"previewThroughDate\": {\n \"previewThruDatePolicy\": \"nextBillingPeriods\",\n \"nextBillingPeriods\": 2\n },\n \"quantityForUsageCharges\": [\n {\n \"chargeId\": \"402880e78ccd1743018cce026efb002d\",\n \"quantity\": 20\n }\n ]\n}" response = http.request(request) puts response.read_body ``` ```java Subscriptions_PreviewExistingSubscription_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://rest.test.zuora.com/v1/subscriptions/subscription-key/preview") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"previewStartDate\": {\n \"previewStartDatePolicy\": \"specificDate\",\n \"specificDate\": \"2024-01-01\"\n },\n \"previewThroughDate\": {\n \"previewThruDatePolicy\": \"nextBillingPeriods\",\n \"nextBillingPeriods\": 2\n },\n \"quantityForUsageCharges\": [\n {\n \"chargeId\": \"402880e78ccd1743018cce026efb002d\",\n \"quantity\": 20\n }\n ]\n}") .asString(); ``` ```php Subscriptions_PreviewExistingSubscription_example request('POST', 'https://rest.test.zuora.com/v1/subscriptions/subscription-key/preview', [ 'body' => '{ "previewStartDate": { "previewStartDatePolicy": "specificDate", "specificDate": "2024-01-01" }, "previewThroughDate": { "previewThruDatePolicy": "nextBillingPeriods", "nextBillingPeriods": 2 }, "quantityForUsageCharges": [ { "chargeId": "402880e78ccd1743018cce026efb002d", "quantity": 20 } ] }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Subscriptions_PreviewExistingSubscription_example using RestSharp; var client = new RestClient("https://rest.test.zuora.com/v1/subscriptions/subscription-key/preview"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"previewStartDate\": {\n \"previewStartDatePolicy\": \"specificDate\",\n \"specificDate\": \"2024-01-01\"\n },\n \"previewThroughDate\": {\n \"previewThruDatePolicy\": \"nextBillingPeriods\",\n \"nextBillingPeriods\": 2\n },\n \"quantityForUsageCharges\": [\n {\n \"chargeId\": \"402880e78ccd1743018cce026efb002d\",\n \"quantity\": 20\n }\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Subscriptions_PreviewExistingSubscription_example import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "previewStartDate": [ "previewStartDatePolicy": "specificDate", "specificDate": "2024-01-01" ], "previewThroughDate": [ "previewThruDatePolicy": "nextBillingPeriods", "nextBillingPeriods": 2 ], "quantityForUsageCharges": [ [ "chargeId": "402880e78ccd1743018cce026efb002d", "quantity": 20 ] ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://rest.test.zuora.com/v1/subscriptions/subscription-key/preview")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```