Skip to content

Adopt latest OpenAPI spec from vatlify #29

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sandervanhooft merged 5 commits into from
May 29, 2026
Merged

Adopt latest OpenAPI spec from vatlify #29

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1d1b60b
feat: adopt latest OpenAPI spec from vatlify and add new webhook even…
sandervanhooft May 28, 2026
33b5553
refactor: rename Types\WebhookEvent to WebhookEventName
sandervanhooft May 28, 2026
6e2d4ad
feat: adopt mandate info on subscription responses
sandervanhooft May 29, 2026
791e2d3
feat: adopt latest vatlify spec (US-English canceledAt + currency-awa…
sandervanhooft May 29, 2026
9af7554
docs: reconcile Subscriptions.md with the actual Subscription resource
sandervanhooft May 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 36 additions & 27 deletions docs/Subscriptions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,30 @@ Below you'll find all properties for the Vatly Subscription resource.

### Properties

| Name | Type | Description |
| --- |------------------| --- |
| `id` | `string` | Unique identifier for the subscription (`subscription_...`). |
| `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` | When the subscription was canceled (ISO 8601). |
| `endedAt` | `string \| null` | When the subscription ended (ISO 8601). |
| `trialStart` | `string \| null` | Trial period start (ISO 8601). |
| `trialEnd` | `string \| null` | Trial period end (ISO 8601). |
| `metadata` | `array` | Your custom metadata. |
| `createdAt` | `string` | Creation timestamp (ISO 8601). |
| Name | Type | Description |
| --- |---------------------| --- |
| `id` | `string` | Unique identifier for the subscription (`subscription_...`). |
| `resource` | `string` | Resource type, always `subscription`. |
| `customerId` | `string` | ID of the customer who owns this subscription. |
| `subscriptionPlanId` | `string` | ID of the subscription plan this subscription is based on. |
| `testmode` | `bool` | Whether this subscription is in test mode. |
| `name` | `string` | Name of the subscription (from the plan). |
| `description` | `string` | Description of the subscription. |
| `billingAddress` | `Address` | Customer's billing address for this subscription. |
| `basePrice` | `Money` | Price per billing cycle before taxes. |
| `quantity` | `int` | Number of subscription units (e.g. seats). |
| `interval` | `string` | Billing interval unit: `day`, `week`, `month`, or `year`. |
| `intervalCount` | `int` | Number of interval units between billing cycles. |
| `status` | `string` | The subscription status (see [Subscription statuses](#subscription-statuses)). |
| `startedAt` | `string` | When the subscription started (ISO 8601). |
| `endedAt` | `string \| null` | When the subscription ended (ISO 8601). |
| `canceledAt` | `string \| null` | When the subscription was canceled (ISO 8601). |
| `renewedAt` | `string \| null` | When the subscription was last renewed (ISO 8601). |
| `renewedUntil` | `string \| null` | Current billing period end date (ISO 8601). |
| `nextRenewalAt` | `string \| null` | When the next renewal will be attempted (ISO 8601). Null if canceled or ended. |
| `trialUntil` | `string \| null` | When the trial period ends (ISO 8601). Null if not in trial or trial has ended. |
| `mandate` | `Mandate \| null` | Payment method on file (`method`, `maskedIdentifier`). Null when the subscription has no mandate yet. |
| `links` | `SubscriptionLinks` | HATEOAS links to related resources (`self`, `customer`). |

---

Expand All @@ -41,7 +50,7 @@ Retrieve a subscription by its ID.
$subscription = $vatly->subscriptions->get('subscription_abc123');

echo $subscription->status;
echo $subscription->planId;
echo $subscription->subscriptionPlanId;

if ($subscription->isActive()) {
echo 'Subscription is active';
Expand Down Expand Up @@ -136,7 +145,7 @@ $subscription = $vatly->subscriptions->cancel('subscription_abc123');

// Subscription is now on grace period until current period ends
echo $subscription->status; // 'on_grace_period'
echo $subscription->currentPeriodEnd; // When it ends
echo $subscription->renewedUntil; // Current billing period end
```


Expand Down Expand Up @@ -174,11 +183,12 @@ $subscription->resume();

| 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 |
| `active` | Subscription is active and will renew |
| `created` | Subscription has been created but not yet started |
| `trial` | Subscription is in trial period |
| `on_grace_period` | Subscription is canceled but still active until the period ends |
| `paused` | Subscription is temporarily paused |
| `canceled` | Subscription has been canceled |

---

Expand All @@ -192,9 +202,8 @@ The Subscription object provides convenient helper methods.


```php
$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'
$subscription->isActive(); // true if status is 'active'
$subscription->isTrial(); // true if status is 'trial'
$subscription->isOnGracePeriod(); // true if status is 'on_grace_period'
$subscription->isCanceled(); // true if status is 'canceled'
```
7 changes: 6 additions & 1 deletion docs/Webhooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,26 @@ Vatly sends webhooks to notify your application when events happen — for examp

## Webhook events

The `eventName` field on a delivery identifies what happened. See [`Vatly\API\Types\WebhookEvent`](../src/API/Types/WebhookEvent.php) for the constants.
The `eventName` field on a delivery identifies what happened. See [`Vatly\API\Types\WebhookEventName`](../src/API/Types/WebhookEventName.php) for the constants.

| Event | Description |
|-------|-------------|
| `order.paid` | Order payment was successful. |
| `order.canceled` | Order was canceled. |
| `order.chargeback_received` | Chargeback was received for an order. |
| `order.chargeback_reversed` | Chargeback was reversed. |
| `payment.failed` | A payment failed and a dunning process was initiated for the order. |
| `refund.completed` | Refund was processed successfully. |
| `refund.failed` | Refund processing failed. |
| `refund.canceled` | Refund was canceled. |
| `subscription.started` | Subscription was started. |
| `subscription.canceled_immediately` | Subscription was canceled immediately. |
| `subscription.canceled_with_grace_period` | Subscription was canceled, customer keeps access until the period ends. |
| `subscription.cancellation_grace_period_completed` | Grace period after cancellation ended. |
| `subscription.resumed` | A canceled subscription was resumed during its grace period. |
| `checkout.paid` | Checkout was paid successfully. |
| `checkout.failed` | Checkout payment failed. |
| `checkout.canceled` | Checkout was canceled. |
| `checkout.expired` | Checkout session expired. |

---
Expand Down
Loading