Manage subscriptions with the API

Subscriptions, also known as recurring transactions, autopays, or scheduled payments, are a powerful way to automate billing and payment collection. With Payabli’s API, you can manage these transactions, including creating, updating, and deleting subscriptions.

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.
• If a subscription payment is declined, you can update the subscription and retry the payment. See Subscription retry logic for more information. Payabli doesn’t retry failed autopays.
• If you pass an invoiceData object to a subscription, the payments in the subscription are automatically added to the invoice as they’re processed.
• Before enrolling customers in recurring billing, make sure you have clear terms and conditions that cover cancellation policies, refund rules, billing frequency, and payment amounts. Work with your legal team to draft these. Displaying terms and capturing customer consent protects you in the event of a chargeback dispute.

Subscription types

Payabli supports two subscription types, set via the subscriptionType field when you create a subscription:

• Regular (default): Charges a fixed amount each cycle. Set totalAmount in paymentDetails (and serviceFee if you charge one). Use any of the supported frequencies.
• BalanceDriven: Charges the payor’s outstanding balance at run time instead of a fixed amount. Each scheduled run reads the live balance and charges that amount. A zero balance is skipped, not charged.

subscriptionType can’t be changed after the subscription is created.

BalanceDriven schedule rules

BalanceDriven subscriptions follow stricter scheduling rules than Regular ones:

• Only the monthly cadences firstofmonth, fifteenthofmonth, and endofmonth are accepted for scheduleDetails.frequency.
• scheduleDetails.startDate is calculated automatically from the chosen frequency. Any value you supply is ignored.
• scheduleDetails.endDate doesn’t apply — BalanceDriven subscriptions run until cancelled.
• No static totalAmount is stored on the schedule. The amount comes from the live balance at run time.

The three new monthly cadences are valid for Regular subscriptions too.

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.

For Regular subscriptions, skip a payment by updating the subscription’s totalAmount to 0. To resume payments, update totalAmount to a non-zero amount. If totalAmount is set to 0, then serviceFee must also be set to 0.

For BalanceDriven subscriptions, the totalAmount = 0 skip mechanism doesn’t apply. The charge amount comes from the payor’s live balance, not from a totalAmount you send, so any totalAmount is accepted but ignored at run time. A scheduled run with a zero balance is automatically skipped.

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.

1
curl -X PUT https://api-sandbox.payabli.com/api/Subscription/231 \
2
     -H "requestToken: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "setPause": true
6
}'

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.

1
curl -X POST https://api-sandbox.payabli.com/api/Subscription/add \
2
     -H "requestToken: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "customerData": {
6
    "customerId": 4440
7
  },
8
  "entryPoint": "8cfec329267",
9
  "paymentDetails": {
10
    "totalAmount": 100,
11
    "serviceFee": 0
12
  },
13
  "paymentMethod": {
14
    "cardcvv": "123",
15
    "cardexp": "02/25",
16
    "cardHolder": "John Cassian",
17
    "cardnumber": "4111111111111111",
18
    "cardzip": "37615",
19
    "initiator": "payor",
20
    "method": "card"
21
  },
22
  "scheduleDetails": {
23
    "endDate": "2025-03-20",
24
    "frequency": "weekly",
25
    "planId": 1,
26
    "startDate": "2024-09-20"
27
  }
28
}'

1
curl -X POST https://api-sandbox.payabli.com/api/Subscription/add \
2
     -H "requestToken: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "customerData": {
6
    "customerId": 4440
7
  },
8
  "entryPoint": "8cfec329267",
9
  "paymentDetails": {
10
    "totalAmount": 100,
11
    "serviceFee": 0
12
  },
13
  "paymentMethod": {
14
    "achAccount": "3453445666",
15
    "achAccountType": "Checking",
16
    "achCode": "PPD",
17
    "achHolder": "John Cassian",
18
    "achHolderType": "personal",
19
    "achRouting": "021000021",
20
    "method": "ach"
21
  },
22
  "scheduleDetails": {
23
    "endDate": "2025-03-20",
24
    "frequency": "weekly",
25
    "planId": 1,
26
    "startDate": "2024-09-20"
27
  }
28
}'

1
curl -X POST https://api-sandbox.payabli.com/api/Subscription/add \
2
     -H "requestToken: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "customerData": {
6
    "customerId": 4440
7
  },
8
  "entryPoint": "8cfec329267",
9
  "paymentDetails": {
10
    "totalAmount": 100,
11
    "serviceFee": 0
12
  },
13
  "paymentMethod": {
14
    "initiator": "merchant",
15
    "storedMethodId": "1ec55af9-7b5a-4ff0-81ed-c12d2f95e135-4440",
16
    "storedMethodUsageType": "recurring"
17
  },
18
  "scheduleDetails": {
19
    "endDate": "2025-03-20",
20
    "frequency": "weekly",
21
    "planId": 1,
22
    "startDate": "2024-09-20"
23
  }
24
}'

1
curl -X POST https://api-sandbox.payabli.com/api/Subscription/add \
2
     -H "requestToken: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "customerData": {
6
    "customerId": 4440
7
  },
8
  "entryPoint": "8cfec329267",
9
  "paymentDetails": {
10
    "totalAmount": 100,
11
    "serviceFee": 0
12
  },
13
  "paymentMethod": {
14
    "initiator": "merchant",
15
    "storedMethodId": "1ec55af9-7b5a-4ff0-81ed-c12d2f95e135-4440",
16
    "storedMethodUsageType": "recurring"
17
  },
18
  "scheduleDetails": {
19
    "endDate": "2025-03-20",
20
    "frequency": "weekly",
21
    "planId": 1,
22
    "startDate": "2024-09-20"
23
  }
24
}'

1
curl -X POST https://api-sandbox.payabli.com/api/Subscription/add \
2
     -H "requestToken: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "customerData": {
6
    "customerId": 4440
7
  },
8
  "entryPoint": "8cfec329267",
9
  "paymentDetails": {
10
    "totalAmount": 100,
11
    "serviceFee": 0
12
  },
13
  "paymentMethod": {
14
    "cardcvv": "123",
15
    "cardexp": "02/25",
16
    "cardHolder": "John Cassian",
17
    "cardnumber": "4111111111111111",
18
    "cardzip": "37615",
19
    "initiator": "payor",
20
    "method": "card"
21
  },
22
  "scheduleDetails": {
23
    "frequency": "endofmonth"
24
  },
25
  "subscriptionType": "BalanceDriven"
26
}'

A successful request sends a response that includes the subscription ID (in responseData) and customer ID.

1
{
2
  "responseText": "Success",
3
  "responseData": 396,
4
  "customerId": 4440,
5
  "isSuccess": true
6
}

Get subscription details

Send a GET request to /api/Subscription/{subscriptionId} to retrieve details about a specific subscription.

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

1
curl https://api-sandbox.payabli.com/api/Subscription/231 \
2
     -H "requestToken: <apiKey>"

A successful request returns a response that includes all available details about a subscription. The response shape is the same for both subscription types — the SubscriptionType field indicates which one. See the API reference for a full response example.

1
{
2
  "EndDate": "2025-10-19T00:00:00Z",
3
  "LastRun": "2025-10-19T00:00:00Z",
4
  "NextDate": "2025-10-19T00:00:00Z",
5
  "StartDate": "2025-10-19T00:00:00Z",
6
  "CreatedAt": "2022-07-01T15:00:01Z",
7
  "Customer": {
8
    "Identifiers": [
9
      "\\\"firstname\\\"",
10
      "\\\"lastname\\\"",
11
      "\\\"email\\\"",
12
      "\\\"customId\\\""
13
    ],
14
    "FirstName": "John",
15
    "LastName": "Doe",
16
    "CompanyName": "Sunshine LLC",
17
    "BillingAddress1": "1111 West 1st Street",
18
    "BillingAddress2": "Suite 200",
19
    "BillingCity": "Miami",
20
    "BillingState": "FL",
21
    "BillingZip": "45567",
22
    "BillingCountry": "US",
23
    "BillingPhone": "5555555555",
24
    "BillingEmail": "example@email.com",
25
    "CustomerNumber": "C-90010",
26
    "ShippingAddress1": "123 Walnut St",
27
    "ShippingAddress2": "STE 900",
28
    "ShippingCity": "Johnson City",
29
    "ShippingState": "TN",
30
    "ShippingZip": "37619",
31
    "ShippingCountry": "US",
32
    "customerId": 4440,
33
    "customerStatus": 1,
34
    "AdditionalData": null
35
  },
36
  "EntrypageId": 0,
37
  "ExternalPaypointID": "Paypoint-100",
38
  "FeeAmount": 3,
39
  "Frequency": "monthly",
40
  "IdSub": 396,
41
  "invoiceData": {
42
    "AdditionalData": null,
43
    "attachments": [
44
      {}
45
    ],
46
    "company": "ACME, INC",
47
    "discount": 10,
48
    "dutyAmount": 0,
49
    "firstName": "Chad",
50
    "freightAmount": 10,
51
    "frequency": "onetime",
52
    "invoiceAmount": 105,
53
    "invoiceDate": "2025-07-01",
54
    "invoiceDueDate": "2025-07-01",
55
    "invoiceEndDate": "2025-07-01",
56
    "invoiceNumber": "INV-2345",
57
    "invoiceStatus": 1,
58
    "invoiceType": 0,
59
    "items": [
60
      {
61
        "itemCost": 5,
62
        "itemProductName": "Materials deposit",
63
        "itemQty": 1
64
      }
65
    ],
66
    "lastName": "Mercia",
67
    "notes": "Example notes.",
68
    "paymentTerms": "PIA",
69
    "purchaseOrder": "PO-345",
70
    "shippingAddress1": "123 Walnut St",
71
    "shippingAddress2": "STE 900",
72
    "shippingCity": "Johnson City",
73
    "shippingCountry": "US",
74
    "shippingEmail": "example@email.com",
75
    "shippingFromZip": "30040",
76
    "shippingPhone": "5555555555",
77
    "shippingState": "TN",
78
    "shippingZip": "37619",
79
    "summaryCommodityCode": "501718",
80
    "tax": 2.05,
81
    "termsConditions": "Must be paid before work scheduled."
82
  },
83
  "LastUpdated": "2022-07-01T15:00:01Z",
84
  "LeftCycles": 15,
85
  "Method": "card",
86
  "NetAmount": 3762.87,
87
  "ParentOrgName": "PropertyManager Pro",
88
  "PaymentData": {
89
    "AccountExp": "11/29",
90
    "accountId": "accountId",
91
    "AccountType": "visa",
92
    "AccountZip": "90210",
93
    "binData": {
94
      "binMatchedLength": "6",
95
      "binCardBrand": "Visa",
96
      "binCardType": "Credit",
97
      "binCardCategory": "PLATINUM",
98
      "binCardIssuer": "Bank of Example",
99
      "binCardIssuerCountry": "United States",
100
      "binCardIssuerCountryCodeA2": "US",
101
      "binCardIssuerCountryNumber": "840",
102
      "binCardIsRegulated": "false",
103
      "binCardUseCategory": "Consumer",
104
      "binCardIssuerCountryCodeA3": "USA"
105
    },
106
    "HolderName": "Chad Mercia",
107
    "Initiator": "payor",
108
    "MaskedAccount": "4XXXXXXXX1111",
109
    "orderDescription": "Depost for materials for 123 Walnut St",
110
    "paymentDetails": {
111
      "totalAmount": 100,
112
      "categories": [
113
        {
114
          "amount": 1000,
115
          "label": "Deposit"
116
        }
117
      ],
118
      "checkImage": {
119
        "key": "value"
120
      },
121
      "checkNumber": "107",
122
      "currency": "USD",
123
      "serviceFee": 0,
124
      "splitFunding": [
125
        {}
126
      ]
127
    },
128
    "Sequence": "subsequent",
129
    "SignatureData": "SignatureData",
130
    "StoredId": "1ec55af9-7b5a-4ff0-81ed-c12d2f95e135-4440",
131
    "StoredMethodUsageType": "subscription"
132
  },
133
  "PaypointDbaname": "Sunshine Gutters",
134
  "PaypointEntryname": "d193cf9a46",
135
  "PaypointId": 3040,
136
  "PaypointLegalname": "Sunshine Services, LLC",
137
  "PlanId": 0,
138
  "Source": "api",
139
  "SubEvents": [
140
    {
141
      "description": "TransferCreated",
142
      "eventTime": "2023-07-05T22:31:06Z",
143
      "extraData": null,
144
      "refData": "refData",
145
      "source": "api"
146
    }
147
  ],
148
  "SubStatus": 1,
149
  "SubscriptionType": "Regular",
150
  "TotalAmount": 103,
151
  "TotalCycles": 24,
152
  "UntilCancelled": true
153
}

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.

You can’t change subscriptionType after creation. If you include it in an update request, it’s ignored.

1
curl -X PUT https://api-sandbox.payabli.com/api/Subscription/231 \
2
     -H "requestToken: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "paymentDetails": {
6
    "totalAmount": 100,
7
    "serviceFee": 0
8
  },
9
  "scheduleDetails": {
10
    "endDate": "2025-03-20",
11
    "frequency": "weekly",
12
    "planId": 1,
13
    "startDate": "2024-09-20"
14
  }
15
}'

A successful request returns a response that includes the subscription ID (in responseData) and customer ID.

1
{
2
  "responseText": "Success",
3
  "isSuccess": true,
4
  "responseData": "396 updated",
5
  "customerId": 4440
6
}

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 396.

1
curl -X DELETE https://api-sandbox.payabli.com/api/Subscription/231 \
2
     -H "requestToken: <apiKey>"

A successful deletion returns a response that includes the subscription ID (in responseData) and customer ID.

1
{
2
  "responseText": "Success",
3
  "isSuccess": true,
4
  "responseData": "396"
5
}

Next steps

Use the Subscription Utilities to manage your subscriptions. These utilities provide additional functionality, such as retrying failed payments and managing autopay transactions.

Related resources

See these related resources to help you get the most out of Payabli.