Reconciling subscription features

When you add or remove features on a plan, existing active subscriptions do not automatically pick up the change — their entitlements stay as they were at activation. Reconciliation converges an active subscription’s feature entitlements to the prices that subscription bills, in a single call: it provisions missing features, removes features for prices the subscription no longer bills, and synchronizes the corresponding billing. Most subscriptions bill their plan’s current prices, so reconciliation converges them to the plan’s current shape. A subscription pinned to a specific plan version bills that version’s prices instead, and reconciliation converges it to that version, not to the plan’s current default. Throughout this page, “the prices the subscription bills” means the prices on the subscription’s billing record at the moment of the call. For a subscription that follows the plan’s current version, reconciliation also targets the features of the prices in that current version. Those prices start to bill in the next period, not the current one, and their features start at the same instant. Some prices grant a feature but produce no line item — a credit-denominated price, or an already-elapsed one-time charge. Reconciliation still keeps or provisions their entitlements, and reports them with billed: false.

When to use it

Reach for reconciliation whenever a plan’s feature list drifts from what an existing active subscription actually has:

You added a feature to a plan and want existing subscribers to get it without recreating the subscription.
You removed a feature from a plan and want to stop billing existing subscribers for it and revoke their entitlement.
A prior subscription activation partially failed and left the subscription without one of the plan’s features.
You want to preview either of the above without touching billing — use dryRun: true.

You do not need reconciliation when the plan and subscription are already aligned. New subscriptions provision entitlements automatically at activation; see Automatic entitlement provisioning.

What reconciliation does

A reconciliation is a single, idempotent operation that:

Adds an entitlement (and, for metered features, its initial grant) for every feature of a price the subscription bills but is missing.
Removes the entitlement and voids the grants of any feature the subscription no longer bills.
Skips features that are already present — they are left unchanged.
Synchronizes billing by creating future line items for added prices and removing future, uninvoiced line items for removed prices.

Reconciliation mints metered feature grants as full-period grants and does not prorate for the current period. Reconciliation never modifies already-invoiced line items — it only touches future, uninvoiced periods.

Timing of a removed feature

A subscription keeps billing a price for the rest of the period it has already paid for, even after that price drops off the plan. Reconciliation does not remove the feature’s entitlement until the subscription’s own billing record for that price closes, at the end of that period. Until then, the feature stays active and is not reported as removed. Run reconciliation again after that period ends to remove the entitlement.

Timing of an added feature

This applies to a subscription that follows the plan’s current version. Reconciliation moves the subscription to the current version. The plan’s versionTransition decides when the feature starts. With end_of_current_period, the default, the feature starts at the start of the subscription’s next period, when its recurring price starts to bill. The move creates the entitlement with activeFrom at the next period start and, for a metered feature, a grant that starts at the same instant. The customer has no access to the feature before then. The entitlement already exists when reconciliation compares the features, so the response reports the feature in skipped, not in added. Reconciliation creates no line item for the current period. A credit-denominated price and an already-elapsed one-time charge never bill, but their feature also starts at the next period. Usage of a metered feature before its price starts to bill is not billed. With immediate, the move starts the feature at the reconciliation, with its full grant, and the response reports it in added. A feature that the version drops ends at the reconciliation and is reported in removed. The prices follow the rules of an immediate move. If the next billing run moved the subscription before you reconcile, the feature already has its entitlement, and the response reports it in skipped. A dryRun reports the same added feature and writes nothing: no entitlement, grant, price interval or line item. A subscription pinned to its own version does not take the new price at all. It takes a price only if the version it holds carries that price.

Making a reconciliation request

API Reference: See the Reconcile Features API endpoint for the complete request and response schema.

Send an empty body (or { "dryRun": false }) to a subscription’s reconciliation endpoint. The subscription must be active.

async function reconcileSubscription(subscriptionId, { dryRun = false } = {}) {
  const response = await fetch(
    `https://api.paygentic.io/v0/subscriptions/${subscriptionId}/reconciliations`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sk_live_YOUR_API_KEY',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ dryRun }),
    }
  );

  if (!response.ok) {
    throw new Error(`Reconciliation failed: ${response.status}`);
  }

  return response.json();
}

import requests

def reconcile_subscription(subscription_id, dry_run=False):
    url = f"https://api.paygentic.io/v0/subscriptions/{subscription_id}/reconciliations"
    headers = {
        "Authorization": "Bearer sk_live_YOUR_API_KEY",
        "Content-Type": "application/json",
    }
    response = requests.post(url, json={"dryRun": dry_run}, headers=headers)
    response.raise_for_status()
    return response.json()

curl -X POST https://api.paygentic.io/v0/subscriptions/{subscriptionId}/reconciliations \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dryRun": false}'

Previewing with dry run

Pass dryRun: true to compute the same diff without creating any entitlement, grant, or line item. The response is shaped identically to a real run and reports exactly what a subsequent real call would do. Use it to confirm the scope of a change before applying it.

{
  "dryRun": true
}

Response

The response returns a subscriptionReconciliation object describing the outcome:

{
  "object": "subscriptionReconciliation",
  "dryRun": false,
  "features": {
    "added": [
      {
        "featureId": "feat_a1b2c3d4e5f6g7h8",
        "featureKey": "advanced_reporting",
        "billed": true
      }
    ],
    "skipped": [
      {
        "featureId": "feat_i9j0k1l2m3n4o5p6",
        "featureKey": "basic_dashboard"
      }
    ],
    "removed": [
      {
        "featureId": "feat_q7r8s9t0u1v2w3x4",
        "featureKey": "legacy_export"
      }
    ],
    "failed": []
  },
  "lineItems": {
    "created": 1,
    "removed": 1
  }
}

Feature groups

added — Features the subscription was missing that were provisioned. A billed: false entry means the feature’s price does not produce a recurring line item, so the feature is entitled but not billed by this reconciliation. Examples include a credit-denominated price or an already-elapsed one-time charge.
skipped — Features the subscription already had an active entitlement for. Left unchanged. This includes a feature that a move to the plan’s current version starts at the next period, and a feature that an earlier immediate move started.
removed — Features for a price the subscription no longer bills. Their entitlement was canceled and grants voided so the subscription matches the prices it currently bills. A feature for a dropped price is not reported here until the subscription’s billing record for that price closes.
failed — Features that could not be fully provisioned. Never billed by this call. Each entry has a coded reason:
- entitlement_failed — the entitlement itself could not be created.
- grant_mint_failed — the entitlement was created but its initial metered grant could not be minted. Re-running reconciliation retries the mint safely.

Line items

created — Number of features newly billed on the subscription by this reconciliation. A dry-run preview returns the same count as the applied run.
removed — Number of features whose billing was removed from the subscription’s upcoming (not-yet-invoiced) invoice because their price is no longer on the plan.
syncFailed — Present and true when entitlements were provisioned successfully but the line-item synchronization step failed. Safe to retry.

Status codes

Status	Meaning
`201 Created`	Reconciliation applied. Feature entitlements match the plan and billing was fully synchronized.
`200 OK`	The reconciliation did not create a full set of resources. This covers a `dryRun` preview, a run where one or more features could not be provisioned (billing is withheld until they succeed), or a run whose entitlements provisioned but whose line-item synchronization failed. Safe to retry — the API does not duplicate already-provisioned entitlements or grants.
`400 Bad Request`	Request is malformed, or the subscription is not eligible. See error codes below.
`404 Not Found`	Subscription does not exist or is not visible to your merchant.
`429 Too Many Requests`	The reconciliation allowance for this subscription is spent. Wait for the number of seconds in the `retry-after` header, then send the request again.
`503 Service Unavailable`	Paygentic could not read which prices the subscription bills, so it made no change. No entitlement was cancelled and no grant was voided. Wait for the number of seconds in the `retry-after` header, then send the request again.

Error codes

SUBSCRIPTION_NOT_ACTIVE — The subscription is not in the active state. Reconciliation is only available for active subscriptions.
SUBSCRIPTION_NOT_V1_BILLING — The subscription is on Legacy Billing (billingVersion: 0). Reconciliation only applies to Standard Billing subscriptions.
SUBSCRIPTION_TIMELINE_RESOLUTION_FAILED — Paygentic could not read the subscription’s billing record. Nothing changed. Retry after the delay in the retry-after header.

Idempotency and retries

Reconciliation is safe to retry:

The API detects already-provisioned entitlements and grants and does not duplicate them.
If a previous run created an entitlement but failed to mint its initial metered grant, re-running reconciliation retries the mint on the same idempotency key. The mint is a no-op when the grant is already present.
If a run returns 200 with lineItems.syncFailed: true, retry to complete billing synchronization.
A 503 with SUBSCRIPTION_TIMELINE_RESOLUTION_FAILED changes nothing, so a retry is always safe.

Rate limits

Reconciliations are limited to 2 requests per second per subscription. Each subscription has its own allowance, so a loop over many subscriptions is not limited in total. A 429 Too Many Requests response returns the retry-after header. Wait for that number of seconds before you send the request again. See Rate limits for the buckets, the response headers, and the retry rules.

Features — Configure features and link them to plan prices
Editing prices — How other plan edits propagate to existing subscribers
Customer Lifecycle — End-to-end subscription flows

Getting Started

Authentication

Platform

Integrations

Legal

Reconciling subscription features

When to use it

What reconciliation does

Timing of a removed feature

Timing of an added feature

Making a reconciliation request

Previewing with dry run

Response

Feature groups

Line items

Status codes

Error codes

Idempotency and retries

Rate limits

​When to use it

​What reconciliation does

​Timing of a removed feature

​Timing of an added feature

​Making a reconciliation request

​Previewing with dry run

​Response

​Feature groups

​Line items

​Status codes

​Error codes

​Idempotency and retries

​Rate limits

​Related pages

When to use it

What reconciliation does

Timing of a removed feature

Timing of an added feature

Making a reconciliation request

Previewing with dry run

Response

Feature groups

Line items

Status codes

Error codes

Idempotency and retries

Rate limits

Related pages