Subscriptions API

The Subscriptions API allows you to create and manage recurring billing for your customers.

The Subscription Object

{
  "id": "sub_abc123def456",
  "object": "subscription",
  "status": "active",
  "customer": "cus_xyz789",
  "plan": {
    "id": "plan_abc123",
    "name": "Pro Monthly",
    "amount": 5000,
    "currency": "GHS",
    "interval": "month"
  },
  "current_period_start": "2024-01-15T00:00:00Z",
  "current_period_end": "2024-02-15T00:00:00Z",
  "trial_start": "2024-01-01T00:00:00Z",
  "trial_end": "2024-01-15T00:00:00Z",
  "cancel_at_period_end": false,
  "canceled_at": null,
  "ended_at": null,
  "metadata": {},
  "created_at": "2024-01-01T10:00:00Z"
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier
`object`	string	Always `"subscription"`
`status`	string	`trialing`, `active`, `past_due`, `canceled`, `unpaid`, `paused`
`customer`	string	Customer ID
`plan`	object	The subscription plan
`current_period_start`	string	Start of current billing period
`current_period_end`	string	End of current billing period
`trial_start`	string	Trial start timestamp
`trial_end`	string	Trial end timestamp
`cancel_at_period_end`	boolean	Cancel at end of period
`canceled_at`	string	When subscription was canceled
`ended_at`	string	When subscription ended
`metadata`	object	Custom metadata
`created_at`	string	Creation timestamp

Create a Subscription

Creates a new subscription for a customer.

POST /v1/subscriptions

Request Body

Parameter	Type	Required	Description
`customer`	string	Yes	Customer ID
`plan`	string	Yes	Plan ID
`payment_method`	object	Yes	Default payment method
`trial_period_days`	integer	No	Override plan trial
`metadata`	object	No	Custom metadata

curl -X POST https://api.44.200.142.19.nip.io/v1/subscriptions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_xyz789",
    "plan": "plan_abc123",
    "payment_method": {
      "type": "mobile_money",
      "phone": "0241234567",
      "provider": "mtn"
    }
  }'

const subscription = await paygate.subscriptions.create({
  customer: 'cus_xyz789',
  plan: 'plan_abc123',
  payment_method: {
    type: 'mobile_money',
    phone: '0241234567',
    provider: 'mtn'
  }
})

subscription = client.subscriptions.create(
    customer='cus_xyz789',
    plan='plan_abc123',
    payment_method={
        'type': 'mobile_money',
        'phone': '0241234567',
        'provider': 'mtn'
    }
)

$subscription = $paygate->subscriptions->create([
    'customer' => 'cus_xyz789',
    'plan' => 'plan_abc123',
    'payment_method' => [
        'type' => 'mobile_money',
        'phone' => '0241234567',
        'provider' => 'mtn'
    ]
]);

Retrieve a Subscription

Retrieves a subscription by ID.

GET /v1/subscriptions/:id

curl https://api.44.200.142.19.nip.io/v1/subscriptions/sub_abc123def456 \
  -H "Authorization: Bearer sk_test_..."

const subscription = await paygate.subscriptions.retrieve('sub_abc123def456')

subscription = client.subscriptions.retrieve('sub_abc123def456')

Update a Subscription

Updates a subscription.

PATCH /v1/subscriptions/:id

Request Body

Parameter	Type	Description
`plan`	string	New plan ID (upgrade/downgrade)
`payment_method`	object	New payment method
`cancel_at_period_end`	boolean	Cancel at period end
`metadata`	object	Custom metadata
`proration_behavior`	string	`create_prorations`, `none`

curl -X PATCH https://api.44.200.142.19.nip.io/v1/subscriptions/sub_abc123def456 \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "plan_premium",
    "proration_behavior": "create_prorations"
  }'

const subscription = await paygate.subscriptions.update('sub_abc123def456', {
  plan: 'plan_premium',
  proration_behavior: 'create_prorations'
})

subscription = client.subscriptions.update('sub_abc123def456',
    plan='plan_premium',
    proration_behavior='create_prorations'
)

Cancel a Subscription

Cancels a subscription.

POST /v1/subscriptions/:id/cancel

Request Body

Parameter	Type	Description
`cancel_at_period_end`	boolean	If true, cancel at period end

Use cancel_at_period_end: true to let customers use their remaining time.

# Cancel at period end
curl -X POST https://api.44.200.142.19.nip.io/v1/subscriptions/sub_abc123def456/cancel \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"cancel_at_period_end": true}'

# Cancel immediately
curl -X POST https://api.44.200.142.19.nip.io/v1/subscriptions/sub_abc123def456/cancel \
  -H "Authorization: Bearer sk_test_..."

// Cancel at period end
await paygate.subscriptions.update('sub_abc123def456', {
  cancel_at_period_end: true
})

// Cancel immediately
await paygate.subscriptions.cancel('sub_abc123def456')

# Cancel at period end
client.subscriptions.update('sub_abc123def456',
    cancel_at_period_end=True
)

# Cancel immediately
client.subscriptions.cancel('sub_abc123def456')

Pause a Subscription

Pauses a subscription.

POST /v1/subscriptions/:id/pause

curl -X POST https://api.44.200.142.19.nip.io/v1/subscriptions/sub_abc123def456/pause \
  -H "Authorization: Bearer sk_test_..."

const subscription = await paygate.subscriptions.pause('sub_abc123def456')

subscription = client.subscriptions.pause('sub_abc123def456')

Resume a Subscription

Resumes a paused subscription.

POST /v1/subscriptions/:id/resume

curl -X POST https://api.44.200.142.19.nip.io/v1/subscriptions/sub_abc123def456/resume \
  -H "Authorization: Bearer sk_test_..."

const subscription = await paygate.subscriptions.resume('sub_abc123def456')

subscription = client.subscriptions.resume('sub_abc123def456')

List Subscriptions

Returns a list of subscriptions.

GET /v1/subscriptions

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (1-100)
`starting_after`	string	Cursor for pagination
`customer`	string	Filter by customer ID
`status`	string	Filter by status
`plan`	string	Filter by plan ID

curl "https://api.44.200.142.19.nip.io/v1/subscriptions?status=active&limit=10" \
  -H "Authorization: Bearer sk_test_..."

const subscriptions = await paygate.subscriptions.list({
  status: 'active',
  limit: 10
})

subscriptions = client.subscriptions.list(status='active', limit=10)

Response

{
  "object": "list",
  "data": [
    {
      "id": "sub_abc123def456",
      "object": "subscription",
      "status": "active",
      ...
    }
  ],
  "has_more": false,
  "url": "/v1/subscriptions"
}

Subscriptions

On this page