Payment Plans

Manage recurring payment plans. A plan is an active subscription-like agreement that charges a customer on a recurring schedule.

Methods

getMany()

List payment plans with optional filters and pagination.

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

const plans = await accrupay.paymentPlans.getMany({
  merchantInternalCustomerCode: 'customer-123',
  status: PAYMENT_PLAN_STATUS.ACTIVE,
  currency: CURRENCY.USD,
  take: 20,
  skip: 0,
});

Filters

Parameter	Type	Description
id	string	Filter by AccruPay plan ID.
transactionProvider	TRANSACTION_PROVIDER	Filter by provider enum value.
transactionProviderId	string	Filter by provider record ID.
currency	CURRENCY	Filter by currency.
providerCode	string	Provider's plan identifier.
providerStatus	PAYMENT_PLAN_STATUS	Provider-reported status.
paymentMethodId	string	Plans using a specific stored payment method.
paymentMethod	PAYMENT_METHOD	Filter by payment method type.
templateId	string	Plans created from a specific template.
customerId	string	Filter by AccruPay customer ID.
providerCustomerCode	string	Provider's customer identifier.
merchantInternalCustomerCode	string	Your internal customer code.
merchantInternalPaymentPlanCode	string	Your internal plan code.
hasProviderError	boolean	Filter plans that have a provider error.
ended	boolean	Filter plans that have ended.
started	boolean	Filter plans that have started billing.
canceled	boolean	Filter canceled plans.
skip	number	Offset-based pagination offset.
take	number	Offset-based page size.
after	string	Cursor for forward pagination.
first	number	Page size for forward cursor pagination.
before	string	Cursor for backward pagination.
last	number	Page size for backward cursor pagination.
sorting	object	Sort field and direction.

---

getOne()

Fetch a single payment plan by ID.

const plan = await accrupay.paymentPlans.getOne({
  merchantPaymentPlanId: 'plan-id', // required
});

Parameter	Type	Required	Description
merchantPaymentPlanId	string	Yes	AccruPay payment plan ID.

---

createOne()

Create a new payment plan for a customer.

import { CURRENCY } from '@accrupay/node';

const plan = await accrupay.paymentPlans.createOne({
  merchantTransactionProviderId: 'provider-id', // required
  data: {
    amount: 4999n,
    currency: CURRENCY.USD,
    merchantInternalPaymentPlanCode: 'plan-sub-123',
    templateId: 'template-id',
    paymentMethodId: 'payment-method-id',
    renewalIntervalMonths: 1,
    renewalIntervalDays: 0,
    renewalIntervalYears: 0,
    endsAfterMonths: 12,
    endsAfterDays: 0,
    endsAfterYears: 0,
    trialPeriodDays: 14,
    trialPeriodMonths: 0,
    trialPeriodYears: 0,
    customer: {
      merchantInternalCustomerCode: 'customer-123',
    },
  },
});

Parameter	Type	Required	Description
merchantTransactionProviderId	string	Yes	AccruPay transaction provider ID.
data	MerchantPaymentPlanCreateSchema	Yes	Plan creation payload.

note

amount and initialAmount are bigint. Use the n suffix: 4999n = $49.99.

---

cancelOne()

Cancel an active payment plan. Both IDs are required.

await accrupay.paymentPlans.cancelOne({
  merchantPaymentPlanId: 'plan-id',           // required
  merchantTransactionProviderId: 'provider-id', // required
});

Parameter	Type	Required	Description
merchantPaymentPlanId	string	Yes	AccruPay payment plan ID.
merchantTransactionProviderId	string	Yes	AccruPay transaction provider ID.

---

syncOne()

Pull the latest plan state from the provider. Both parameters are required.

await accrupay.paymentPlans.syncOne({
  merchantTransactionProviderId: 'provider-id', // required
  providerCode: 'provider-plan-code',           // required
});

Parameter	Type	Required	Description
merchantTransactionProviderId	string	Yes	AccruPay transaction provider ID.
providerCode	string	Yes	The provider's own plan identifier.

---

Return shape

All methods return a PaymentPlan object (or a paginated list for getMany).

Identifiers and status

Field	Type	Description
id	string	AccruPay plan ID.
customerId	string	AccruPay customer ID.
merchantInternalCustomerCode	string	Your customer identifier.
merchantInternalPaymentPlanCode	string	Your plan identifier.
merchantInternalPaymentPlanDescription	string	Optional description.
status	PAYMENT_PLAN_STATUS	AccruPay status (see below).
providerStatus	string	Raw status string from the provider.
providerCode	string	Provider's plan identifier.
providerCustomerCode	string	Provider's customer identifier.
providerError	string | null	Last provider error message, if any.
providerLastSyncedAt	string	ISO timestamp of last sync.
providerLastVerifiedAt	string	ISO timestamp of last verification.

Amounts and currency

Field	Type	Description
amount	bigint	Recurring charge amount in smallest currency unit.
initialAmount	bigint	First-charge amount (may differ for setup fees).
currency	CURRENCY	ISO 4217 currency.

Schedule

Field	Type	Description
renewalIntervalDays	number	Days between renewals.
renewalIntervalMonths	number	Months between renewals.
renewalIntervalYears	number	Years between renewals.
endsAfterDays	number	Plan lifetime in days.
endsAfterMonths	number	Plan lifetime in months.
endsAfterYears	number	Plan lifetime in years.
trialPeriodDays	number	Trial length in days.
trialPeriodMonths	number	Trial length in months.
trialPeriodYears	number	Trial length in years.
periodCount	number	Number of billing periods completed.
timeAnchor	string	Billing anchor timestamp.
currentPeriodStart	string	Current period start (ISO).
currentPeriodEnd	string	Current period end (ISO).
startedAt	string | null	When billing started (ISO).
endsAt	string | null	Scheduled end date (ISO).
trialEndsAt	string | null	Trial end date (ISO).
canceledAt	string | null	Cancellation timestamp (ISO).

Relations

Field	Type	Description
paymentMethodId	string	Stored payment method used.
templateId	string | null	Template this plan was created from.
transactionProviderId	string	Associated transaction provider.
payload	object | null	Arbitrary metadata.
paymentMethod	object	Nested payment method object.
template	object | null	Nested template object.
transactionProvider	object	Nested provider object.
transactions	object[]	Transactions generated by this plan.
createdAt	string	ISO creation timestamp.
updatedAt	string	ISO last-update timestamp.

PAYMENT_PLAN_STATUS values

Value	Meaning
ACTIVE	Plan is billing normally.
CANCELED	Plan was canceled by merchant or customer.
ENDED	Plan reached its end date or period count.
PAUSED	Billing is temporarily suspended.
PENDING	Plan created but not yet started.
TRIALING	Plan is in the trial period.