Payment Plans

Payment plans represent recurring or scheduled billing arrangements. Templates are reusable plan definitions; plans are customer-specific instances created from a template or directly.

---

Payment Plan Templates

merchantApiPaymentPlanTemplateCreate

Create a reusable billing template tied to a transaction provider.

mutation CreateTemplate(
  $providerId: String!
  $data: MerchantPaymentPlanTemplateCreateSchema!
) {
  merchantApiPaymentPlanTemplateCreate(
    merchantTransactionProviderId: $providerId
    data: $data
  ) {
    id
    name
    amount
    currency
    renewalIntervalMonths
    endsAfterMonths
    trialPeriodDays
    providerStatus
    providerCode
    createdAt
    updatedAt
  }
}

Top-level arguments

Argument	Type	Required	Description
merchantTransactionProviderId	String	Yes	ID of the merchant transaction provider
data	MerchantPaymentPlanTemplateCreateSchema	Yes	Template definition

MerchantPaymentPlanTemplateCreateSchema fields

Field	Type	Required	Description
name	String	Yes	Human-readable template name
amount	BigInt	Yes	Recurring charge amount in smallest currency unit (e.g. cents)
initialAmount	BigInt	Yes	First-payment amount (set equal to amount when there is no different first charge)
currency	CURRENCY	Yes	ISO 4217 currency enum (e.g. USD)
providerStatus	PAYMENT_PLAN_TEMPLATE_STATUS	Yes	Initial status: ENABLED or DISABLED
renewalIntervalDays	Int	Yes	Days component of the renewal interval (0 if unused)
renewalIntervalMonths	Int	Yes	Months component of the renewal interval (0 if unused)
renewalIntervalYears	Int	Yes	Years component of the renewal interval (0 if unused)
endsAfterDays	Int	Yes	Days component of the plan duration (0 if unused)
endsAfterMonths	Int	Yes	Months component of the plan duration (0 if unused)
endsAfterYears	Int	Yes	Years component of the plan duration (0 if unused)
trialPeriodDays	Int	Yes	Days component of the trial period (0 if no trial)
trialPeriodMonths	Int	Yes	Months component of the trial period (0 if no trial)
trialPeriodYears	Int	Yes	Years component of the trial period (0 if no trial)
description	String	No	Optional template description
providerParentTemplateCode	String	No	Provider's parent template code, when applicable

note

As with plan creation, the renewalInterval*, endsAfter*, and trialPeriod* integers are each required — send all of them, using 0 for unused units. At least one renewalInterval* and one endsAfter* must be greater than 0.

Return shape

Field	Type	Description
id	String	AccruPay template UUID
name	String	Template name
amount	BigInt	Recurring amount
currency	CURRENCY	Currency
renewalIntervalMonths	Int	Months component of the renewal interval
endsAfterMonths	Int	Months component of the plan duration
trialPeriodDays	Int	Days component of the trial period
providerStatus	PAYMENT_PLAN_TEMPLATE_STATUS	Provider-side status
providerCode	String	Provider's own template reference
createdAt	DateTimeISO	Creation timestamp
updatedAt	DateTimeISO	Last update timestamp

---

merchantApiPaymentPlanTemplateUpdate

Update a template's mutable fields. Changes apply to future plan renewals only; existing active plans are not retroactively modified.

mutation UpdateTemplate(
  $providerId: String!
  $templateId: String!
  $data: MerchantPaymentPlanTemplateUpdateSchema!
) {
  merchantApiPaymentPlanTemplateUpdate(
    merchantTransactionProviderId: $providerId
    merchantPaymentPlanTemplateId: $templateId
    data: $data
  ) {
    id
    name
    providerStatus
    updatedAt
  }
}

Top-level arguments

Argument	Type	Required	Description
merchantTransactionProviderId	String	Yes	Provider ID
merchantPaymentPlanTemplateId	String	Yes	AccruPay template UUID to update
data	MerchantPaymentPlanTemplateUpdateSchema	Yes	Fields to update

MerchantPaymentPlanTemplateUpdateSchema fields

Field	Type	Required	Description
name	String	No	New template name
providerStatus	PAYMENT_PLAN_TEMPLATE_STATUS	No	ENABLED or DISABLED

---

merchantApiPaymentPlanTemplateSyncOne

Pull the latest state for a template from the provider and update AccruPay's records.

mutation SyncTemplate($providerId: String!, $providerCode: String!) {
  merchantApiPaymentPlanTemplateSyncOne(
    merchantTransactionProviderId: $providerId
    providerCode: $providerCode
  ) {
    id
    name
    providerStatus
    updatedAt
  }
}

Arguments

Argument	Type	Required	Description
merchantTransactionProviderId	String	Yes	Provider ID
providerCode	String	Yes	Provider's own template reference code

---

Payment Plans

merchantApiPaymentPlanCreate

Create a customer-specific payment plan, optionally from a template.

mutation CreatePlan(
  $providerId: String!
  $data: MerchantPaymentPlanCreateSchema!
) {
  merchantApiPaymentPlanCreate(
    merchantTransactionProviderId: $providerId
    data: $data
  ) {
    id
    status
    amount
    currency
    providerCode
    renewalIntervalMonths
    endsAfterMonths
    trialPeriodDays
    currentPeriodStart
    currentPeriodEnd
    createdAt
    updatedAt
  }
}

Top-level arguments

Argument	Type	Required	Description
merchantTransactionProviderId	String	Yes	Provider ID
data	MerchantPaymentPlanCreateSchema	Yes	Plan definition

MerchantPaymentPlanCreateSchema fields

Field	Type	Required	Description
merchantInternalPaymentPlanCode	String	Yes	Your unique identifier for this plan
templateId	String	Yes	AccruPay template UUID; billing schedule source
paymentMethodId	String	Yes	Stored payment method ID to charge on each renewal
amount	BigInt	Yes	Recurring charge amount in smallest currency unit
initialAmount	BigInt	Yes	First-charge amount (set equal to amount when there is no different first charge)
currency	CURRENCY	Yes	Currency enum (e.g. USD)
renewalIntervalDays	Int	Yes	Days component of the renewal interval (0 if unused)
renewalIntervalMonths	Int	Yes	Months component of the renewal interval (0 if unused)
renewalIntervalYears	Int	Yes	Years component of the renewal interval (0 if unused)
endsAfterDays	Int	Yes	Days component of the plan duration (0 if unused)
endsAfterMonths	Int	Yes	Months component of the plan duration (0 if unused)
endsAfterYears	Int	Yes	Years component of the plan duration (0 if unused)
trialPeriodDays	Int	Yes	Days component of the trial period (0 if no trial)
trialPeriodMonths	Int	Yes	Months component of the trial period (0 if no trial)
trialPeriodYears	Int	Yes	Years component of the trial period (0 if no trial)
merchantInternalPaymentPlanDescription	String	No	Optional human-readable description
customer	MerchantCustomerSelector	No	Customer selector. If omitted, the customer is resolved from the payment method. When provided, merchantInternalCustomerCode is required within it.

note

The interval, duration, and trial integers (renewalInterval*, endsAfter*, trialPeriod*) are each required by the schema — send every field, using 0 for units you are not using (e.g. a monthly plan sets renewalIntervalMonths: 1 and the other renewalInterval* to 0). The plan's billing cadence is defined by the referenced templateId.

Return shape

Field	Type	Description
id	String	AccruPay plan UUID
status	PAYMENT_PLAN_STATUS	INITIALIZING, ACTIVE, INACTIVE, CANCELED, ENDED, or ERROR
amount	BigInt	Recurring charge amount
currency	CURRENCY	Currency
providerCode	String	Provider's plan reference
renewalIntervalMonths	Int	Months component of the renewal interval
endsAfterMonths	Int	Months component of the plan duration
trialPeriodDays	Int	Days component of the trial period
currentPeriodStart	DateTimeISO	Start of the current billing period
currentPeriodEnd	DateTimeISO	End of the current billing period (the next charge boundary)
createdAt	DateTimeISO	Creation timestamp
updatedAt	DateTimeISO	Last update timestamp

---

merchantApiPaymentPlanCancel

Cancel an active plan. No further renewals will be charged after cancellation.

mutation CancelPlan($planId: String!, $providerId: String!) {
  merchantApiPaymentPlanCancel(
    merchantPaymentPlanId: $planId
    merchantTransactionProviderId: $providerId
  ) {
    id
    status
    updatedAt
  }
}

Arguments

Argument	Type	Required	Description
merchantPaymentPlanId	String	Yes	AccruPay plan UUID to cancel
merchantTransactionProviderId	String	Yes	Provider the plan belongs to

---

merchantApiPaymentPlanSyncOne

Pull the latest plan state from the provider by the provider's own reference code.

mutation SyncPlan($providerId: String!, $providerCode: String!) {
  merchantApiPaymentPlanSyncOne(
    merchantTransactionProviderId: $providerId
    providerCode: $providerCode
  ) {
    id
    status
    currentPeriodEnd
    updatedAt
  }
}

Arguments

Argument	Type	Required	Description
merchantTransactionProviderId	String	Yes	Provider ID
providerCode	String	Yes	Provider's plan reference code

---

Read queries

Fetch plans and templates. Single-record queries take an AccruPay ID; list queries return a pagination connection (edges { node }, pageInfo, totalCount).

Query	Type	Args	Returns
merchantApiPaymentPlan	query	merchantPaymentPlanId: String!	MerchantPaymentPlan!
merchantApiPaymentPlans	query	filters: id, transactionProviderId/transactionProvider, currency, providerCode, providerStatus, paymentMethodId, paymentMethod, templateId, customerId, merchantInternalCustomerCode, merchantInternalPaymentPlanCode, hasProviderError, started/ended/canceled, pagination (skip/take/after/first/before/last), sorting	MerchantPaymentPlanPaginationConnection!
merchantApiPaymentPlanTemplate	query	merchantPaymentPlanTemplateId: String!	MerchantPaymentPlanTemplate!
merchantApiPaymentPlanTemplates	query	filters: id, transactionProviderId/transactionProvider, name, currency, providerCode, providerParentTemplateCode, providerStatus, pagination, sorting	MerchantPaymentPlanTemplatePaginationConnection!

query GetPlan($merchantPaymentPlanId: String!) {
  merchantApiPaymentPlan(merchantPaymentPlanId: $merchantPaymentPlanId) {
    id
    status
    amount
    currency
    currentPeriodEnd
  }
}

---

Bulk sync (reconciliation)

Pull and reconcile all plans or templates for a provider in one call — for bulk reconciliation instead of per-record syncOne.

mutation SyncAllPlans($merchantTransactionProviderId: String!) {
  merchantApiPaymentPlanSyncAll(merchantTransactionProviderId: $merchantTransactionProviderId) {
    id
    status
    providerCode
  }
}

mutation SyncAllTemplates($merchantTransactionProviderId: String!) {
  merchantApiPaymentPlanTemplateSyncAll(merchantTransactionProviderId: $merchantTransactionProviderId) {
    id
    providerStatus
    providerCode
  }
}

Mutation	Arg	Returns
merchantApiPaymentPlanSyncAll	merchantTransactionProviderId: String!	[MerchantPaymentPlan!]!
merchantApiPaymentPlanTemplateSyncAll	merchantTransactionProviderId: String!	[MerchantPaymentPlanTemplate!]!

note

Both return a plain array (not a connection) and have no Node SDK wrapper — call them as raw GraphQL. The SDK exposes only syncOne.

---

Related

• Webhooks — how provider events update plan state
• Reconciliation
• Node SDK — Payment Plans
• Node SDK — Payment Plan Templates