Subscriptions

Jupico Subscriptions are for ongoing recurring billing built from reusable plan templates.

The easiest way to think about the model is:

Plan = the reusable contract template
Subscription = one customer enrolled in that plan
Customer + payment token + plan = the three inputs needed to subscribe someone

Once those pieces are in place, Jupico can run the recurring billing flow according to the plan’s terms.

This is different from Installments:

Subscriptions are for ongoing recurring services, memberships, dues, or other repeat billing models.
Installments are for a fixed amount that will be collected over a defined number of payments and then end.

Related endpoints

Plan endpoints

Subscription endpoints

Query endpoints

Overview

A subscription flow in Jupico is built in two layers:

Plan layer — define the recurring commercial terms once
Subscription layer — enroll a specific customer into that plan

That means a plan should be treated as the reusable billing definition, while the subscription should be treated as the customer-specific execution of that definition.

At a high level, the platform creates a plan, collects a payment token, associates that plan with a customer, and then lets Jupico handle the recurring billing lifecycle from there.

Key concepts

Plan

A plan is the reusable recurring contract template.

This is where the recurring billing rules belong. The plan defines the offer that multiple customers can subscribe to.

Examples of what typically belongs at the plan layer:

recurring commercial terms
billing cadence
service conditions
other reusable rules that should stay consistent across subscribers

Subscription

A subscription is the customer-specific enrollment into a plan.

This is the actual live recurring arrangement for one customer. It represents the execution of the plan for that customer.

Customer

A customer is the person or business being enrolled into the recurring plan.

Customer creation and maintenance happen outside the Subscriptions API itself, but a real subscription flow depends on having the right customer record in place.

Payment token

A payment token is the saved card or bank-account token that Jupico will use for recurring charges.

If the customer changes their funding source later, you do not need to recreate the subscription. Instead, update the payment token on the existing subscription.

Renewal visibility

Subscription operations are not limited to create and activate. The Query API also gives you an operational view of plans and subscriptions, including service terms and renewal dates.

Activation state

Plans and subscriptions each have their own lifecycle controls.

That gives you flexibility to:

prepare a plan before offering it
enable or disable a plan for future signups
activate or deactivate customer subscriptions independently

What you need before creating a subscription

Before you create a subscription, make sure you have these three things:

A customer
A payment token
A plan

That is the core mental model for this feature.

Once those inputs exist, the subscription can be created and managed through the recurring billing engine.

Typical lifecycle

1. Define the recurring offer

Start by deciding what the recurring product or service should look like:

what the customer is buying
how often it should renew
what commercial terms should stay the same for every subscriber

2. Create the plan

Create the reusable plan that represents that recurring offer.

Think of this step as writing the contract template that will later be reused across subscribers.

3. Activate the plan when it is ready for use

Once the recurring offer is ready to be sold, activate the plan so it can be used for new subscriptions.

4. Create or identify the customer

Make sure the correct customer record exists for the person or business being enrolled.

5. Collect and store the payment token

Capture the payment method through the appropriate tokenization flow so you have a reusable card or bank-account token.

6. Create the subscription

Create the subscription by associating:

the customer
the payment token
the plan

This is the point where the reusable contract becomes a live, customer-specific recurring billing arrangement.

7. Activate the subscription

If your flow separates creation from go-live, activate the subscription when you are ready for recurring billing to begin.

8. Use query endpoints for support and operations

Use the Query API to:

review active and inactive subscriptions
inspect plan details
check service terms
monitor renewal timing

9. Maintain the subscription over time

As real-world billing changes happen, you can:

update plan details
deactivate plans or subscriptions
delete records when appropriate
update the subscription’s payment token when the customer changes payment method

When to use subscriptions

Use Subscriptions when:

the billing model is ongoing rather than fixed-payoff
the same recurring offer should be reused across many customers
you want a reusable plan template and customer-specific enrollments
you want lifecycle controls around plans and subscriptions
you want renewal and service-term visibility in the query layer

Use Installments instead when:

there is a fixed total amount to collect
the number of payments is known in advance
the payment plan ends once the total is collected

Handling custom billing models

Subscriptions work best when the recurring business model fits a reusable plan.

For custom billing rules — such as anniversary billing, special prorating logic, or cadences that do not fit the plan model — the best approach is often a hybrid design:

keep long-term recurring billing inside the Jupico subscription model when possible
handle one-off alignment logic in the platform layer when necessary

Examples:

charge a separate initial payment to align a customer to a future renewal date
calculate any prorated amount in the platform before creating the long-term subscription
use native subscriptions for the ongoing recurring portion after the customer is aligned