Manage Scheduled or Recurring Payments

This guide covers the key operations for managing subscriptions through the API.

​

Considerations

When working with subscriptions, keep the following in mind:

• Payabli automatically tokenizes payment information and assigns stored payment methods to the provided customer.
• Subscriptions are always linked to a customer - if no customerId is provided and the customerData fields don’t match an existing customer, a new customer is created.
• Best practice is to create the customer first and pass the customerId in the customerData object.
• When using a stored payment method, ensure the storedId in paymentMethod corresponds to the customer in customerData.
• Subscription and autopay transactions typically run between 2:30 AM and 3:30 AM Eastern time.

​

Pause a subscription or skip a payment

Pausing a subscription stops all future payments until the subscription is unpaused. Skipping payments allows the subscription to continue but skips the next scheduled payment.

To pause a subscription, send a PUT request to /api/Subscription/\{subscriptionId\} with the setPause field set to true. When you’re ready to resume the subscription, send another PUT request with setPause set to false.

To skip a payment, update the subscription’s totalAmount to 0. To resume payments, update totalAmount to a non-zero amount. Note that if totalAmount is set to 0, then serviceFee must also be set to 0.

​

Create a subscription

Send a POST request to /api/Subscription/add to create a new subscription or scheduled payment. See the API reference for this endpoint for full documentation.

curl --request POST \
  --url https://api-sandbox.payabli.com/api/Subscription/add \
  --header 'Content-Type: application/json' \
  --header 'requestToken: <api-key>' \
  --data '{
  "entryPoint": "f743aed24a",
  "paymentMethod": {
    "storedMethodId": "4000e8c6-3add-4200-8ac2-9b8a4f8b1639-1323",
    "initiator": "merchant",
    "storedMethodUsageType": "recurring"
  },
  "paymentDetails": {
    "totalAmount": 100,
    "serviceFee": 0
  },
  "customerData": {
    "customerId": 4440
  },
  "invoiceData": {
    "invoiceNumber": "VU_17222",
  },
  "scheduleDetails": {
    "planId": 1,
    "startDate": "09-20-2024",
    "endDate": "03-20-2025",
    "frequency": "weekly"
  }
}'

​

Get subscription details

Send a GET request to /api/Subscription/{subscriptionId} to retrieve details about a specific subscription. See the API reference for this endpoint for full documentation.

This example gets the details for the subscription with ID 263.

curl --request GET \
    --url https://api-sandbox.payabli.com/api/Subscription/263 \
    --header 'accept: application/json' \
    --header 'requestToken: <API TOKEN>'

A successful request returns a response that includes all available details about a subscription.

​

Update a subscription

Send a PUT request to /api/Subscription/{subscriptionId} to change an existing subscription’s payment details, schedule, or pause status. See the API reference for this endpoint for full documentation.

The first example updates the subscription with the ID 263 to paused. The second example updates the payment details.

curl --request PUT \
    --url https://api-sandbox.payabli.com/api/Subscription/263 \
    --header 'accept: application/json' \
    --header 'content-type: application/*+json' \
    --header 'requestToken: <API TOKEN>' \
    --data '{"setPause":true}'

​

Delete a subscription

Send a DELETE request to /api/Subscription/{subscriptionId} to cancel a subscription and stop future payments. See the API reference for this endpoint for full documentation.

This example deletes the subscription with the ID 263.

curl --request DELETE \
    --url https://api-sandbox.payabli.com/api/Subscription/263 \
    --header 'accept: application/json' \
    --header 'requestToken: <API TOKEN>'

​

Response format

All subscription operations return a standardized response format:

{
  "responseText": "Success",
  "isSuccess": true,
  "responseData": 263, // this is the subscription ID
  "customerId": 1300
}