From d4dad5edd6da04a42c60fe94e4ef96d5cc7a05f1 Mon Sep 17 00:00:00 2001
From: Sander van Hooft <sandervanhooft@users.noreply.github.com>
Date: Wed, 25 Feb 2026 17:34:20 +0100
Subject: [PATCH] Align SDK docs with OpenAPI spec

- Orders: remove invalid 'refunded' status (valid: pending, paid, failed)
- Subscriptions: fix statuses to match spec (active, created, trial, on_grace_period, paused)
- Refunds: fix 'succeeded' to 'completed', add 'canceled' status
- Chargebacks: remove non-existent status field, align properties with spec
- Subscription Plans: replace 'active' bool with status enum (approved, draft, archived)
- One-Off Products: replace 'active' bool with status enum (approved, draft, archived)
- Webhooks: fix refund.succeeded to refund.completed
---
 docs/Chargebacks.md       | 47 +++++++++------------------------------
 docs/OneOffProducts.md    |  2 +-
 docs/Orders.md            |  4 +---
 docs/Refunds.md           | 12 +++++-----
 docs/SubscriptionPlans.md |  2 +-
 docs/Subscriptions.md     | 25 +++++++++------------
 docs/Webhooks.md          |  2 +-
 7 files changed, 32 insertions(+), 62 deletions(-)

diff --git a/docs/Chargebacks.md b/docs/Chargebacks.md
index e41c5da..0d9ee4b 100644
--- a/docs/Chargebacks.md
+++ b/docs/Chargebacks.md
@@ -11,12 +11,14 @@ Below you'll find all properties for the Vatly Chargeback resource.
 | Name | Type | Description |
 | --- | --- | --- |
 | `id` | `string` | Unique identifier for the chargeback (`chb_...`). |
-| `status` | `string` | The status: `open`, `won`, or `lost`. |
-| `orderId` | `string` | The disputed order ID. |
-| `amount` | `integer` | Chargeback amount in cents. |
-| `currency` | `string` | Three-letter ISO currency code. |
-| `reason` | `string|null` | Reason provided by the bank. |
+| `resource` | `string` | Always `chargeback`. |
+| `merchantId` | `string` | The merchant ID. |
 | `testmode` | `bool` | Whether this is a test chargeback. |
+| `amount` | `object` | Chargeback amount (`value` and `currency`). |
+| `settlementAmount` | `object` | Amount deducted from settlement (may differ from `amount`). |
+| `reason` | `string` | Reason code for the dispute (e.g. `fraud`, `product_not_received`, `duplicate`). |
+| `originalOrderId` | `string` | The ID of the original order that was disputed. |
+| `orderId` | `string\|null` | The credit note order ID (after processing). |
 | `createdAt` | `string` | Creation timestamp (ISO 8601). |
 
 ---
@@ -35,9 +37,9 @@ Retrieve a chargeback by its ID.
 ```php
 $chargeback = $vatly->chargebacks->get('chb_abc123');
 
-echo $chargeback->status;
-echo $chargeback->amount / 100 . ' ' . $chargeback->currency;
 echo $chargeback->reason;
+echo $chargeback->amount->value . ' ' . $chargeback->amount->currency;
+echo $chargeback->originalOrderId;
 ```
 
 
@@ -66,35 +68,6 @@ Retrieve a paginated list of all chargebacks.
 $chargebacks = $vatly->chargebacks->list();
 
 foreach ($chargebacks as $chargeback) {
-    echo $chargeback->id . ': ' . $chargeback->status;
+    echo $chargeback->id . ': ' . $chargeback->reason;
 }
 ```
-
-
-
----
-
-## Chargeback statuses
-
-| Status | Description |
-|--------|-------------|
-| `open` | Dispute is ongoing |
-| `won` | You won the dispute |
-| `lost` | You lost the dispute |
-
----
-
-## Helper methods
-
-
-
-The Chargeback object provides convenient helper methods.
-
-
-
-
-```php
-$chargeback->isOpen();  // true if status is 'open'
-$chargeback->isWon();   // true if status is 'won'
-$chargeback->isLost();  // true if status is 'lost'
-```
diff --git a/docs/OneOffProducts.md b/docs/OneOffProducts.md
index 645d3bd..34046db 100644
--- a/docs/OneOffProducts.md
+++ b/docs/OneOffProducts.md
@@ -16,7 +16,7 @@ Below you'll find all properties for the Vatly One-Off Product resource.
 | `amount` | `integer` | Price in cents. |
 | `currency` | `string` | Three-letter ISO currency code. |
 | `testmode` | `bool` | Whether this is a test product. |
-| `active` | `bool` | Whether the product is active. |
+| `status` | `string` | The status: `approved`, `draft`, or `archived`. |
 | `createdAt` | `string` | Creation timestamp (ISO 8601). |
 
 ---
diff --git a/docs/Orders.md b/docs/Orders.md
index b884165..83af9da 100644
--- a/docs/Orders.md
+++ b/docs/Orders.md
@@ -11,7 +11,7 @@ Below you'll find all properties for the Vatly Order resource.
 | Name | Type | Description |
 | --- | --- | --- |
 | `id` | `string` | Unique identifier for the order (`ord_...`). |
-| `status` | `string` | The status: `pending`, `paid`, `failed`, or `refunded`. |
+| `status` | `string` | The status: `pending`, `paid`, or `failed`. |
 | `customerId` | `string` | The customer ID. |
 | `checkoutId` | `string|null` | The checkout ID (for initial orders). |
 | `subscriptionId` | `string|null` | The subscription ID (for recurring orders). |
@@ -94,7 +94,6 @@ $orders = $vatly->orders->list([
 | `pending` | Order is awaiting payment |
 | `paid` | Payment successful |
 | `failed` | Payment failed |
-| `refunded` | Order has been refunded |
 
 ---
 
@@ -111,5 +110,4 @@ The Order object provides convenient helper methods.
 $order->isPaid();      // true if status is 'paid'
 $order->isPending();   // true if status is 'pending'
 $order->isFailed();    // true if status is 'failed'
-$order->isRefunded();  // true if status is 'refunded'
 ```
diff --git a/docs/Refunds.md b/docs/Refunds.md
index 99708d9..62fa8b7 100644
--- a/docs/Refunds.md
+++ b/docs/Refunds.md
@@ -11,7 +11,7 @@ Below you'll find all properties for the Vatly Refund resource.
 | Name | Type | Description |
 | --- | --- | --- |
 | `id` | `string` | Unique identifier for the refund (`ref_...`). |
-| `status` | `string` | The status: `pending`, `succeeded`, or `failed`. |
+| `status` | `string` | The status: `pending`, `completed`, `failed`, or `canceled`. |
 | `orderId` | `string` | The order ID being refunded. |
 | `amount` | `integer` | Refund amount in cents. |
 | `currency` | `string` | Three-letter ISO currency code. |
@@ -124,8 +124,9 @@ foreach ($refunds as $refund) {
 | Status | Description |
 |--------|-------------|
 | `pending` | Refund is being processed |
-| `succeeded` | Refund completed successfully |
+| `completed` | Refund completed successfully |
 | `failed` | Refund failed |
+| `canceled` | Refund was canceled |
 
 ---
 
@@ -139,7 +140,8 @@ The Refund object provides convenient helper methods.
 
 
 ```php
-$refund->isPending();    // true if status is 'pending'
-$refund->isSucceeded();  // true if status is 'succeeded'
-$refund->isFailed();     // true if status is 'failed'
+$refund->isPending();     // true if status is 'pending'
+$refund->isCompleted();   // true if status is 'completed'
+$refund->isFailed();      // true if status is 'failed'
+$refund->isCanceled();    // true if status is 'canceled'
 ```
diff --git a/docs/SubscriptionPlans.md b/docs/SubscriptionPlans.md
index 04eb424..3f84442 100644
--- a/docs/SubscriptionPlans.md
+++ b/docs/SubscriptionPlans.md
@@ -19,7 +19,7 @@ Below you'll find all properties for the Vatly Subscription Plan resource.
 | `intervalCount` | `integer` | Number of intervals between billings. |
 | `trialDays` | `integer|null` | Default trial period in days. |
 | `testmode` | `bool` | Whether this is a test plan. |
-| `active` | `bool` | Whether the plan is active. |
+| `status` | `string` | The status: `approved`, `draft`, or `archived`. |
 | `createdAt` | `string` | Creation timestamp (ISO 8601). |
 
 ---
diff --git a/docs/Subscriptions.md b/docs/Subscriptions.md
index ddec1e8..77f8160 100644
--- a/docs/Subscriptions.md
+++ b/docs/Subscriptions.md
@@ -11,7 +11,7 @@ Below you'll find all properties for the Vatly Subscription resource.
 | Name | Type | Description |
 | --- | --- | --- |
 | `id` | `string` | Unique identifier for the subscription (`sub_...`). |
-| `status` | `string` | The status: `active`, `canceled`, `past_due`, `trialing`, `paused`, or `ended`. |
+| `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. |
@@ -102,8 +102,8 @@ Cancel a subscription. The subscription will remain active until the end of the
 ```php
 $subscription = $vatly->subscriptions->cancel('sub_abc123');
 
-// Subscription is now 'canceled' but active until period end
-echo $subscription->status;        // 'canceled'
+// Subscription is now on grace period until current period ends
+echo $subscription->status;        // 'on_grace_period'
 echo $subscription->currentPeriodEnd;  // When it ends
 ```
 
@@ -116,11 +116,10 @@ echo $subscription->currentPeriodEnd;  // When it ends
 | Status | Description |
 |--------|-------------|
 | `active` | Subscription is active and billing |
-| `canceled` | Subscription is canceled, active until period end |
-| `past_due` | Payment failed, in grace period |
-| `trialing` | In trial period |
+| `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 |
-| `ended` | Subscription has ended |
 
 ---
 
@@ -134,11 +133,9 @@ The Subscription object provides convenient helper methods.
 
 
 ```php
-$subscription->isActive();     // true if status is 'active'
-$subscription->isCanceled();   // true if status is 'canceled'
-$subscription->isTrialing();   // true if status is 'trialing'
-$subscription->isPastDue();    // true if status is 'past_due'
-$subscription->hasEnded();     // true if status is 'ended'
-$subscription->onTrial();      // true if currently in trial
-$subscription->onGracePeriod(); // true if canceled but still active
+$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'
 ```
diff --git a/docs/Webhooks.md b/docs/Webhooks.md
index 5927184..3f87dd5 100644
--- a/docs/Webhooks.md
+++ b/docs/Webhooks.md
@@ -15,7 +15,7 @@ Vatly sends webhooks to notify your application when events happen, like success
 | `subscription.ended` | Subscription ended |
 | `order.paid` | Order payment received |
 | `refund.created` | Refund initiated |
-| `refund.succeeded` | Refund completed |
+| `refund.completed` | Refund completed |
 | `chargeback.created` | Chargeback received |
 | `chargeback.won` | Chargeback dispute won |
 | `chargeback.lost` | Chargeback dispute lost |