Subscriptions

Returns a paginated list of subscriptions as { meta: { count, totalPages, page, limit }, data: [...] }.

Defaults: page=1, limit=10, sort=-updatedAt (prefix with - for descending).

Filters: status (running, completed, incomplete, paused, inactive; comma-separated for several), customerId (customer vault id), planId, email, companyName, phone, customerName, plan (plan name), reference.

inactive (deleted) subscriptions are hidden unless status is sent explicitly. Response money fields are integer cents. The amount filter takes dollars (converted to cents). List entries omit schedule and payment counters; use GET /public/subscription/{id}.

Create a new subscription linked to a plan (or inline custom schedule) and a customer vault. All money values are integer amounts in cents (1000 = $10.00).

Customer: exactly one of customerId / customerVaultId is required. They are aliases for the customer vault id; when both are sent customerId wins. The customer must have an email and a default payment method (card or ACH), which is the one charged.

Schedule: send planId or customSchedule. When both are sent planId takes precedence. customSchedule rules: amount (cents) required; payments 0–52 (0 = until terminated); exactly one frequency mode — dayFrequency (> 0) alone, or monthFrequency (1–24) together with dayOfMonth (1–31).

startDate — optional. Omitted = tomorrow (start of day). A supplied date must be in the future.

autoRenew — renew after the last payment cycle (optional in practice; defaults to falsy).

notificationMail — send receipt notifications; defaults to true.

taxes — merchant tax ids; the tax total is added to the amount.

attachments — objects returned by POST /public/subscription/upload-attachments.

Surcharge is computed server-side from the payment method (0 for ACH). overrideDefaultPaymentMethod (payment method id) charges a non-default stored method.

Retrieve a single subscription by ID.

Cancel a subscription by setting status: inactive; deletedAt is not set and the record remains retrievable by id. Subscriptions in completed or incomplete status cannot be deleted. Inactive subscriptions are hidden from the list unless status=inactive is sent. Future schedule entries are removed on cancellation (only past entries are kept).

Update an existing subscription.

Updatable fields: amount (cents), autoRenew, notificationMail, customerVaultId, attachments, customSchedule, startDate.

To change the customer vault (and thus the payment method), provide a new customerVaultId.

attachments: Upload files first via /upload-attachments, then pass the file path objects here.

customSchedule: Only for subscriptions created with a custom schedule (not plan-based ones). Replaces the schedule; if amount is also sent it must match customSchedule.amount. Rejected when the subscription has future payments already paid.

startDate: Re-anchors the rebuilt schedule; must be a future date and can only be sent together with customSchedule.

Pause a running subscription (other statuses are rejected). Future schedule entries are removed and no charges are processed while paused; nextPayment becomes null. Use resume to re-activate. Rejected when inactive, already paused, or when future entries are already paid. A pause email is always sent to the customer (ignores notificationMail).

Resume a paused subscription. The remaining schedule is regenerated from the resume date according to the plan settings; payments that would have fallen inside the pause are skipped, not caught up. Charges continue as scheduled once resumed. A resume email is always sent (ignores notificationMail).

Manually charge any unpaid schedule entry (failed or not yet attempted). Subscription status, entry date and attempt count are not checked. Provide the scheduleId from the subscription's schedule array.

State-changing GET: this request performs a charge against the customer default payment method and is not idempotent; do not retry blindly.

Upload attachment files to associate with a subscription (e.g. contracts, agreements). Use the returned file path objects in the attachments field when creating or updating a subscription.

File limits: configured per deployment; defaults: up to 10 files per request, 25 MB per file, 25 MB total.

Supported formats: JPG, PNG, PDF. Uploaded files are publicly readable; fullPath is an unauthenticated URL. Attachments are returned by GET/list but omitted from webhook payloads.