Subscriptions Integration Guide
Last updated:August 6, 2026
This Subscription Integration guide describes how you can schedule subscription payments. Like recurring payments, the money gets auto-debited from consumer's bank account to the merchant account in fixed time periods (e.g. weekly, monthly, quarterly, yearly). Similarly, money can be auto-credited using payouts. Subscription businesses benefit from the flexibility of creating different plans and pricing structures to meet market demands.
A subscription payment can be scheduled as a pre-authorization (PA), debit (DB) or credit (CD) transaction. Consumers are not locked into the plan they started with: at any point they can move to a higher or lower value plan or a different billing frequency, and the merchant reschedules the existing subscription to match, no cancellation required.
A scheduled payment can still decline, and when it does, MAC Scheduler can recover it on its own. Both plans above are
ordinary SD/RS transactions, told apart only by their source field:
- Subscription plan (
source: SCHEDULER): the consumer's ongoing relationship with the merchant. Created, upgraded, downgraded, or rescheduled as many times as needed, always queryable to see which version is active right now. - Recovery plan (
source: MACRETRY): tied to one declined payment. Created automatically when a scheduled attempt comes back with a retry-later MAC, existing only to give that payment another chance.
Different lifecycles, same intent: keep the subscription alive and recover the revenue.
See the MAC Scheduler guide for the full recovery mechanics.
- To collect card data, you must be PCI-DSS compliant. To minimize your compliance requirements, use COPYandPAY Registration Tokens.
Use cases
Start subscription
The merchant collects card data from the shopper and schedules a subscription payment. You can set the value of the transaction, the schedule for when the charges should occur, and the number of times the payment transaction should happen based on your subscription plan.
How it works
1. Store the payment data
Collect the customer payment information via COPYandPAY or Server-to-Server. With any of the options, please consider having a card-on-file agreement with the shopper. It is best to tokenize the card during the cardholder (CIT) initiated payment so that a merchant (MIT) agreement is in place for the future subscription payments.
Sample request:
The tokenization response returns a registrationId. Carry that id into the schedule request below,
it is what links every future debit, reschedule, and cancellation back to this shopper's stored payment data.
2. Schedule a payment
Perform a server-to-server POST request with the registration id, payment type and the job schedule parameters
which describes when and how often the transaction should be executed. For a complete reference of the scheduling job parameters,
please check API Reference.
[job.second] [job.minute] [job.hour] [job.dayOfMonth] [job.month] [job.dayOfWeek]
| Value | Description | Allowed in |
|---|---|---|
| , | List. Specify several values. For example:
|
All fields |
| - | Range. Specify a range of values. For example:
|
All fields |
| * | Wildcard. Specify all valid values. For example:
|
All fields |
| ? | Question mark. Specify no value. Can only be used in the dayOfMonth and dayOfWeek fields. Used when you wish to specify a particular value in one of those fields, but not the other. For example:
|
job.dayOfMonth job.dayOfWeek |
| / | Step. Specify increments (value/value_to_increment). For example:
|
All fields |
| L | Last. Specify the last day of the month or week. For example:
|
job.dayOfMonth job.dayOfWeek |
| W | Nearest weekday. Specify the weekday (Monday-Friday) nearest the given day. For example:
|
job.dayOfMonth |
| # | Weekday of the month. Specify "the nth Sun-Sat day of the month". For example, the value of:
|
job.dayOfWeek |
Sample request:
3. We execute the transaction for you
The scheduled payment is executed automatically at the defined time using the stored payment information and subscription plan.
4. Review the subscription plan
Query the schedule using the schedule ID. Watch plan.active in the result: green means this plan is the active one, red means it has been replaced or cancelled.
Sample request:
Update subscription plan
A consumer can decide to change plans at any point during an active subscription, moving to a higher or lower value tier,
or a more or less frequent billing cycle. Handle this with the RS (Reschedule) payment type, which updates the
pricing, timing, or structure of the existing schedule in place, without cancelling it and starting over. Submit your updated
plan to the /scheduling/v1/schedules/{id}/reschedule endpoint, referencing either the original schedule (SD)
or your most recent reschedule (RS). Each update is recorded as a step in the same session, giving you a continuous
history of how the plan has changed over time.
How it works
Reschedule an existing plan
Move the consumer to a new amount or frequency on the active schedule, without cancelling it.
We execute the transaction for you
Execute the updated subscription payment at the scheduled time.
1. Reschedule an existing plan
Submit your updated plan to the /scheduling/v1/schedules/{id}/reschedule endpoint using the RS payment type,
referencing either the original schedule (SD) or your most recent reschedule (RS). The new plan
takes effect immediately within the same active session, preserving the full change history without disrupting your customers'
experience.
For example, a consumer on the Digital plan upgrades to Print & Digital, or asks to switch from monthly to quarterly
billing. Either way, submit an RS request referencing the original schedule, no need to cancel and rebuild.
You can chain multiple rescheduling requests in sequence, with each new RS referencing the previous one, for
example if the consumer later downgrades again or changes frequency a second time.
Sample request:
The reschedule response returns a new id for the RS. Its plan.active becomes
true, and the schedule it replaced (the original SD or an earlier RS) flips to plan.active: false,
only one entry in the chain is ever the active plan at a time.
2. We execute the transaction for you
The scheduled payment is executed automatically at the defined time using the stored payment information and subscription plan.
3. Review the subscription plan
Query the reschedule ID to confirm the updated subscription plan is in effect. Watch plan.active in the result: green confirms the new plan is live, red means you're looking at a plan that has already been superseded.
Sample request:
Cancel subscription
The merchant scheduled one or multiple subscription payments. You can cancel any of the subscriptions.
How it works
1. List subscriptions
Perform a server-to-server GET request with the registration id to retrieve all scheduling records, including the
original schedule (SD), any plan updates (RS), and cancellations (DS). Use this to identify
the schedule ID you want to reference when cancelling.
Sample request:
Only one record in the returned list has plan.active: true, that is the current, live plan.
Reference that record's id (or any earlier SD/RS in the same chain) when you cancel.
2. Cancel the subscription
Send a de-scheduling (DS) request specifying any schedule ID belonging to the subscription, the original
SD or any subsequent RS. Cancelling any one of them cancels the entire subscription and stops
all future scheduled payments.
Sample request: