feat: Add on_resume support to subscription resume and pause operations (#111)

Author: davidgrayston-paddle

CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 Check our main [developer changelog](https://developer.paddle.com/?utm_source=dx&utm_medium=paddle-php-sdk) for information about changes to the Paddle Billing platform, the Paddle API, and other developer tools.
 
+## [1.8.0] - 2024-12-19
+
+### Added
+
+- Added `on_resume` support to subscription resume and pause operations
+
 ## [1.7.2] - 2024-12-17
 
 ### Fixed

src/Client.php

@@ -60,7 +60,7 @@
 
 class Client
 {
-    private const SDK_VERSION = '1.7.2';
+    private const SDK_VERSION = '1.8.0';
 
     public readonly LoggerInterface $logger;
     public readonly Options $options;

src/Entities/Subscription/SubscriptionOnResume.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * |------
+ * | ! Generated code !
+ * | Altering this code will result in changes being overwritten |
+ * |-------------------------------------------------------------|.
+ */
+
+namespace Paddle\SDK\Entities\Subscription;
+
+use Paddle\SDK\PaddleEnum;
+
+/**
+ * @method static SubscriptionOnResume ContinueExistingBillingPeriod()
+ * @method static SubscriptionOnResume StartNewBillingPeriod()
+ */
+final class SubscriptionOnResume extends PaddleEnum
+{
+    private const ContinueExistingBillingPeriod = 'continue_existing_billing_period';
+    private const StartNewBillingPeriod = 'start_new_billing_period';
+}

src/Resources/Subscriptions/Operations/PauseSubscription.php

@@ -6,20 +6,27 @@
 
 use Paddle\SDK\Entities\DateTime;
 use Paddle\SDK\Entities\Subscription\SubscriptionEffectiveFrom;
+use Paddle\SDK\Entities\Subscription\SubscriptionOnResume;
+use Paddle\SDK\FiltersUndefined;
+use Paddle\SDK\Undefined;
 
 class PauseSubscription implements \JsonSerializable
 {
+    use FiltersUndefined;
+
     public function __construct(
         public readonly SubscriptionEffectiveFrom|null $effectiveFrom = null,
         public readonly \DateTimeInterface|null $resumeAt = null,
+        public readonly SubscriptionOnResume|Undefined $onResume = new Undefined(),
     ) {
     }
 
     public function jsonSerialize(): array
     {
-        return [
+        return $this->filterUndefined([
             'effective_from' => $this->effectiveFrom,
             'resume_at' => isset($this->resumeAt) ? DateTime::from($this->resumeAt)?->format() : null,
-        ];
+            'on_resume' => $this->onResume,
+        ]);
     }
 }

src/Resources/Subscriptions/Operations/ResumeSubscription.php

@@ -5,21 +5,28 @@
 namespace Paddle\SDK\Resources\Subscriptions\Operations;
 
 use Paddle\SDK\Entities\DateTime;
+use Paddle\SDK\Entities\Subscription\SubscriptionOnResume;
 use Paddle\SDK\Entities\Subscription\SubscriptionResumeEffectiveFrom;
+use Paddle\SDK\FiltersUndefined;
+use Paddle\SDK\Undefined;
 
 class ResumeSubscription implements \JsonSerializable
 {
+    use FiltersUndefined;
+
     public function __construct(
         public readonly SubscriptionResumeEffectiveFrom|\DateTimeInterface|null $effectiveFrom = null,
+        public readonly SubscriptionOnResume|Undefined $onResume = new Undefined(),
     ) {
     }
 
     public function jsonSerialize(): array
     {
-        return [
+        return $this->filterUndefined([
             'effective_from' => $this->effectiveFrom instanceof \DateTimeInterface
                 ? DateTime::from($this->effectiveFrom)?->format()
                 : $this->effectiveFrom,
-        ];
+            'on_resume' => $this->onResume,
+        ]);
     }
 }

tests/Functional/Resources/Subscriptions/SubscriptionsClientTest.php

@@ -24,6 +24,7 @@
 use Paddle\SDK\Entities\Subscription\SubscriptionNonCatalogPriceWithProduct;
 use Paddle\SDK\Entities\Subscription\SubscriptionNonCatalogProduct;
 use Paddle\SDK\Entities\Subscription\SubscriptionOnPaymentFailure;
+use Paddle\SDK\Entities\Subscription\SubscriptionOnResume;
 use Paddle\SDK\Entities\Subscription\SubscriptionProrationBillingMode;
 use Paddle\SDK\Entities\Subscription\SubscriptionResumeEffectiveFrom;
 use Paddle\SDK\Entities\Subscription\SubscriptionScheduledChangeAction;
@@ -355,6 +356,18 @@ public static function pauseOperationsProvider(): \Generator
             new Response(200, body: self::readRawJsonFixture('response/full_entity')),
             self::readRawJsonFixture('request/pause_full'),
         ];
+
+        yield 'On resume continue existing billing period' => [
+            new PauseSubscription(SubscriptionEffectiveFrom::Immediately(), new \DateTime('2023-10-09T16:30:00Z'), SubscriptionOnResume::ContinueExistingBillingPeriod()),
+            new Response(200, body: self::readRawJsonFixture('response/full_entity')),
+            self::readRawJsonFixture('request/pause_resume_existing_billing_period'),
+        ];
+
+        yield 'On resume start new billing period' => [
+            new PauseSubscription(SubscriptionEffectiveFrom::Immediately(), new \DateTime('2023-10-09T16:30:00Z'), SubscriptionOnResume::StartNewBillingPeriod()),
+            new Response(200, body: self::readRawJsonFixture('response/full_entity')),
+            self::readRawJsonFixture('request/pause_resume_new_billing_period'),
+        ];
     }
 
     /**
@@ -399,6 +412,18 @@ public static function resumeOperationsProvider(): \Generator
             new Response(200, body: self::readRawJsonFixture('response/full_entity')),
             self::readRawJsonFixture('request/resume_single_as_date'),
         ];
+
+        yield 'On resume continue existing billing period' => [
+            new ResumeSubscription(SubscriptionResumeEffectiveFrom::Immediately(), SubscriptionOnResume::ContinueExistingBillingPeriod()),
+            new Response(200, body: self::readRawJsonFixture('response/full_entity')),
+            self::readRawJsonFixture('request/resume_existing_billing_period'),
+        ];
+
+        yield 'On resume start new billing period' => [
+            new ResumeSubscription(SubscriptionResumeEffectiveFrom::Immediately(), SubscriptionOnResume::StartNewBillingPeriod()),
+            new Response(200, body: self::readRawJsonFixture('response/full_entity')),
+            self::readRawJsonFixture('request/resume_new_billing_period'),
+        ];
     }
 
     /**

tests/Functional/Resources/Subscriptions/_fixtures/request/pause_resume_existing_billing_period.json

@@ -0,0 +1,5 @@
+{
+    "effective_from": "immediately",
+    "resume_at": "2023-10-09T16:30:00.000000Z",
+    "on_resume": "continue_existing_billing_period"
+}

tests/Functional/Resources/Subscriptions/_fixtures/request/pause_resume_new_billing_period.json

@@ -0,0 +1,5 @@
+{
+    "effective_from": "immediately",
+    "resume_at": "2023-10-09T16:30:00.000000Z",
+    "on_resume": "start_new_billing_period"
+}

tests/Functional/Resources/Subscriptions/_fixtures/request/resume_existing_billing_period.json

@@ -0,0 +1,4 @@
+{
+    "effective_from": "immediately",
+    "on_resume": "continue_existing_billing_period"
+}

tests/Functional/Resources/Subscriptions/_fixtures/request/resume_new_billing_period.json

@@ -0,0 +1,4 @@
+{
+    "effective_from": "immediately",
+    "on_resume": "start_new_billing_period"
+}