Hi,
I am currently implementing a recurring payment feature using the Apple Pay JS API.
Based on the official demo (https://applepaydemo.apple.com/apple-pay-js-api), it appears that the recurringPaymentRequest object only supports a maximum of two stages: trialBilling and regularBilling.
However, our service requires a multi-stage billing model with three or more different cycles/amounts as shown below:
Example Schedule:
- Stage 1: 2,000 JPY (2026-03-01 to 2026-04-01)
- Stage 2: 1,500 JPY (2026-04-01 to 2026-10-01)
- Stage 3: 1,000 JPY (2026-10-01 to 2027-10-01)
- Stage 4: 500 JPY (Thereafter)
Questions: Is there any way to directly define and display three or more different billing cycles/amounts on the Apple Pay payment sheet?
If the API is strictly limited to two stages, what is the Apple-recommended way to provide transparency for such complex schedules while remaining compliant with the guidelines? For instance, is it acceptable to set the final amount in regularBilling and explain the preceding stages in the billingAgreement or paymentDescription fields?
I would appreciate any insights or official guidance on this.
Best regards,
Hi @hisayama,
You wrote:
Is there any way to directly define and display three or more different billing cycles/amounts on the Apple Pay payment sheet? [...]
There is no supported way to achieve this with the current Apple Pay JS or PassKit APIs. Please submit a report via Feedback Assistant with your use case and examples, for the Apple Pay team to consider your suggestions.
Then, you wrote:
[...] If the API is strictly limited to two stages, what is the Apple-recommended way to provide transparency for such complex schedules while remaining compliant with the guidelines? For instance, is it acceptable to set the final amount in regularBilling and explain the preceding stages in the billingAgreement or paymentDescription fields? [...]
The expected approach also provides the best experience for your customers—show the user their ultimate ongoing commitment in regularBilling, then fully disclose the path to get there in billingAgreement.
Your decreasing-price model can be represented clearly with this approach as well—use trialBilling for Stag 1, regularBilling for the final 500 JPY rate, and enumerate all intermediate stages clearly in billingAgreement.
For example, your specific schedule (2,000 JPY -> 1,500 -> 1,000 -> 500 JPY) can be structured like so:
const recurringPaymentRequest = {
// Short plan label
paymentDescription: "Tiered Membership Plan",
// Stage 1 in trialBilling
trialBilling: {
label: "Month 1 Rate (2026-03-01 to 2026-04-01)",
amount: "2000",
type: "final",
paymentTiming: "recurring",
recurringPaymentIntervalUnit: "month",
recurringPaymentIntervalCount: 1,
recurringPaymentStartDate: new Date("2026-03-01"),
recurringPaymentEndDate: new Date("2026-04-01"),
},
// MUST be the final/lowest ongoing amount
regularBilling: {
label: "Ongoing Rate (from 2027-10-01)",
amount: "500",
type: "final",
paymentTiming: "recurring",
recurringPaymentIntervalUnit: "month",
recurringPaymentIntervalCount: 1,
recurringPaymentStartDate: new Date("2027-10-01"),
},
// Full schedule disclosure goes here
billingAgreement:
"Your billing schedule is as follows:\n" +
"• 2026-03-01 to 2026-04-01: 2,000 JPY/month\n" +
"• 2026-04-01 to 2026-10-01: 1,500 JPY/month\n" +
"• 2026-10-01 to 2027-10-01: 1,000 JPY/month\n" +
"• 2027-10-01 onward: 500 JPY/month\n\n" +
"You will be notified by email before each billing change. " +
"Cancel anytime from your account settings.",
// Required — both technically and for compliance
managementURL: "https://example.com/account/subscription",
};
Note: Because your schedule is actually decreasing in price over time 2,000 -> 500 JPY), using the regularBilling field to represent the final 500 JPY amount is both correct and the most transparent option for your customers.
Cheers,
Paris X Pinkney | WWDR | DTS Engineer
