Subscriptions

Subscriptions are for ongoing recurring billing. The core model has two layers:

Plan = reusable contract template
Subscription = one customer enrolled in that plan

A real subscription needs three inputs:

a customer;
a payment token;
a plan.

After those pieces exist, Jupico can run the recurring billing lifecycle according to the plan configuration.

Subscriptions vs installments

Use Subscriptions when the customer is paying for an ongoing service, membership, dues program, or other repeat-billing arrangement.

Use Installments when the customer is paying toward a fixed total that ends after a defined number of payments.

Plan layer

The plan defines the reusable billing terms. It is where the recurring offer belongs.

A plan can include:

name and description;
schedules;
billing cadence;
pricing model;
service terms;
feature or benefit configuration;
activation state.

Subscription layer

The subscription enrolls a specific customer into a plan. It connects the plan to:

the customer;
the payment token;
optional schedule-level selections or quantities;
lifecycle state;
renewal timing.

Schedules and pricing models

Schedules define billing phases within a plan. Pricing models define where the amount comes from.

Use these conceptual groups:

Pricing group	Models	Meaning
Plan-defined	`free`, `flat`	The plan fully defines the amount.
Customer-selected	`flatTiered`, `perModule`, `perUsageTiered`	The plan defines options; the subscription selects the applicable option.
Quantity-driven	`perUsageQuantity`, `perUsageVolume`	The subscription or usage data provides the quantity/volume applied to plan rules.

Confirm exact schema details in the API Reference before publishing deep pricing examples.

Typical lifecycle

Define the recurring offer.
Create the plan.
Activate the plan when it is ready to sell.
Create or identify the customer.
Collect a reusable payment token.
Create the subscription.
Activate the subscription if your flow separates create from activate.
Monitor subscription status, service terms, and renewal dates.
Update the subscription payment token if the customer changes payment method.
Deactivate or delete the subscription when needed.

Custom billing rules

Subscriptions work best when the recurring business model fits a reusable plan. For custom anniversary billing, proration, or one-off alignment rules, use a hybrid model:

handle the one-time alignment amount in your platform;
create the ongoing Jupico subscription for future recurring charges;
keep renewal tracking and payment-token maintenance inside the subscription lifecycle.

Needs confirmation before publishing deep-dive content

Confirm schedule frequency behavior beyond the currently documented examples.
Confirm required fields for paymentToken versus token in the API schema.
Confirm whether selectedModules is an array or string.
Confirm perUsageQuantity field naming.
Confirm the full set of supported billing cadences and proration behavior.