Subscriptions

Recurring billing and subscription management.

Subscriptions can be created through checkout sessions with recurring products, or directly via the API using a stored customer's payment method.

Not available over the API on Paysio Debit & Payouts

POST /subscriptions returns 400 on Debit & Payouts workspaces: the processor requires the card security code for every charge and the API never stores it. Use hosted Checkout Sessions with recurring products instead — they fully support subscriptions. Listing, cancelling, pausing, and resuming existing subscriptions still work.

Create Subscription

Create a subscription by charging a stored customer's payment method. The first payment is charged immediately, unless a future start_date is provided — in which case the subscription is created with status 'scheduled' and no payment is charged until that date.

POSThttps://paysio.com/api/v1/subscriptions

Authorizations

Authorizationstringheaderrequired

Secret key (sk_*). Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Body

customer_idstringrequired

ID of the customer with a stored payment method

product_idstringrequired

ID of a recurring product

payment_method_idstring

Charge a SPECIFIC saved method instead of the customer's default. Use an id from GET /customers/:id/payment-methods (the "vault_…" form or the bare UUID). It must belong to this customer and have been used at your business, otherwise the call returns 400 — a subscription is never silently created against a different card. Omit to use the default method.

start_datestring

ISO 8601 date. If in the future, creates a scheduled subscription that activates on this date. The customer is not charged until then.

metadataobject

Arbitrary key-value metadata (optional)

Example request — cURL

curl -X POST https://paysio.com/api/v1/subscriptions \
  -H "Authorization: Bearer sk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_id": "...",
  "product_id": "..."
}'

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/subscriptions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "customer_id": "...",
    "product_id": "..."
  }),
})
const data = await res.json()

Example response (200)

// Immediate (no start_date):
{
  "data": {
    "id": "sub_uuid",
    "customer_id": "cus_uuid",
    "product_id": "prod_uuid",
    "status": "active",
    "amount": 2700,
    "currency": "USD",
    "billing_period": "monthly",
    "current_period_start": "2026-04-11T00:00:00.000Z",
    "current_period_end": "2026-05-11T00:00:00.000Z",
    "next_billing_date": "2026-05-11T00:00:00.000Z",
    "transaction_id": "tx_uuid"
  }
}

// Scheduled (start_date in the future):
{
  "data": {
    "id": "sub_uuid",
    "customer_id": "cus_uuid",
    "product_id": "prod_uuid",
    "status": "scheduled",
    "amount": 2700,
    "currency": "USD",
    "billing_period": "monthly",
    "start_date": "2026-05-11T00:00:00.000Z",
    "current_period_start": "2026-05-11T00:00:00.000Z",
    "current_period_end": "2026-06-11T00:00:00.000Z",
    "next_billing_date": "2026-05-11T00:00:00.000Z"
  }
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

List Subscriptions

List subscriptions with customer and product details.

GEThttps://paysio.com/api/v1/subscriptions

Authorizations

Authorizationstringheaderrequired

Any API key. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Query parameters

limitinteger

1-100, default 10

starting_afterstring

Cursor for pagination

Example request — cURL

curl -X GET https://paysio.com/api/v1/subscriptions \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/subscriptions", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": [
    {
      "id": "sub_5c4d3e2f-1a0b-49c8-8d7e-6f5a4b3c2d1e",
      "customerId": "cus_8f2a1c9e-4b3d-47a1-9e12-0a5f6c7d8b90",
      "productId": "prd_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "status": "active",
      "amount": 2999,
      "taxAmount": 0,
      "shippingAmount": 0,
      "discountAmount": 0,
      "currency": "USD",
      "billingPeriod": "monthly",
      "currentPeriodStart": "2026-06-28T14:12:06.882Z",
      "currentPeriodEnd": "2026-07-28T14:12:06.882Z",
      "nextBillingDate": "2026-07-28T14:12:06.882Z",
      "cancelAtPeriodEnd": false,
      "pausedAt": null,
      "cancelledAt": null,
      "metadata": {},
      "sandbox": false,
      "createdAt": "2026-06-28T14:12:06.882Z",
      "customerEmail": "[email protected]",
      "productName": "Pro Plan"
    }
  ],
  "has_more": false
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Get Subscription

Retrieve a single subscription. Includes cancel_at_period_end field.

GEThttps://paysio.com/api/v1/subscriptions/:id

Authorizations

Authorizationstringheaderrequired

Any API key. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Example request — cURL

curl -X GET https://paysio.com/api/v1/subscriptions/:id \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/subscriptions/:id", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": {
    "id": "sub_5c4d3e2f-1a0b-49c8-8d7e-6f5a4b3c2d1e",
    "workspaceId": "3d9b2e10-7c44-4a2f-bb8e-1f6a2c3d4e5f",
    "customerId": "cus_8f2a1c9e-4b3d-47a1-9e12-0a5f6c7d8b90",
    "productId": "prd_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "status": "active",
    "amount": 2999,
    "taxAmount": 0,
    "shippingAmount": 0,
    "currency": "USD",
    "billingPeriod": "monthly",
    "currentPeriodStart": "2026-06-28T14:12:06.882Z",
    "currentPeriodEnd": "2026-07-28T14:12:06.882Z",
    "nextBillingDate": "2026-07-28T14:12:06.882Z",
    "cancelAtPeriodEnd": false,
    "pausedAt": null,
    "cancelledAt": null,
    "processorType": "nmi",
    "rail": "card",
    "cardLastFour": "4242",
    "cardType": "visa",
    "discountCode": null,
    "discountAmount": 0,
    "metadata": {},
    "sandbox": false,
    "createdAt": "2026-06-28T14:12:06.882Z",
    "updatedAt": "2026-06-28T14:12:06.882Z"
  }
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Cancel Subscription

Cancel a subscription. Supports immediate cancellation or scheduling cancellation at the end of the current billing period. Note: subscriptions with status 'scheduled' (created with a future start_date) are always cancelled immediately regardless of the at_period_end flag.

POSThttps://paysio.com/api/v1/subscriptions/:id/cancel

Authorizations

Authorizationstringheaderrequired

Secret key (sk_*). Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Body

reasonstring

Cancellation reason (optional)

at_period_endboolean

If true, subscription stays active until current period ends. Default: false. Ignored for scheduled subscriptions.

Example request — cURL

curl -X POST https://paysio.com/api/v1/subscriptions/:id/cancel \
  -H "Authorization: Bearer sk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "...",
  "at_period_end": false
}'

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/subscriptions/:id/cancel", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "reason": "...",
    "at_period_end": false
  }),
})
const data = await res.json()

Example response (200)

// Immediate cancellation:
{
  "data": { "id": "uuid", "status": "cancelled" }
}

// Scheduled (at_period_end: true):
{
  "data": {
    "id": "uuid",
    "status": "active",
    "cancel_at_period_end": true,
    "cancel_at": "2026-05-11T00:00:00.000Z"
  }
}

// Cancelling a scheduled subscription (always immediate):
{
  "data": { "id": "uuid", "status": "cancelled" }
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Pause Subscription

Pause an active subscription. Billing is suspended until resumed.

POSThttps://paysio.com/api/v1/subscriptions/:id/pause

Authorizations

Authorizationstringheaderrequired

Secret key (sk_*). Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Example request — cURL

curl -X POST https://paysio.com/api/v1/subscriptions/:id/pause \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/subscriptions/:id/pause", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": {
    "id": "uuid",
    "status": "paused"
  }
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Resume Subscription

Resume a paused subscription. Billing dates are extended by the paused duration.

POSThttps://paysio.com/api/v1/subscriptions/:id/resume

Authorizations

Authorizationstringheaderrequired

Secret key (sk_*). Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Example request — cURL

curl -X POST https://paysio.com/api/v1/subscriptions/:id/resume \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/subscriptions/:id/resume", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": {
    "id": "uuid",
    "status": "active"
  }
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}