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	No	First-payment amount when different from amount
currency	CURRENCY	Yes	ISO 4217 currency enum (e.g. USD)
providerStatus	PAYMENT_PLAN_TEMPLATE_STATUS	Yes	Initial status: ENABLED or DISABLED
renewalIntervalMonths	Int	Yes	Months between renewals
endsAfterMonths	Int	No	Plan duration in months; omit for indefinite
trialPeriodDays	Int	No	Trial days before first charge; 0 for no trial

Return shape

Field	Type	Description
id	String	AccruPay template UUID
name	String	Template name
amount	BigInt	Recurring amount
currency	CURRENCY	Currency
renewalIntervalMonths	Int	Renewal interval
endsAfterMonths	Int	Duration; null if indefinite
trialPeriodDays	Int	Trial period
providerStatus	PAYMENT_PLAN_TEMPLATE_STATUS	Provider-side status
providerCode	String	Provider's own template reference
createdAt	DateTime	Creation timestamp
updatedAt	DateTime	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
    nextChargeAt
    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	No	AccruPay template UUID; inherits billing schedule when provided
paymentMethodId	String	Yes	Stored payment method ID to charge on each renewal
amount	BigInt	Yes	Recurring charge amount in smallest currency unit
initialAmount	BigInt	No	First-charge amount when different from amount
currency	CURRENCY	Yes	Currency enum (e.g. USD)
renewalIntervalMonths	Int	Yes	Months between charges
endsAfterMonths	Int	No	Plan duration in months; omit for indefinite
trialPeriodDays	Int	No	Trial period before first charge
customer.merchantInternalCustomerCode	String	Yes	Your customer identifier

Return shape

Field	Type	Description
id	String	AccruPay plan UUID
status	PAYMENT_PLAN_STATUS	ACTIVE, INACTIVE, CANCELED, ENDED, or ERROR
amount	BigInt	Recurring charge amount
currency	CURRENCY	Currency
providerCode	String	Provider's plan reference
renewalIntervalMonths	Int	Renewal interval
endsAfterMonths	Int	Duration; null if indefinite
trialPeriodDays	Int	Trial period
nextChargeAt	DateTime	Scheduled next charge date
createdAt	DateTime	Creation timestamp
updatedAt	DateTime	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
    nextChargeAt
    updatedAt
  }
}

Arguments

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

---

Related

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