API & webhooks
Connect your website or other software. Add subscriptions, record usage, read invoices, and be told the moment something happens.
The API and webhooks are in the Business plan. Admins set them up under Settings › API & webhooks.
API keys
Click New key, say what it's for, and choose Read only or Read & write. Copy the key straight away; it is shown only once. A key works as you, with your Subscriptions role. Revoke a key you no longer use.
Send it with each request as Authorization: Bearer <key>. Requests and replies are JSON.
What you can do
| Request | Does |
|---|---|
GET /plans | Your active plans. |
GET /customers?email= · GET /customers/{id} | Find customers. |
POST /customers | Add a customer: name, email, mobile, tax_id, state_code. |
GET /subscriptions?status=&customer_id= · GET /subscriptions/{id} | Subscriptions, with plan, add-ons, MRR, dates and custom fields. |
POST /subscriptions | Start a subscription: customer_id, plan_code, quantity, price, start_date, trial_days, coupon_code, addons, custom_fields, salesperson_id, reference. |
POST /subscriptions/{id}/usage | Record usage of a by-usage add-on: addon_code, quantity, date, note. It's billed on the next invoice. |
POST /subscriptions/{id}/cancel | Cancel: when (end or now), reason, credit. |
GET /subscriptions/{id}/invoices | Its invoices and credit notes. |
The full address and examples are on the API & webhooks page. Errors come back with a code and message, such as 401 for a missing key, 422 for a wrong value (with the field) or 429 when the day's limit is reached. Everything changed through the API is in the activity log.
Webhooks
Click New webhook, enter your https address and tick the events: a subscription added, started, renewed, changed, paused, resumed, cancelled, expired, reactivated or Unpaid, a payment received, or a quote accepted or declined.
- Signing: we POST JSON with the event, the subscription (or quote) and, for invoices, the invoice. Each delivery is signed: check that the
X-Ellibo-Signatureheader equalssha256=plus the HMAC-SHA256 oftimestamp.bodywith your webhook's secret, where the timestamp is theX-Ellibo-Timestampheader. The secret is shown once when you make the webhook. - Retries: a delivery your address doesn't accept (not a 2xx answer) is tried again after 5 minutes, 1, 3, 12 and 24 hours. If it still fails, the admins get an email.
- Testing: Send a test posts a
pingstraight away. Latest deliveries shows what was sent and what came back.