Skip to main content
POST
/
api
/
v1
/
subscriptions
/
subscribers
curl -X POST https://api.settlx.io/api/v1/subscriptions/subscribers \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "customer@example.com",
    "externalId": "usr_789abc",
    "metadata": {
      "userId": "usr_789abc",
      "signupSource": "checkout"
    }
  }'

{
  "data": {
    "id": "9f1e2d3c-4b5a-6789-abcd-ef0123456789",
    "merchantId": "f9e8d7c6-b5a4-3210-9876-543210fedcba",
    "planId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "customer@example.com",
    "externalId": "usr_789abc",
    "status": "pending",
    "currentPeriodStart": "2026-04-19T00:00:00.000Z",
    "currentPeriodEnd": "2026-05-19T00:00:00.000Z",
    "gracePeriodEndsAt": "2026-04-26T00:00:00.000Z",
    "cancelAtEnd": false,
    "metadata": {
      "userId": "usr_789abc",
      "signupSource": "checkout"
    },
    "createdAt": "2026-04-19T10:00:00.000Z"
  }
}

​
Enroll Subscriber

Enrolls a customer into a subscription plan. Call this from your backend when a customer chooses a plan — for example, after they complete your onboarding or sign-up flow. After enrollment:
  • The subscriber’s status is set to pending
  • An invoice is created immediately for the first billing cycle
  • A subscriber.enrolled webhook is fired to your configured webhook URL
  • The subscriber becomes active only after their first payment is confirmed on-chain
Provision access to your product only after you receive the subscriber.activated webhook — not immediately on enrollment.

​
Request

​
planId
string
required
UUID of the subscription plan to enroll the customer into. The plan must belong to your merchant account and must not be archived.Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
​
email
string
required
The subscriber’s email address. Used for billing notifications and to identify the subscriber within a plan.A subscriber with the same email can only be enrolled in the same plan once at a time. Attempting to enroll a duplicate returns 409 Conflict.Example: "customer@example.com"
​
externalId
string
Your internal customer or user ID. Stored on the subscriber record and returned in webhook payloads. Use this to correlate Settlx subscribers with users in your system.Maximum 255 characters.Example: "usr_789abc"
​
metadata
object
Arbitrary key-value pairs to attach to the subscriber. Returned in all webhook events for this subscriber.Example: { "plan": "pro", "signupSource": "checkout" }

​
Response

​
data
object
curl -X POST https://api.settlx.io/api/v1/subscriptions/subscribers \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "customer@example.com",
    "externalId": "usr_789abc",
    "metadata": {
      "userId": "usr_789abc",
      "signupSource": "checkout"
    }
  }'

{
  "data": {
    "id": "9f1e2d3c-4b5a-6789-abcd-ef0123456789",
    "merchantId": "f9e8d7c6-b5a4-3210-9876-543210fedcba",
    "planId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "customer@example.com",
    "externalId": "usr_789abc",
    "status": "pending",
    "currentPeriodStart": "2026-04-19T00:00:00.000Z",
    "currentPeriodEnd": "2026-05-19T00:00:00.000Z",
    "gracePeriodEndsAt": "2026-04-26T00:00:00.000Z",
    "cancelAtEnd": false,
    "metadata": {
      "userId": "usr_789abc",
      "signupSource": "checkout"
    },
    "createdAt": "2026-04-19T10:00:00.000Z"
  }
}