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"
    }
  }'

const response = await fetch('https://api.settlx.io/api/v1/subscriptions/subscribers', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SETTLX_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    planId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    email: 'customer@example.com',
    externalId: 'usr_789abc',
    metadata: {
      userId: 'usr_789abc',
      signupSource: 'checkout',
    },
  }),
});

const { data } = await response.json();
console.log(data.id);     // subscriber UUID
console.log(data.status); // "pending"

import httpx, os

client = httpx.Client(headers={"Authorization": f"Bearer {os.environ['SETTLX_API_KEY']}"})

response = client.post(
    "https://api.settlx.io/api/v1/subscriptions/subscribers",
    json={
        "planId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "email": "customer@example.com",
        "externalId": "usr_789abc",
        "metadata": {"userId": "usr_789abc"},
    }
)

subscriber = response.json()["data"]
print(subscriber["id"])      # subscriber UUID
print(subscriber["status"])  # "pending"

{
  "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"
  }
}

{
  "error": "Bad Request",
  "message": "Cannot enroll into an archived plan"
}

{
  "error": "Not Found",
  "message": "Subscription plan not found"
}

{
  "error": "Conflict",
  "message": "Subscriber is already enrolled in this plan (status: active)"
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

POST

api

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"
    }
  }'

const response = await fetch('https://api.settlx.io/api/v1/subscriptions/subscribers', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SETTLX_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    planId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    email: 'customer@example.com',
    externalId: 'usr_789abc',
    metadata: {
      userId: 'usr_789abc',
      signupSource: 'checkout',
    },
  }),
});

const { data } = await response.json();
console.log(data.id);     // subscriber UUID
console.log(data.status); // "pending"

import httpx, os

client = httpx.Client(headers={"Authorization": f"Bearer {os.environ['SETTLX_API_KEY']}"})

response = client.post(
    "https://api.settlx.io/api/v1/subscriptions/subscribers",
    json={
        "planId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "email": "customer@example.com",
        "externalId": "usr_789abc",
        "metadata": {"userId": "usr_789abc"},
    }
)

subscriber = response.json()["data"]
print(subscriber["id"])      # subscriber UUID
print(subscriber["status"])  # "pending"

{
  "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"
  }
}

{
  "error": "Bad Request",
  "message": "Cannot enroll into an archived plan"
}

{
  "error": "Not Found",
  "message": "Subscription plan not found"
}

{
  "error": "Conflict",
  "message": "Subscriber is already enrolled in this plan (status: active)"
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

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

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"

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"

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"

object

Arbitrary key-value pairs to attach to the subscriber. Returned in all webhook events for this subscriber.Example: { "plan": "pro", "signupSource": "checkout" }

Response

object

Show Subscriber object

string

UUID of the subscriber

string

Your merchant account UUID

string

UUID of the plan they enrolled into

string

Subscriber email address

string | null

Your internal customer ID, if provided

string

Always pending immediately after enrollment

string

ISO 8601 — start of the current billing period

string

ISO 8601 — end of the current billing period

string

ISO 8601 — deadline to pay the first invoice before expiry

boolean

Whether the subscription is scheduled to cancel at period end

object | null

Metadata you attached at enrollment

string

ISO 8601 creation timestamp

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"
    }
  }'

const response = await fetch('https://api.settlx.io/api/v1/subscriptions/subscribers', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SETTLX_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    planId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    email: 'customer@example.com',
    externalId: 'usr_789abc',
    metadata: {
      userId: 'usr_789abc',
      signupSource: 'checkout',
    },
  }),
});

const { data } = await response.json();
console.log(data.id);     // subscriber UUID
console.log(data.status); // "pending"

import httpx, os

client = httpx.Client(headers={"Authorization": f"Bearer {os.environ['SETTLX_API_KEY']}"})

response = client.post(
    "https://api.settlx.io/api/v1/subscriptions/subscribers",
    json={
        "planId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "email": "customer@example.com",
        "externalId": "usr_789abc",
        "metadata": {"userId": "usr_789abc"},
    }
)

subscriber = response.json()["data"]
print(subscriber["id"])      # subscriber UUID
print(subscriber["status"])  # "pending"

{
  "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"
  }
}

{
  "error": "Bad Request",
  "message": "Cannot enroll into an archived plan"
}

{
  "error": "Not Found",
  "message": "Subscription plan not found"
}

{
  "error": "Conflict",
  "message": "Subscriber is already enrolled in this plan (status: active)"
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Invoices

Subscriptions

Settlements

Webhooks

Reference

Webhook Events — Invoices

Webhook Events — Subscriptions

Guides

Enroll Subscriber

Enroll Subscriber

Request

Response

​Enroll Subscriber

​Request

​Response

Enroll Subscriber

Request

Response