Documentation

Subscriptions

Subscriptions

Use the subscriptions API to set up recurring billing for your customers. Subscriptions handle the full lifecycle: creation, confirmation, updates, pausing, resumption, and cancellation.

Create and Confirm a Subscription

POST /subscriptions

This creates a subscription and immediately attempts to confirm the first payment.

GET //sandbox.perfectpay.ai/subscriptions
curl https://sandbox.perfectpay.ai/subscriptions \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_abc123",
    "plan_id": "plan_monthly_4999",
    "payment_method_id": "pm_abc123",
    "return_url": "https://example.com/account/subscriptions"
  }'

Create a Subscription (Without Confirming)

POST /subscriptions/create

Use this when you want to create the subscription first and confirm it separately.

GET //sandbox.perfectpay.ai/subscriptions/create
curl https://sandbox.perfectpay.ai/subscriptions/create \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_abc123",
    "plan_id": "plan_monthly_4999"
  }'

Confirm a Subscription

POST /subscriptions/{subscription_id}/confirm

GET //sandbox.perfectpay.ai/subscriptions/sub_abc123/confirm
curl https://sandbox.perfectpay.ai/subscriptions/sub_abc123/confirm \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method_id": "pm_abc123"
  }'

Retrieve a Subscription

GET /subscriptions/{subscription_id}

GET //sandbox.perfectpay.ai/subscriptions/sub_abc123
curl https://sandbox.perfectpay.ai/subscriptions/sub_abc123 \
  -H "api-key: YOUR_SECRET_API_KEY"

Update a Subscription

PUT /subscriptions/{subscription_id}/update

GET //sandbox.perfectpay.ai/subscriptions/sub_abc123/update
curl https://sandbox.perfectpay.ai/subscriptions/sub_abc123/update \
  -X PUT \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "plan_annual_49999"
  }'

Pause a Subscription

POST /subscriptions/{subscription_id}/pause

GET //sandbox.perfectpay.ai/subscriptions/sub_abc123/pause
curl https://sandbox.perfectpay.ai/subscriptions/sub_abc123/pause \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Resume a Subscription

POST /subscriptions/{subscription_id}/resume

GET //sandbox.perfectpay.ai/subscriptions/sub_abc123/resume
curl https://sandbox.perfectpay.ai/subscriptions/sub_abc123/resume \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Cancel a Subscription

POST /subscriptions/{subscription_id}/cancel

GET //sandbox.perfectpay.ai/subscriptions/sub_abc123/cancel
curl https://sandbox.perfectpay.ai/subscriptions/sub_abc123/cancel \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Get Subscription Plans

GET /subscriptions/plans

GET //sandbox.perfectpay.ai/subscriptions/plans
curl https://sandbox.perfectpay.ai/subscriptions/plans \
  -H "api-key: YOUR_SECRET_API_KEY"

Use this to list available plans when building a plan selector in your UI.

Subscription Lifecycle

Code
create --> confirm --> active --> pause --> resume --> cancel
                        |                               |
                        +--------> cancel --------------+
  • active: The subscription is live and will generate payments on the billing cycle
  • paused: Billing is suspended but the subscription still exists
  • cancelled: The subscription is terminated and no further payments will be attempted