Creating Subscriptions

Creating a Subscription

A subscription binds a customer to a specific version of a price plan and activates that plan’s entitlements immediately. Creating a subscription is a single API call:

1
2
3
4
5
6
7
8

curl -X POST "$ABAXUS_URL/v1/subscriptions" \
  -H "Authorization: Bearer $ABAXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_acme",
    "plan_id": "plan_growth",
    "start_date": "2026-04-01T00:00:00Z"
  }'

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "id": "sub_01hx8km4n5p6q7r8s9t0u1v2w",
  "customer_id": "cust_acme",
  "plan_id": "plan_growth",
  "plan_version": 2,
  "status": "active",
  "start_date": "2026-04-01T00:00:00Z",
  "end_date": null,
  "created_at": "2026-04-03T09:01:00Z"
}

Plan Version Pinning

When a subscription is created, ABAXUS records the current plan_version and pins the subscription to it. In the example above, plan_version: 2 means this subscription will always be billed against version 2 of the Growth plan, regardless of future plan changes.

This is the core safety mechanism of ABAXUS’s versioning system. You can publish plan_growth v3 with new pricing tomorrow, and Acme’s subscription continues on v2 until you explicitly schedule a plan change amendment. Historical invoices for this subscription can always be recalculated and will produce the same result.

To subscribe a customer to a specific older version (e.g., a legacy rate you want to honor):

1
2
3
4
5
6
7
8
9

curl -X POST "$ABAXUS_URL/v1/subscriptions" \
  -H "Authorization: Bearer $ABAXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_acme",
    "plan_id": "plan_growth",
    "plan_version": 1,
    "start_date": "2026-04-01T00:00:00Z"
  }'

Entitlements Activate Immediately

As soon as a subscription is created, the plan’s entitlements are reflected in GET /v1/entitlements for that customer. There is no delay or provisioning step. This means your product can check entitlements immediately after the subscription creation response is received.

If a customer has an existing subscription on a lower-tier plan and you create an additional subscription for a premium add-on, their resolved entitlements immediately reflect the union of both plans’ entitlements.

Time-Limited Subscriptions

Set an end_date for trial periods, promotional access, or fixed-term contracts:

1
2
3
4
5
6
7
8
9

curl -X POST "$ABAXUS_URL/v1/subscriptions" \
  -H "Authorization: Bearer $ABAXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_trial",
    "plan_id": "plan_growth",
    "start_date": "2026-04-01T00:00:00Z",
    "end_date": "2026-04-14T23:59:59Z"
  }'

When the end_date is reached, the background worker automatically transitions the subscription to expired status. Entitlements from this subscription are immediately removed from the customer’s resolved entitlement set, and no further billing can occur against this subscription after the end date.

Listing a Customer’s Subscriptions

1
2

curl "$ABAXUS_URL/v1/subscriptions?customer_id=cust_acme&status=active" \
  -H "Authorization: Bearer $ABAXUS_KEY"

A customer can have multiple active subscriptions. Common cases: a base platform subscription plus one or more add-on subscriptions, or a main plan plus a legacy plan you’re migrating away from.