Plan Templates

A payment plan template is a reusable billing schedule definition. It describes the amount, currency, renewal interval, optional trial period, and when the plan ends. Create a template once and reference it when creating plans for individual customers.

Create a template

import AccruPay, { CURRENCY, PAYMENT_PLAN_TEMPLATE_STATUS } from '@accrupay/node';

const sdk = new AccruPay({
  apiSecret: process.env.ACCRUPAY_API_SECRET!,
});

const template = await sdk.paymentPlanTemplates.createOne({
  merchantTransactionProviderId: process.env.ACCRUPAY_PROVIDER_ID,
  data: {
    name: 'Monthly Pro',
    description: 'Pro plan billed monthly',
    amount: 2999n,           // $29.99 per billing cycle
    initialAmount: 0n,       // charged at the start (0 = none)
    currency: CURRENCY.USD,
    providerStatus: PAYMENT_PLAN_TEMPLATE_STATUS.ENABLED,

    // Renewal interval — at least one unit > 0; send 0 for the rest
    renewalIntervalDays: 0,
    renewalIntervalMonths: 1,
    renewalIntervalYears: 0,

    // Plan duration — at least one unit > 0
    endsAfterDays: 0,
    endsAfterMonths: 12,     // ends after 12 billing cycles
    endsAfterYears: 0,

    // Trial period — 0 for no trial
    trialPeriodDays: 14,     // 14-day free trial
    trialPeriodMonths: 0,
    trialPeriodYears: 0,
  },
});

console.log(template.id, template.providerStatus);

BigInt amounts

AccruPay amounts are bigint in the smallest currency unit (cents for USD). 2999n = $29.99.

Template field reference

Required fields

Field	Type	Description
`name`	`string`	Display name for the template
`amount`	`bigint`	Recurring charge amount in the smallest currency unit
`initialAmount`	`bigint`	Amount charged at plan creation (`0n` for none, or a setup/trial fee)
`currency`	`CURRENCY`	Currency for all charges on this template
`providerStatus`	`PAYMENT_PLAN_TEMPLATE_STATUS`	`ENABLED` or `DISABLED`
`renewalIntervalDays`	`number`	Days component of the renewal interval (`0` if unused)
`renewalIntervalMonths`	`number`	Months component of the renewal interval (`0` if unused)
`renewalIntervalYears`	`number`	Years component of the renewal interval (`0` if unused)
`endsAfterDays`	`number`	Days component of the plan duration (`0` if unused)
`endsAfterMonths`	`number`	Months component of the plan duration (`0` if unused)
`endsAfterYears`	`number`	Years component of the plan duration (`0` if unused)
`trialPeriodDays`	`number`	Days component of the trial period (`0` if no trial)
`trialPeriodMonths`	`number`	Months component of the trial period (`0` if no trial)
`trialPeriodYears`	`number`	Years component of the trial period (`0` if no trial)

Optional fields

Field	Type	Description
`description`	`string`	Internal description — not shown to customers
`providerParentTemplateCode`	`string`	Provider's parent template code, when applicable

Renewal & duration intervals

All renewalInterval*, endsAfter*, and trialPeriod* integers are required — send each one, using 0 for units you are not using. At least one renewalInterval* and one endsAfter* must be greater than 0.

Update a template

const updated = await sdk.paymentPlanTemplates.updateOne({
  merchantTransactionProviderId: process.env.ACCRUPAY_PROVIDER_ID,
  merchantPaymentPlanTemplateId: template.id,
  data: {
    name: 'Monthly Pro (Updated)',
    description: 'Revised pro plan',
  },
});

Updating a template does not automatically change the billing schedule of existing active plans — changes apply to newly created plans only, unless the provider propagates updates automatically.

Sync a template

Pull the latest template state from the provider. Use this after making changes in the provider dashboard or to confirm the template is active:

const synced = await sdk.paymentPlanTemplates.syncOne({
  merchantTransactionProviderId: process.env.ACCRUPAY_PROVIDER_ID,
  providerCode: template.providerCode,
});

console.log(synced.providerStatus); // ENABLED or DISABLED

Template status

Status	Description
`ENABLED`	Template is active and can be used to create new plans
`DISABLED`	Template is inactive — creating plans against it will fail

List and fetch templates

// List all templates
const templates = await sdk.paymentPlanTemplates.getMany({
  take: 20,
  skip: 0,
});

// Fetch a single template
const template = await sdk.paymentPlanTemplates.getOne({
  merchantPaymentPlanTemplateId: 'template-id',
});

Next steps

Payment Plans — create customer subscriptions using a template
Save a Card — store a payment method to use when creating plans

Create a template​

Template field reference​

Required fields​

Optional fields​

Update a template​

Sync a template​

Template status​

List and fetch templates​

Next steps​