Plans and billing cycles

A plan defines what a customer subscribes to, how frequently XPay bills the subscription, and how many invoices XPay may charge.

Create the products referenced by the plan before creating the plan. Updating a plan does not automatically update subscriptions already created under it.

Plan operations#

Create a fixed-price plan#

When you provide a plan-level amount, use major currency units with up to two decimal places. For example, 5000.50 with PKR represents PKR 5,000.50.

POST {{base_url}}/public/v1/plan

{
  "name": "LedgerPro Basic monthly",
  "interval": "month",
  "every": 1,
  "billing_cycle": "per_unit/user",
  "billing_cycle_anchor_config": {
    "day_of_month": 1
  },
  "product": [
    {
      "product_id": "{{product_id}}",
      "quantity": 1
    }
  ],
  "active": true
}

The response returns the created plan in data:

{
  "success": true,
  "responseStatus": "OK",
  "message": "Request processed successfully.",
  "data": {
    "plan_id": "xpay_plan_{{plan_id}}",
    "name": "LedgerPro Basic monthly",
    "amount": 5000,
    "currency": "PKR",
    "interval": "month",
    "every": 1,
    "billing_cycle": "per_unit/user",
    "billing_cycle_anchor_config": {
      "day_of_month": 1
    },
    "product": [
      {
        "product_id": "xpay_product_{{product_id}}",
        "quantity": 1
      }
    ],
    "active": true
  }
}

The response is shortened to the fields used in the subscription flow.

When amount and currency are omitted, XPay calculates the plan amount from the referenced product prices and quantities. Supply both fields when the plan must use a different fixed amount:

{
  "amount": 4500,
  "currency": "PKR"
}

Use the XPay API reference for the complete request and response schemas.

Create the Plus plan#

After creating the separate LedgerPro Plus product, create its monthly plan:

{
  "name": "LedgerPro Plus monthly",
  "interval": "month",
  "every": 1,
  "billing_cycle": "per_unit/user",
  "billing_cycle_anchor_config": {
    "day_of_month": 1
  },
  "product": [
    {
      "product_id": "{{ledgerpro_plus_product_id}}",
      "quantity": 1
    }
  ],
  "active": true
}

Because the Plus product costs PKR 8,000.00, this plan derives the same monthly amount. Store its plan ID separately and use it when creating a Plus subscription or Prorations.

Recurring interval#

Use interval with a positive every value to define the recurring frequency.

For accelerated subscription testing, the API also accepts minute as the interval.

Billing-cycle anchor configuration#

Use billing_cycle_anchor_config to select the calendar point used for the recurring billing schedule. Its shape depends on interval.

Monthly plans#

Provide day_of_month as an integer from 1 through 31.

{
  "interval": "month",
  "every": 1,
  "billing_cycle_anchor_config": {
    "day_of_month": 15
  }
}

Weekly plans#

Provide day_of_week as an integer from 0 through 6.

{
  "interval": "week",
  "every": 1,
  "billing_cycle_anchor_config": {
    "day_of_week": 1
  }
}

Yearly plans#

Provide month as an integer from 1 through 12 and day_of_month as an integer from 1 through 31.

{
  "interval": "year",
  "every": 1,
  "billing_cycle_anchor_config": {
    "month": 7,
    "day_of_month": 1
  }
}

Include billing_cycle_anchor_config for monthly and weekly plans. For yearly plans, XPay validates its fields when you provide it.

If the selected day doesn't exist in the target month, XPay carries the overflow into the following month. For example:

• Day 31 in a 28-day February resolves to March 3.
• Day 31 in a 29-day February resolves to March 2.
• February 29 in a non-leap year resolves to March 1.

Limit the number of invoices#

Use total_count when the subscription must stop after a defined number of invoices.

{
  "interval": "month",
  "every": 1,
  "total_count": 12
}

In this example, XPay can charge a maximum of 12 subscription invoices.

If total_count is omitted, the subscription has no invoice-count limit.

Upcoming scheduled-invoice window#

After the last slot in the current scheduled-invoice window is successfully paid or skipped, XPay creates the next five scheduled invoices.

XPay reserves the invoice IDs shown in the schedule before their corresponding invoice objects are created. Merchants can store these IDs for reconciliation, but should use the invoice screen or Invoices and recurring payments to retrieve the current invoice object and state.

Interaction with subscription start date#

The subscription's start_date, timezone, and collect_advance values determine how billing begins relative to a plan-level billing anchor. See Create a fixed-price subscription for the complete creation behavior.