MOmonei
Subscriptions

Preview Subscription Update

Changed on

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 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.

post/subscriptions/{id}/preview

Request

Request body

priceIdstring uuid

The price 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.

amountinteger

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.

intervalCountinteger

Number of intervals between subscription payments.

nextPaymentAtinteger

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.

Example request

{
  "priceId": "3c5a1f8e-2b7d-4e9a-9c41-7d2e6b0f5a13",
  "amount": 110,
  "interval": "month",
  "intervalCount": 1,
  "nextPaymentAt": 1636366897
}

Response

The proration a subscription update would settle

creditinteger required

Unused time that would be credited at the current price, in the smallest currency unit.

chargeinteger 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.

netinteger 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.

refundCappedboolean 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.

effectiveAtinteger required

The date the change would take effect.

currentPeriodEndnumber required

The end date of the current subscription period. Measured in seconds since the Unix epoch.

newPeriodEndinteger

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.

nextPaymentAtinteger

When the next payment would be taken. Present on the same changes as newPeriodEnd, and equal to it.

Example response

{
  "credit": 500,
  "charge": 1200,
  "net": 700,
  "direction": "charge",
  "effectiveAt": 1636366897,
  "currentPeriodEnd": 1636366897,
  "newPeriodEnd": 1667902897,
  "nextPaymentAt": 1667902897
}

Changes