Php
Subscriptions
Vatly PHP SDK - Subscriptions
Subscriptions
Subscriptions are created automatically when a customer completes a checkout for a subscription plan. You can then manage the subscription lifecycle through the API.
The Subscription Resource
Below you'll find all properties for the Vatly Subscription resource.
Properties
| Name | Type | Description |
|---|---|---|
id | string | Unique identifier for the subscription (sub_...). |
status | string | The status: active, created, trial, on_grace_period, or paused. |
customerId | string | The customer ID. |
planId | string | The subscription plan ID. |
testmode | bool | Whether this is a test subscription. |
currentPeriodStart | string | Current billing period start (ISO 8601). |
currentPeriodEnd | string | Current billing period end (ISO 8601). |
canceledAt | `string | null` |
endedAt | `string | null` |
trialStart | `string | null` |
trialEnd | `string | null` |
metadata | array | Your custom metadata. |
createdAt | string | Creation timestamp (ISO 8601). |
Retrieve a subscription
GET /v1/subscriptions/:id
Retrieve a subscription by its ID.
$subscription = $vatly->subscriptions->get('sub_abc123');
echo $subscription->status;
echo $subscription->planId;
if ($subscription->isActive()) {
echo 'Subscription is active';
}
List all subscriptions
GET /v1/subscriptions
Retrieve a paginated list of all subscriptions.
Optional attributes
| Name | Type | Description |
|---|---|---|
limit | integer | The number of subscriptions to return (default: 10, max: 100). |
startingAfter | string | A cursor for pagination. |
customerId | string | Filter by customer ID. |
$subscriptions = $vatly->subscriptions->list();
foreach ($subscriptions as $subscription) {
echo $subscription->id . ': ' . $subscription->status;
}
// Filter by customer
$subscriptions = $vatly->subscriptions->list([
'customerId' => 'cus_abc123',
]);
Cancel a subscription
DELETE /v1/subscriptions/:id
Cancel a subscription. The subscription will remain active until the end of the current billing period.
$subscription = $vatly->subscriptions->cancel('sub_abc123');
// Subscription is now on grace period until current period ends
echo $subscription->status; // 'on_grace_period'
echo $subscription->currentPeriodEnd; // When it ends
Subscription statuses
| Status | Description |
|---|---|
active | Subscription is active and billing |
created | Subscription created, not yet active |
trial | In trial period |
on_grace_period | Canceled but still active until current period ends |
paused | Subscription is paused |
Helper methods
The Subscription object provides convenient helper methods.
$subscription->isActive(); // true if status is 'active'
$subscription->isCreated(); // true if status is 'created'
$subscription->onTrial(); // true if status is 'trial'
$subscription->onGracePeriod(); // true if status is 'on_grace_period'
$subscription->isPaused(); // true if status is 'paused'