Recurring Billing is a feature that allows merchants to automatically charge customers on a predefined schedule such as weekly, monthly, yearly, or one-time, without manually creating invoices or processing payments each time.

Recurring Billing is commonly used for subscriptions, memberships, service agreements, and installment-based billing.

How Recurring Billing Works (High-Level Flow)

Configure recurring billing settings for the merchant
Create or fetch a customer
Tokenize the customer’s card
Create a recurring contract (subscription)
System automatically generates invoices and processes payments based on the schedule

Merchant-level Configuration

(Need to re-check and correct, in relevant to Merchant Application Activation API -> https://prioritycommerce.atlassian.net/browse/APIHELP-10758)

Recurring billing behavior is controlled at the merchant level. These settings determine how invoices are generated and scheduled.

The below settings can be updated via the PUT /checkout/v3/merchantsetting/{merchantId} endpoint.

API Node	Description
`invoice.interval`	Defines the recurrence interval for invoices (e.g., Once, Weekly, Monthly).
`invoice.frequency`	Defines how many times a recurring invoice should repeat.
`invoice.dayNumber`	Defines the day number for recurrence (e.g., `1` = 1st of the month).
`invoice.dayType`	Defines the type of recurrence interval — Day, Week, or Month.
`invoice.month`	Defines the specific month for recurring invoices (if applicable).
`invoice.autoGenerate`	Set to true to auto-generate recurring invoices.
`invoice.intervalValue`	Defines the numeric value of the recurrence interval (e.g., `30` = every 30 days).
`invoice.intervalLabel`	Defines the label for the interval (e.g., “Days”, “Weeks”, “Months”).

To know more, kindly refer to the Merchant Configuration and Payment Controls.

Setting Up Recurring Billing for Customers

This section explains how to create and manage a recurring billing contract for a customer.

a. Create a Customer

A Customer represents the end user (cardholder) whose payment details you want to securely store for future use. It contains identifying information such as name, email, and mobile number.

If the customer already exists, you can skip this step.

b. Generate a Card Token (Customer Card Account)

Once a Customer Profile exists, create a Customer Card Account to tokenize your card details. Use the POST /checkout/v3/customercardaccount/{customerId} endpoint.

Parameter	Required	Description
`number`	✓	13 to 17 digits of card number.
`expiryMonth`	✓	Card expiry month.
`expiryYear`	✓	Card expiry year.
`cvv`	✓	Card verification value.
`avsStreet`	✓	Billing street address line 1.
`avsZip`	✓	5-9 digit Billing zip/postal code.

Note: Both avsStreet and avsZip are used to perform Address Verification Service (AVS) checks.

The GET /checkout/v3/customercardaccount/{customerId} endpoint returns all card accounts for a customer, including:
- id: Card Account id.
- token: Secure card token for payments.

c. Create Contract

A Contract Subscription defines the full recurring agreement between the merchant and the customer.

It consists of:

Contract → Financial and commercial terms
Subscription → Billing execution and payment behavior

Follow below steps to Create Contracts for customers:

Create a Contract using the POST /checkout/v3/contractsubscription?echo=true endpoint that includes:

Parameter	Required	Description
`contract`	✓	Root object that defines the financial and scheduling details of the recurring billing contract.
`contract.merchantId`	✓	Identifier of the merchant creating the recurring contract.
`contract.frequency`	✓	Interval multiplier for billing (e.g., 1 = every cycle).
`contract.interval`		Billing cadence (Weekly, Monthly, Yearly, or Once).
`contract.totalAmount`		Total contract amount including taxes and discounts.
`contract.quantity`		Aggregate quantity of items in the contract.
`contract.billNow`		If true, charges the first payment immediately upon contract creation.
`contract.taxes`		List of taxes applied at the contract level.
`contract.discounts`		List of discounts applied to the contract.
`contract.purchases`	✓	Array of line items included in the contract.
`subscription`	✓	Root object that defines billing execution and payment behavior.
`subscription.customerId`	✓	Unique identifier of the customer associated with the contract.
`subscription.cardAccountId`	Conditional	Tokenized payment method ID (required for Autopay).
`subscription.startDate`	✓	Date when the recurring billing schedule begins.
`subscription.invoiceMethod`		Payment method used for recurring billing: `Autopay` or `Invoice`.
`subscription.sendReceipt`		Controls when payment receipts are sent (Always, Never, or Once).

Key points:

Billing Cadence Rules: The timing of the first and subsequent payments depends on schedule parameters and the initial charge type (Regular vs. Bill Now).

Term	Definition
Regular Contract	`bill_now` is `false`. First payment occurs on the first scheduled date.
Bill Now Contract	`bill_now` is `true`. First payment occurs immediately at contract creation.
6-Day Gap Rule	Enforced for Weekly/Monthly Bill Now. If the immediate payment date and next scheduled date are less than 6 days apart, the system pushes the nextBillDate by one cycle. Yearly contracts ignore this rule.
Next Bill Date	System-calculated date for the next payment execution.

contract.taxes can be managed separately. To know more, kindly refer to Sales Taxes.
contract.discounts can be managed separately. To know more, kindly refer to Discounts.

PCE captures the contract details instantly. The GET /checkout/v3/contract/{id} endpoint gives a response including detailed contract information such as amount, frequency, status, next billing date, and associated payment method:
- id: Unique identifier for the contract.
Use the GET /checkout/v3/contractsubscription/{{contractId}} endpoint to retrieve details of the subscription associated with a specific contract, including billing schedule, pricing, and duration.
Updating Recurring Billing Contract: After the contract is created, use the PUT checkout/v3/contractsubscription?id={{contractId}}&subId={{subId}} to update the Recurring Billing Contract created.
Here, the contractId will be the ID of the contract you wish to update and subId will be the subscription Id. You can modify an existing recurring billing contract, such as updating the amount, frequency, payment method, or status, without creating a new contract record.

i. Retrieving a Contract’s Payments

Retrieve the list of all payments that have been processed under a specific recurring billing contract.

Use the GET /v3/contract/payment API endpoint to fetch transaction history including amounts, dates, and payment statuses.

ii. Retrieving a Contract History

Retrieve the change history and event log for a specific contract, including updates, pauses, cancellations, or payment modifications.

Use the GET /v3/contract/history API endpoint to recive metadata such as timestamps, user IDs, and change descriptions.

iii. Contract Attachments

You can add attachments related to a contract after it has been created.

Requirements

To retrieve or associate an attachment, you must provide:

contractId – Identifier of the contract
subAttachmentId – Identifier of the specific attachment

Use following endpoints for Contract Attachments:

Add a Contract Attachment: Use POST /checkout/v3/contractattachment?id={{contractId}}&echo=true API endpoint to add file name and attachment to the created contract.
Retrieve a Contract Attachment: Use GET /checkout/v3/contractattachment?id={{contractId}}&subId={{subAttachmentId}} API endpoint to get the details of the attached document.
Deleting a Contract Attachment: Use DELETE checkout/v3/contractattachment?id={{contractId}}&subId={{subAttachmentId}} API endpoint to delete the attachment added to the contract.

Pending Items

Customer API Tryout links
Card Account API Tryout links
All other endpoints mentioned need to be linked to API tryouts