Create a subscription | Prolifi

curl -X POST https://api.prolifi.co/api/v1/public/subscriptions \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "customer_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "plan_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "billing_cycle": "yearly",
  "start_date": "2026-04-01",
  "quantity": 5
}'

{
  "data": {
    "id": "string",
    "customer_id": "string",
    "plan_id": "string",
    "plan_name": "string",
    "status": "active",
    "billing_cycle": "string",
    "current_period_start": "2023-01-15",
    "current_period_end": "2023-01-15",
    "start_date": "2023-01-15",
    "billing_date": "2023-01-15",
    "cancel_at": "2024-01-15T09:30:00Z",
    "canceled_at": "2024-01-15T09:30:00Z",
    "pause_start": "2024-01-15T09:30:00Z",
    "pause_end": "2024-01-15T09:30:00Z",
    "pricing": {
      "amount": 1.1,
      "currency": "string",
      "pricing_scheme_id": "string"
    },
    "metadata": {},
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
}

Creates a new subscription linking a customer to a plan. The subscription is activated immediately.

The billing_cycle can be a UUID (billing cycle ID) or a name like "monthly" or "yearly" — it will be matched against the plan’s available billing cycles.

If country_id is not provided, it is resolved from the customer’s record.

Authentication

AuthorizationBearer

Use a secret key (sk_test_* or sk_live_*) for full read/write access, or a public key (pk_test_* or pk_live_*) for read-only access.

Request

This endpoint expects an object.

customer_idstringRequiredformat: "uuid"

The customer to subscribe.

plan_idstringRequiredformat: "uuid"

The plan to subscribe to.

billing_cyclestring or nullOptional

Billing cycle UUID or name (e.g., "monthly", "yearly"). Defaults to the plan’s first billing cycle.

start_datedate or nullOptional

Subscription start date. Defaults to today.

billing_datedate or nullOptional

First billing date. Defaults to start date.

country_idstring or nullOptionalformat: "uuid"

Country for tax and currency. Resolved from customer if not provided.

pricing_scheme_idstring or nullOptionalformat: "uuid"

Override the plan's default pricing scheme.

payment_term_idstring or nullOptionalformat: "uuid"

quantityinteger or nullOptional>=1

Seat count or quantity (for per-unit pricing).

metadataobject or nullOptional

Response

Subscription created successfully

dataobjectOptional

Errors

401

Unauthorized Error

403

Forbidden Error

422

Unprocessable Entity Error