Subscriptions

A subscription is a recurring-billing schedule. Each time a cycle comes due, fluxa generates a fresh charge on the fixed on-chain stablecoin channel for the fixed amount and advances the schedule. Because settlement is non-custodial and direct, each cycle is its own on-chain charge — the payer sends to a fresh deposit address for that cycle, and the net settles on-chain straight to your own wallet. Lifecycle events (subscription.charged, subscription.completed, subscription.payment_failed) are delivered as webhooks.

The subscription model

Name
id
Type
string
Description
The subscription id, prefixed sub_.
Name
title
Type
string
Description
Human label for the subscription.
Name
customer
Type
string
Description
Optional payer identifier (e.g. an email) stamped onto each generated order.
Name
amount
Type
string
Description
Amount charged each cycle, as a decimal string.
Name
currency
Type
string
Description
Pricing currency / asset.
Name
channel
Type
string
Description
The channel each cycle charges on.
Name
channel_name
Type
string
Description
Human-readable display name of that channel, resolved by the platform.
Name
interval_unit
Type
string
Description
day, week, or month.
Name
interval_count
Type
integer
Description
Number of units per billing period.
Name
status
Type
string
Description
active, paused, past_due, canceled, or completed.
Name
cycles_done
Type
integer
Description
Charges generated so far; also the next cycle's index.
Name
total_cycles
Type
integer
Description
Cycle cap. 0 means unlimited.
Name
billing_anchor
Type
timestamp
Description
Fixed origin of the schedule (the first charge's due time).
Name
next_charge_at
Type
timestamp
Description
When the next cycle is due.
Name
ends_at
Type
timestamp
Description
Optional hard end — no charge is scheduled past this. May be null.
Name
last_order_id
Type
string
Description
The most recently generated order, or null.
Name
failure_count
Type
integer
Description
Consecutive billing failures (reset on success).
Name
created_at
Type
timestamp
Description
When the subscription was created.

GET/api/v1/subscriptions

List subscriptions

API keyAPI secret

Signed locally — your secret stays in this browser and is never sent or stored.

No keys yet? Create an API key pair in the merchant portal — the secret is shown only once. Open the merchant portal →

Query string

Return your subscriptions as a plain data array.

Request

GET

/api/v1/subscriptions

curl "$BASE/api/v1/subscriptions" \
  -H "X-Api-Key: $KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG"

Response

{
  "data": [
    {
      "id": "sub_9Qw8",
      "title": "Pro plan",
      "amount": "19.00",
      "currency": "USDT",
      "channel": "usdt_erc20",
      "interval_unit": "month",
      "interval_count": 1,
      "status": "active",
      "cycles_done": 2,
      "total_cycles": 0,
      "next_charge_at": "2026-07-11T00:00:00Z"
    }
  ]
}

POST/api/v1/subscriptions

Create a subscription

API keyAPI secret

Signed locally — your secret stays in this browser and is never sent or stored.

No keys yet? Create an API key pair in the merchant portal — the secret is shown only once. Open the merchant portal →

Request body

Create a recurring schedule.

Required attributes

Name
amount
Type
string
Description
Amount per cycle, as a decimal string.
Name
currency
Type
string
Description
Pricing currency / asset.
Name
channel
Type
string
Description
Channel code each cycle charges on.
Name
interval_unit
Type
string
Description
day, week, or month.

Optional attributes

Name
title
Type
string
Description
Human label.
Name
customer
Type
string
Description
Payer identifier stamped onto each order.
Name
interval_count
Type
integer
Description
Units per period. Defaults to 1.
Name
total_cycles
Type
integer
Description
Stop after this many cycles. 0 (default) means unlimited.
Name
ends_at
Type
timestamp
Description
Hard end date (RFC 3339).
Name
starts_at
Type
timestamp
Description
First charge's due time (honored on create only). Defaults to now.

Request

POST

/api/v1/subscriptions

curl "$BASE/api/v1/subscriptions" \
  -H "X-Api-Key: $KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Pro plan",
    "customer": "ada@example.com",
    "amount": "19.00",
    "currency": "USDT",
    "channel": "usdt_erc20",
    "interval_unit": "month",
    "interval_count": 1
  }'

Response

{
  "id": "sub_9Qw8",
  "title": "Pro plan",
  "customer": "ada@example.com",
  "amount": "19.00",
  "currency": "USDT",
  "channel": "usdt_erc20",
  "interval_unit": "month",
  "interval_count": 1,
  "status": "active",
  "cycles_done": 0,
  "total_cycles": 0,
  "next_charge_at": "2026-06-11T00:00:00Z"
}

GET/api/v1/subscriptions/:id

Retrieve a subscription

API keyAPI secret

Signed locally — your secret stays in this browser and is never sent or stored.

No keys yet? Create an API key pair in the merchant portal — the secret is shown only once. Open the merchant portal →

Path parameters · id

Query string

Fetch one subscription plus its recent generated orders (its billing history).

Request

GET

/api/v1/subscriptions/sub_9Qw8

curl "$BASE/api/v1/subscriptions/sub_9Qw8" \
  -H "X-Api-Key: $KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG"

Response

{
  "subscription": {
    "id": "sub_9Qw8",
    "status": "active",
    "cycles_done": 2,
    "next_charge_at": "2026-07-11T00:00:00Z"
  },
  "orders": [
    { "id": "ord_5K2m", "status": "paid", "amount": "19.00" }
  ]
}

PUT/api/v1/subscriptions/:id

Update a subscription

API keyAPI secret

Signed locally — your secret stays in this browser and is never sent or stored.

No keys yet? Create an API key pair in the merchant portal — the secret is shown only once. Open the merchant portal →

Path parameters · id

Query stringRequest body

Edit the subscription's amount, currency, channel, title, customer, interval and end conditions. The schedule columns (cycles_done, next_charge_at, status) are not touched. Send the editable fields just as for create (starts_at is ignored here).

Request

PUT

/api/v1/subscriptions/sub_9Qw8

curl -X PUT "$BASE/api/v1/subscriptions/sub_9Qw8" \
  -H "X-Api-Key: $KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Pro plan (annual)",
    "amount": "190.00",
    "currency": "USDT",
    "channel": "usdt_erc20",
    "interval_unit": "month",
    "interval_count": 12
  }'

PATCH/api/v1/subscriptions/:id

Change status

API keyAPI secret

Signed locally — your secret stays in this browser and is never sent or stored.

No keys yet? Create an API key pair in the merchant portal — the secret is shown only once. Open the merchant portal →

Path parameters · id

Query stringRequest body

Pause, resume or cancel a subscription.

Required attributes

Name
status
Type
string
Description
active (resume), paused, or canceled.

Request

PATCH

/api/v1/subscriptions/sub_9Qw8

curl -X PATCH "$BASE/api/v1/subscriptions/sub_9Qw8" \
  -H "X-Api-Key: $KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'

Response

{
  "id": "sub_9Qw8",
  "status": "paused"
}