APIPay In endpointsSubscriptions

Create subscription

View as MarkdownOpen in Claude

Creates a subscription or scheduled payment to run at a specified time and frequency. You can use stored payment method tokens for card, ACH, and digital wallets by passing them into the paymentMethod.storedMethodId field.

Authentication

requestTokenstring
API Key authentication via header

Headers

idempotencyKeystringOptional

Optional but recommended A unique ID that you can include to prevent duplicating objects or transactions in the case that a request is sent more than once. This key isn’t generated in Payabli, you must generate it yourself. This key persists for 2 minutes. After 2 minutes, you can reuse the key if needed.

Query parameters

forceCustomerCreationbooleanOptional

When true, the request creates a new customer record, regardless of whether customer identifiers match an existing customer. Defaults to false.

Request

This endpoint expects an object.
customerDataobjectOptional

Object describing the customer/payor.

entryPointstringOptional<=50 characters
The entrypoint identifier.
invoiceDataobjectOptional
Object describing an Invoice linked to the subscription.
paymentDetailsobjectOptional

Object describing details of the payment. For Regular subscriptions, skip a payment by setting totalAmount to 0; payments pause until you update it to a non-zero value, and serviceFee must also be 0 when totalAmount is 0. For BalanceDriven subscriptions, any totalAmount you send is accepted but ignored at run time. Each run charges the payor’s live balance, and a zero balance is skipped.

paymentMethodobjectOptional
Information about the payment method for the transaction. Required and recommended fields for each payment method type are described in each schema below.
scheduleDetailsobjectOptional
Object describing the schedule for subscription.
setPausebooleanOptional

Flag indicating if subscription is paused. When a subscription is paused, no payments are processed until the subscription is unpaused, and the next payment date isn’t calculated automatically. If you want to skip a payment instead, set the totalAmount to 0 in the paymentDetails object.

sourcestringOptional<=100 characters
Custom identifier to indicate the transaction or request source.
subdomainstringOptional<=50 characters
Refers to the payment page identifier. If provided, then the transaction is linked to the payment page.
subscriptionTypeenumOptional

Subscription type. Defaults to Regular when omitted. Can’t be changed after the subscription is created. If you send it to the update endpoint, it’s ignored.

Response

Success
responseTextstring

Response text for operation: ‘Success’ or ‘Declined’.

responseDatainteger
The identifier of the newly created subscription.
customerIdlong

The Payabli-generated unique ID for the customer.

isSuccessboolean

Boolean indicating whether the operation was successful. A true value indicates success. A false value indicates failure.

Errors

400
Bad Request Error
401
Unauthorized Error
500
Internal Server Error
503
Service Unavailable Error