--- title: "Preview Subscription Update" method: POST path: "/subscriptions/{id}/preview" tags: ["Subscriptions"] --- # Preview Subscription Update `POST /subscriptions/{id}/preview` ## Request - Base URL: `https://api.monei.com/v1` - URL: `https://api.monei.com/v1/subscriptions/{id}/preview` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Calculate what a prorated change to a subscription would settle, without applying it. Send the `priceId`, `amount`, `interval`, `intervalCount` or `nextPaymentAt` you intend to set. The response reports the credit for unused time, the charge for the new price or the extra time, and the net difference that would move. Nothing is charged, refunded or stored. Use this to show a customer the cost of a plan change, or of moving their next charge date, before they confirm it. Then apply the change with [Update Subscription](https://docs.monei.com/apis/rest/subscriptions-update/) and `prorate: true`. The figures are an estimate. Applying the change recalculates them at that moment, so a preview taken much earlier can differ. The same validation runs here as on the update, so a change this endpoint rejects would also be rejected when applied. ## Request body - PreviewSubscriptionUpdateRequest: Send at least one of `priceId`, `amount`, `interval`, `intervalCount` or `nextPaymentAt`. A request that changes none of them is rejected, because there is no difference to price. `priceId` follows the same rules as on the update. The figures come from the same calculation the update endpoint runs, and the same rules reject the same requests, so a preview that returns a settlement is one the update can apply. - `priceId` string, uuid: The [price](https://docs.monei.com/apis/rest/prices-create/) the subscription bills. The subscription copies the price's values when it is created or switched to the price. A later change to the price never changes the subscription. - `amount` integer: Amount intended to be collected by this payment. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge 1.00 USD). - `interval` 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year': Subscription interval. The `minute` and `hour` intervals are only available in test mode. - `intervalCount` integer: Number of intervals between subscription payments. - `nextPaymentAt` integer: The date when the next payment will be made. Measured in seconds since the Unix epoch. Send it on an update to move the next charge without changing the price. The date must be in the future and no more than five years ahead, and the subscription must be active or past due with a live schedule. A trialing subscription moves with `trialPeriodEnd` instead, and a paused one has to be resumed first. A pending `skipIntervalCount`, `pauseIntervalCount`, `pauseAtPeriodEnd` or `cancelAtPeriodEnd` blocks the change, because it would turn the charge at the new date into a skipped, paused or cancelled cycle instead of a payment. Clear it in the same request by sending `0`, `null` or `false` for that field. Moving the date on its own settles no money. Combine it with `prorate` to charge or refund the time that moves. ## Response `200` The proration a subscription update would settle - SubscriptionUpdatePreview - `credit` integer, required: Unused time that would be credited at the current price, in the smallest currency unit. - `charge` integer, required: Time that would be charged at the new price, in the smallest currency unit. An interval change charges the full new price rather than a fraction of it. - `net` integer, required: The computed difference, `charge` minus `credit`. This is the amount that would move, in full: a refund the period's funding cannot cover is rejected rather than reduced, so a preview that returns a settlement returns the whole of it. - `direction` 'charge' | 'refund' | 'none', required: Whether the difference would be charged, refunded, or neither. `none` means the difference rounds to zero and no money moves. - `refundCapped` boolean, required: Always `false`. A refund is now either covered in full or the change is rejected, so there is no partial refund for this to report. Do not branch on it. - `effectiveAt` integer, required: The date the change would take effect. - `currentPeriodEnd` number, required: The end date of the current subscription period. Measured in seconds since the Unix epoch. - `newPeriodEnd` integer: The end of the billing period the change would start. Present only when the change resets the period: an `interval` or `intervalCount` change, which restarts it from now, or a `nextPaymentAt` change, which moves the end to the new date. - `nextPaymentAt` integer: When the next payment would be taken. Present on the same changes as `newPeriodEnd`, and equal to it. ## Other responses - `400`: The request is incorrect or could not be processed - `401`: Unauthorized error. Please check your auth credentials - `404`: The specified resource was not found - `422`: The request was well-formed but could not be processed due to semantic errors - `500`: Unexpected server error - `503`: The service is temporarily unavailable ## Changes - **2026-10-29** `50bc7df2aa43`: 1 info - added the new optional request property `priceId` - **2026-09-21** `758592ac4b6e`: 2 info - added the new optional request property `nextPaymentAt` - response property `refundCapped` deprecated - **2026-09-11** `873825923a30`: 1 info - endpoint added [Operation history](https://skmtc.dev/monei/apis/monei-api-v1/changes/subscriptions/:id/preview/post.md) --- [API](https://skmtc.dev/monei/apis/monei-api-v1.md) - [All operations](https://skmtc.dev/monei/apis/monei-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/monei/apis/monei-api-v1/revisions/50bc7df2aa43?raw)