> ## Documentation Index > Fetch the complete documentation index at: https://docs.kelviq.com/llms.txt > Use this file to discover all available pages before exploring further. # Preview a subscription update > Calculates the recurring price, next invoice line items and total, and any amount that would be charged immediately for a proposed subscription update. The request uses the same plan, charge-period, and feature fields as [Update a subscription](/api-reference/subscriptions/update-a-subscription). This endpoint does not change the subscription, create an invoice, charge the customer, or write the proposed update to Kelviq. For manual billing methods, `nextInvoice` is `null`. Amount fields without the `Units` suffix use the currency's major unit; fields ending in `Units` use its minor unit. Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment. ## OpenAPI ````yaml /api-reference/openapi.json post /subscriptions/{subscriptionId}/update/preview/ openapi: 3.0.0 info: title: kelviq API version: 1.0.0 description: >- API for interacting with kelviq services, derived from Python SDK documentation. servers: - url: https://sandboxapi.kelviq.com/api/v1 description: Sandbox — Test payments - url: https://api.kelviq.com/api/v1 description: Production — Live payments security: - bearerAuth: [] tags: - name: Products description: Catalog products. - name: Product Settings description: Per-product settings (currency, VPN/Tor/proxy, product URL). - name: Product Files description: Product images and downloadable assets. - name: Features description: Catalog features that can be granted as plan entitlements. - name: Plans description: Catalog plans (CRUD, publish, versions, prices). - name: Plan Entitlements description: Feature entitlements attached to a plan. - name: Plan Files description: Files attached to plans, and signed download links. - name: Media description: Generate presigned S3 upload URLs for product/plan images and files. - name: Partner description: Partner integration APIs (organization provisioning, lookup). - name: Charges description: >- One-time payments charged immediately against a customer's default payment method. - name: Refunds description: Full and partial refunds for paid orders. - name: Transactions description: >- Charges, refunds, disputes, and other financial movements for the authenticated organization. - name: Payment Methods description: Saved customer payment methods (cards, etc.). - name: Orders description: Completed and resolved orders for the authenticated organization. - name: Order Events description: Timeline events for a specific order. - name: Invoices description: Invoices generated for orders and subscription billing cycles. - name: Webhooks description: Delivery logs for webhook events sent to your configured endpoints. - name: Checkout Sessions description: Merchant-side view of checkout sessions created by customers. - name: Checkout Session Events description: Timeline events for a specific checkout session. paths: /subscriptions/{subscriptionId}/update/preview/: post: tags: - Subscriptions summary: Preview a subscription update description: >- Calculates the recurring price, next invoice line items and total, and any amount that would be charged immediately for a proposed subscription update. The request uses the same plan, charge-period, and feature fields as [Update a subscription](/api-reference/subscriptions/update-a-subscription). This endpoint does not change the subscription, create an invoice, charge the customer, or write the proposed update to Kelviq. For manual billing methods, `nextInvoice` is `null`. Amount fields without the `Units` suffix use the currency's major unit; fields ending in `Units` use its minor unit. operationId: previewSubscriptionUpdate parameters: - name: subscriptionId in: path required: true description: >- The unique identifier of the subscription whose update will be previewed. example: 78058918-9746-4280-9b9b-1bd5115eec6e schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PreviewSubscriptionUpdateRequest' example: planIdentifier: new_plan_enterprise chargePeriod: YEARLY features: - identifier: seats quantity: 10 responses: '200': description: >- The proposed update was priced successfully; no changes were applied. content: application/json: schema: $ref: '#/components/schemas/SubscriptionUpdatePreviewResponse' example: currency: USD recurringAmount: 50 recurringAmountUnits: 5000 amountChargedImmediately: 39.5 amountChargedImmediatelyUnits: 3950 nextInvoice: amountDue: 39.5 amountDueUnits: 3950 nextPaymentAttempt: '2026-09-01T00:00:00Z' lineItems: - description: Unused time on Pro after 12 Aug 2026 amount: -10.5 amountUnits: -1050 - description: Remaining time on Enterprise after 12 Aug 2026 amount: 50 amountUnits: 5000 '400': description: >- Bad Request - Invalid subscription update, pricing configuration, or payment-provider preview error. content: application/json: schema: $ref: '#/components/schemas/DetailErrorResponse' example: detail: Subscription does not exists components: schemas: PreviewSubscriptionUpdateRequest: type: object required: - planIdentifier - chargePeriod properties: planIdentifier: type: string description: The identifier of the proposed new plan. example: new_plan_enterprise chargePeriod: type: string enum: - ONE_TIME - MONTHLY - YEARLY - WEEKLY - DAILY - TWENTY_EIGHT_DAYS - THREE_MONTHS - SIX_MONTHS description: The proposed charging period for the subscription. example: YEARLY features: type: array items: $ref: '#/components/schemas/FeatureInput' nullable: true description: List of proposed features and quantities for the subscription. example: - identifier: seats quantity: 10 ipAddress: type: string nullable: true description: The IP Address of the customer, for location-based pricing. example: 103.154.35.20 trialEnd: type: string nullable: true description: >- The proposed trial end. Accepts `"now"` or a future ISO 8601 datetime. example: '2027-12-31 23:59:59' SubscriptionUpdatePreviewResponse: type: object properties: currency: type: string description: ISO 4217 currency code for all amounts in the response. example: USD recurringAmount: type: number description: >- The subscription's new recurring amount in the currency's major unit. example: 50 recurringAmountUnits: type: integer description: >- The subscription's new recurring amount in the currency's minor unit. example: 5000 amountChargedImmediately: type: number description: >- Amount that would be charged immediately in the currency's major unit. This is non-zero only when the update uses immediate invoicing. example: 39.5 amountChargedImmediatelyUnits: type: integer description: >- Amount that would be charged immediately in the currency's minor unit. example: 3950 nextInvoice: allOf: - $ref: '#/components/schemas/SubscriptionUpdatePreviewInvoice' nullable: true description: >- Preview of the next provider invoice. `null` for billing methods that do not provide invoice previews. DetailErrorResponse: type: object properties: detail: type: string description: A human-readable error message. example: Customer does not exist. FeatureInput: type: object required: - identifier - quantity properties: identifier: type: string description: The unique identifier for the feature. example: seats quantity: type: integer description: The desired quantity for this feature. example: 5 SubscriptionUpdatePreviewInvoice: type: object properties: amountDue: type: number description: >- Total amount due on the previewed invoice in the currency's major unit. example: 39.5 amountDueUnits: type: integer description: >- Total amount due on the previewed invoice in the currency's minor unit. example: 3950 nextPaymentAttempt: type: string format: date-time nullable: true description: >- When payment for the previewed invoice would next be attempted, when available. example: '2026-09-01T00:00:00Z' lineItems: type: array items: $ref: '#/components/schemas/SubscriptionUpdatePreviewLineItem' SubscriptionUpdatePreviewLineItem: type: object properties: description: type: string nullable: true description: Description of the invoice line item. example: Unused time on Pro after 12 Aug 2026 amount: type: number description: >- Line-item amount in the currency's major unit. Proration credits are negative. example: -10.5 amountUnits: type: integer description: >- Line-item amount in the currency's minor unit. Proration credits are negative. example: -1050 securitySchemes: bearerAuth: type: http scheme: bearer description: >- The Server API Key obtained from the kelviq application. Pass as a Bearer token in the Authorization header. Example: 'Authorization: Bearer __YOUR_API_KEY__' ````