Skip to content
SMBcrmSMBcrm Developers

Subscriptions

A subscription is a recurring billing record tied to a contact, created when a contact signs up for a recurring product or plan through a connected payment provider. This part of the API is read-only: subscriptions are created and managed by the checkout and provider flows, not by direct API calls. Use these endpoints to list and look up the subscriptions already on your account.

Base URL: https://services.smbcrm.com · Version header: v3 · Scope: payments/subscriptions.readonly. See Scopes.

List subscriptions

Section titled “List subscriptions”
GET/payments/subscriptions

List the recurring subscriptions in your SMBcrm account.

scope payments/subscriptions.readonlyauth Location token or PIT

Identify your account with altId and altType (see the Aside below). Add contactId to scope results to one contact, or id to look up a specific subscription, and page through with limit / offset.

Terminal window
curl "https://services.smbcrm.com/payments/subscriptions?altId=<location_id>&altType=location&contactId=<contact_id>&limit=20&offset=0" \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"
200 OK
{
  "data": [
    {
      "_id": "<subscription_id>",
      "altId": "<location_id>",
      "altType": "location",
      "contactId": "<contact_id>",
      "contactName": "Jane Doe",
      "contactEmail": "jane@example.com",
      "currency": "USD",
      "amount": 49,
      "liveMode": true,
      "entitySourceType": "funnel",
      "entitySourceName": "Membership Funnel",
      "paymentProviderType": "stripe",
      "createdAt": "2026-06-08T15:04:00.000Z",
      "updatedAt": "2026-06-08T15:04:00.000Z"
    }
  ],
  "totalCount": 1
}

Each record also carries status (an object describing the subscription’s current state), entityType, entityId, entitySourceId, entitySourceMeta, subscriptionId, subscriptionSnapshot, paymentProviderConnectedAccount, ipAddress and createdBy.

Query param Type Required Description
altId string Yes Your <location_id>. See the Aside below.
altType string Yes Always location.
contactId string No Limit results to subscriptions belonging to one contact.
id string No Filter to a specific subscription by ID.
entityId string No Filter by the subscription’s entity ID, for example an order ID.
entitySourceType string No Filter by the source that created the subscription, for example funnel or invoice.
paymentMode string No Filter by payment mode, for example live.
startAt string No Start of the date range to return, as YYYY-MM-DD, for example 2024-02-01.
endAt string No End of the date range to return, as YYYY-MM-DD, for example 2024-02-13.
search string No Search by subscription name.
limit number No Maximum number of subscriptions to return per page. Default 10.
offset number No Number of subscriptions to skip, for pagination. Default 0.
getPaymentsCollectedCount boolean No Include the total payments collected for each subscription.

Get a subscription

Section titled “Get a subscription”
GET/payments/subscriptions/{subscriptionId}

Fetch a single subscription by ID.

scope payments/subscriptions.readonlyauth Location token or PIT

Pass the subscription’s _id (from List subscriptions) as subscriptionId in the path. altId and altType are required.

Terminal window
curl "https://services.smbcrm.com/payments/subscriptions/<subscription_id>?altId=<location_id>&altType=location" \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"
200 OK
{
  "_id": "<subscription_id>",
  "altId": "<location_id>",
  "altType": "location",
  "contactId": "<contact_id>",
  "currency": "USD",
  "amount": 49,
  "liveMode": true,
  "entitySource": {
    "type": "funnel",
    "subType": "one_step_order_form",
    "id": "<funnel_id>",
    "name": "Membership Funnel"
  },
  "schedule": {
    "executeAt": "2026-08-08T15:04:00.000Z",
    "rrule": {
      "intervalType": "monthly",
      "interval": 1,
      "startDate": "2026-06-08"
    }
  },
  "createdAt": "2026-06-08T15:04:00.000Z",
  "updatedAt": "2026-06-08T15:04:00.000Z"
}

entitySource.type reflects where the subscription originated: funnel, website, invoice, calendar, text2Pay, document_contracts, membership, mobile_app, communities, point_of_sale, manual, form, survey, payment_link, or external. entitySource.subType further qualifies the source and is one of one_step_order_form, two_step_order_form, upsell, tap_to_pay, card_payment, store, contact_view, email_campaign, payments_dashboard, shopify, subscription_view, store_upsell, woocommerce, service, meeting, imported_csv, qr_code, saas_one_time, or saas_subscription. These lists can grow, so handle values you don’t recognize.

schedule.rrule is the recurrence rule that sets the billing cadence. intervalType and interval together define how often the subscription bills (in the example, every month), and startDate is the first date of the schedule. The rrule fields are listed below the query parameters.

The full response also includes status (an object describing the subscription’s current state), canceledAt / canceledBy once a subscription is canceled, and a paymentProvider object. Other fields are entityType, entityId, subscriptionId, ipAddress, meta, markAsTest, traceId and createdBy, plus these objects: coupon (the coupon applied to the subscription), recurringProduct (the recurring product), autoPayment (the auto-payment details), contactSnapshot (the subscriber’s contact details) and subscriptionSnapshot (a snapshot of the subscription record).

Query param Type Required Description
altId string Yes Your <location_id>.
altType string Yes Always location.

The schedule.rrule object in the response has these fields:

Field Type Required Description
intervalType string Yes Billing frequency unit: yearly, monthly, weekly, daily, hourly, minutely, or secondly.
interval number Yes Number of intervalType units between billings. 2 with monthly bills every two months.
startDate string Yes Start date of the schedule, YYYY-MM-DD.
startTime string No Start time, HH:mm:ss.
endDate string No End date of the schedule, YYYY-MM-DD.
endTime string No End time, HH:mm:ss.
dayOfMonth number No Day of the month: -1, or 1 through 28.
dayOfWeek string No Day of the week: mo, tu, we, th, fr, sa, or su.
numOfWeek number No Week number: -1, 1, 2, 3, or 4.
monthOfYear string No Month: jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, or dec.
count number No Maximum number of billings.
daysBefore number No Number of days before the scheduled date to run.
Section titled “Related”