Prorations

A proration creates an invoice to account for unused or additional value when a merchant changes, pauses, or cancels a subscription during a billing cycle.

Use proration only on a subscription that has started and is not in the draft state.

The Fixed-price subscriptions defines the separate LedgerPro Basic and LedgerPro Plus plans, priced at PKR 5,000.00 and PKR 8,000.00 per month. When a customer upgrades during a cycle, XPay compares the consumed and remaining values under the two plans.

Prorate an update immediately#

Use invoice_now with Manage a fixed-price subscription:

PATCH {{base_url}}/public/v1/subscription/{subscription_id}

{
  "plan_id": "{{new_plan_id}}",
  "proration": {
    "behaviour": "invoice_now"
  }
}

XPay compares the current cycle's consumed value with the remaining value under the updated billing terms and creates a proration invoice immediately.

The proration invoice identifies whether the calculated amount represents:

• A payment due from the customer, or
• A refund associated with a previously paid invoice.

Use the Invoices and recurring payments to retrieve the proration invoice and perform the required payment or refund action.

Pause with proration#

POST {{base_url}}/public/v1/subscription/{subscription_id}/pause

{
  "type": "immediate",
  "proration": true
}

XPay creates a draft proration invoice for the remaining cycle value, changes the subscription to paused, and stops upcoming billing.

Request proration before cancellation#

POST {{base_url}}/public/v1/subscription/{subscription_id}/cancel

{
  "proration": true,
  "cancellation_reason": "Customer changed service"
}

This request creates a draft proration invoice and returns before cancelling the subscription. After the merchant handles that invoice, send a separate cancellation request without proration: true to cancel the subscription.

Reconcile the result#

Store the proration invoice ID and retrieve the invoice to determine:

• Amount and currency
• Payment or refund direction
• Related previously paid invoice, when present
• Current invoice state

Don't change customer access based only on the existence of a proration invoice. Use the returned subscription and invoice states.