Sign in

v1

latestOpenAPI 3.0.02026-07-2475182625.5 KB
Subscriptions

Preview a prorated plan change

Generates a preview of the estimated charges, credits, or refunds for a subscription before making any changes.

This endpoint returns a prorated estimate for only one subscription per request.

post/subscriptions/estimate

Request body

subscriptionstring required

Unique identifier for the subscription.

productstring

Product identifier for the subscription change.

quantityinteger

Quantity of the product.

prorateboolean

Indicates whether the subscription change should be prorated.

couponsstring[]

Array of coupon codes to be applied to the subscription.

Example request

{
  "subscription": "aBCDE12fGH3iJkL4mNOpqr",
  "product": "Hulu",
  "quantity": 1,
  "pricing": {
    "price": {
      "USD": 50,
      "EUR": 45
    }
  },
  "addons": [
    {
      "product": "extra-storage",
      "quantity": 2,
      "pricing": {
        "USD": 5,
        "EUR": 4.5
      }
    }
  ],
  "prorate": true,
  "coupons": [
    "20AMOFF"
  ]
}

Response

OK

subscriptionstring

Unique identifier for the subscription.

currencystring

The subscription currency.

timezonestring

The timezone of the subscription.

periodStartDateinteger

Start date of the current billing period in epoch milliseconds.

periodStartDateDisplaystring

Human-readable format of the start date.

periodStartDateDisplayISO8601string

ISO 8601 format of the start date.

periodEndDateinteger

End date of the current billing period in epoch milliseconds.

periodEndDateDisplaystring

Human-readable format of the end date.

periodEndDateDisplayISO8601string

ISO 8601 format of the end date.

isProratableboolean

Indicates whether this subscription change is eligible for proration.

prorationStatusstring

Indicates whether proration is available for this subscription change. When Available, the estimated charge or credit shown in this response will apply when you confirm the plan change. All other values indicate that proration cannot proceed and the reason why.

Possible values:

  • Available — Proration is available.
  • The subscription is inactive. — The subscription must be active for proration to apply.
  • The subscription is scheduled to be paused. — Proration is not available while a pause is scheduled.
  • The subscription is currently paused. — Proration cannot be applied to a paused subscription.
  • The subscription doesn't have a payment method on file. — A payment method is required for proration.
  • The payment method associated with the subscription can't be used for proration. — The current payment method does not support proration.
  • Subscriptions in the trial period are not eligible for proration. — Trial subscriptions cannot be prorated.
  • Subscriptions in the trial period are not eligible for proration. The subscription is scheduled to be paused. — Combined trial and scheduled-pause condition.
  • Managed subscriptions are not eligible for proration. — Managed subscriptions use a separate billing flow.
  • The subscription is either currently on, or has passed the re-bill and can't be prorated. — The subscription is at or past its re-bill date.
  • The subscription can't be prorated since there are no successful payments posted to it. — At least one successful payment is required.
  • The subscription can't be prorated as the payment is no longer refundable. — The refund window for the current period has closed.
endDatestring nullable

Subscription end date, if set. Null for indefinitely-renewing subscriptions.

endDateDisplaystring nullable

Human-readable format of the subscription end date.

endDateDisplayISO8601string nullable

ISO 8601 format of the subscription end date.

remainingPeriodsinteger nullable

Number of remaining billing periods. Returns -1 for indefinite renewal.

nextChargeDateinteger

Date of the next scheduled charge in epoch milliseconds.

nextChargeDateDisplaystring

Human-readable format of the next charge date.

nextChargeDateDisplayISO8601string

ISO 8601 format of the next charge date.

Example response

{
  "subscription": "aBCDE12fGH3iJkL4mNOpqr",
  "currency": "USD",
  "timezone": "UTC",
  "periodStartDate": 1679961600000,
  "periodStartDateDisplay": "12/31/25",
  "periodStartDateDisplayISO8601": "2025-01-01",
  "periodEndDate": 1682553600000,
  "periodEndDateDisplay": "12/31/25",
  "periodEndDateDisplayISO8601": "2025-12-31",
  "isProratable": true,
  "prorationStatus": "The subscription is either currently on, or has passed the re-bill and can't be prorated.",
  "remainingPeriods": -1,
  "nextChargeDate": 1682640000000,
  "nextChargeDateDisplay": "4/28/23",
  "nextChargeDateDisplayISO8601": "2025-01-08",
  "discountTotals": {
    "productLevelDiscountTotalDisplay": "$0.00",
    "couponLevelDiscountTotalDisplay": "$0.00"
  },
  "currentPlan": {
    "display": "Basic",
    "product": "basic",
    "billingFrequency": "1 month",
    "price": 200,
    "priceDisplay": "$200.00",
    "discountDisplay": "$0.00",
    "discounts": [
      {
        "discountValue": 20
      }
    ],
    "quantity": 1,
    "subtotal": 200,
    "subtotalDisplay": "$200.00",
    "taxDisplay": "$0.00",
    "total": 200,
    "totalDisplay": "$200.00",
    "taxPercent": 7.75,
    "taxPercentDisplay": "7.75%",
    "periodStartDate": 1679961600000,
    "periodStartDateDisplay": "12/31/25",
    "periodStartDateDisplayISO8601": "2025-01-01",
    "periodEndDate": 1679961600000,
    "periodEndDateDisplay": "12/31/25",
    "periodEndDateDisplayISO8601": "2025-01-01",
    "proratedItemCharge": 300,
    "proratedItemChargeDisplay": "$300.00",
    "proratedItemCredit": 200,
    "proratedItemCreditDisplay": "$200.00",
    "proratedItemSubtotalDisplay": "$100.00",
    "proratedItemTaxDisplay": "$0.00",
    "proratedItemTotal": 100,
    "proratedItemTotalDisplay": "$100.00",
    "addons": [
      {
        "product": "add-on-product-path",
        "quantity": 20,
        "pricing": {
          "price": {
            "USD": 5
          }
        }
      }
    ],
    "subscriptionSubtotal": 200,
    "subscriptionSubtotalDisplay": "$200.00",
    "subscriptionTaxDisplay": "$0.00",
    "subscriptionTotal": 200,
    "subscriptionTotalDisplay": "$200.00",
    "subscriptionProratedCredit": 200,
    "subscriptionProratedCreditDisplay": "$200.00"
  },
  "proposedPlan": {
    "display": "Premium",
    "product": "premium",
    "billingFrequency": "1 month",
    "price": 300,
    "priceDisplay": "$300.00",
    "discountDisplay": "$0.00",
    "discounts": [
      {
        "discountValue": 20
      }
    ],
    "quantity": 1,
    "subtotal": 300,
    "subtotalDisplay": "$300.00",
    "taxDisplay": "$0.00",
    "total": 300,
    "totalDisplay": "$300.00",
    "taxPercent": 7.75,
    "taxPercentDisplay": "7.75%",
    "periodStartDate": 1679961600000,
    "periodStartDateDisplay": "12/31/25",
    "periodStartDateDisplayISO8601": "2025-01-01",
    "periodEndDate": 1682553600000,
    "periodEndDateDisplay": "12/31/25",
    "periodEndDateDisplayISO8601": "2025-12-31",
    "proratedItemCharge": 300,
    "proratedItemChargeDisplay": "$300.00",
    "proratedItemCredit": 200,
    "proratedItemCreditDisplay": "$200.00",
    "proratedItemSubtotal": 100,
    "proratedItemSubtotalDisplay": "$100.00",
    "proratedItemTaxDisplay": "$0.00",
    "proratedItemTotal": 100,
    "proratedItemTotalDisplay": "$100.00",
    "addons": [
      {
        "product": "add-on-product-path",
        "quantity": 20,
        "pricing": {
          "price": {
            "USD": 5
          }
        }
      }
    ],
    "subscriptionSubtotal": 300,
    "subscriptionSubtotalDisplay": "$300.00",
    "subscriptionTaxDisplay": "$0.00",
    "subscriptionTotal": 300,
    "subscriptionTotalDisplay": "$300.00",
    "subscriptionProratedCharge": 300,
    "subscriptionProratedChargeDisplay": "$300.00"
  },
  "amountDue": {
    "prorationSubtotal": 100,
    "prorationSubtotalDisplay": "$100.00",
    "prorationTaxDisplay": "$0.00",
    "totalAmountDue": 100,
    "totalAmountDueDisplay": "$100.00",
    "nextChargeDate": 1682640000000,
    "nextChargeDateDisplay": "4/28/23",
    "nextChargeDateDisplayISO8601": "2025-01-08",
    "nextChargeAmount": 300,
    "nextChargeAmountDisplay": "$300.00"
  }
}