feat: Add support for payout reconciliation reports, remittance_reference and location value for price.tax_mode (#144)

Author: davidgrayston-paddle

CHANGELOG.md

@@ -6,6 +6,13 @@ 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.
 
+## [Unreleased]
+
+### Added
+
+- Support for payout reconciliation reports and `remittance_reference`, see [changelog](https://developer.paddle.com/changelog/2025/payout-reconciliation-report?utm_source=dx&utm_medium=paddle-php-sdk)
+- Added `location` value for `price.tax_mode`, see [changelog](https://developer.paddle.com/changelog/2025/default-automatic-tax-setting?utm_source=dx&utm_medium=paddle-php-sdk)
+
 ## [1.13.1] - 2025-11-03
 
 _No functional change — aligns versioning metadata with release_ 

src/Entities/Report/ReportFilterName.php

@@ -24,7 +24,9 @@
  * @method static ReportFilterName ProductStatus()
  * @method static ReportFilterName ProductType()
  * @method static ReportFilterName ProductUpdatedAt()
+ * @method static ReportFilterName RemittanceReference()
  * @method static ReportFilterName Status()
+ * @method static ReportFilterName TransactionUpdatedAt()
  * @method static ReportFilterName Type()
  * @method static ReportFilterName UpdatedAt()
  */
@@ -40,7 +42,9 @@ final class ReportFilterName extends PaddleEnum
     private const ProductStatus = 'product_status';
     private const ProductType = 'product_type';
     private const ProductUpdatedAt = 'product_updated_at';
+    private const RemittanceReference = 'remittance_reference';
     private const Status = 'status';
+    private const TransactionUpdatedAt = 'transaction_updated_at';
     private const Type = 'type';
     private const UpdatedAt = 'updated_at';
 }

src/Entities/Shared/TaxMode.php

@@ -17,10 +17,12 @@
  * @method static TaxMode AccountSetting()
  * @method static TaxMode External()
  * @method static TaxMode Internal()
+ * @method static TaxMode Location()
  */
 final class TaxMode extends PaddleEnum
 {
     private const AccountSetting = 'account_setting';
     private const External = 'external';
     private const Internal = 'internal';
+    private const Location = 'location';
 }

src/Notifications/Entities/Payout.php

@@ -14,6 +14,7 @@ private function __construct(
         public PayoutStatus $status,
         public string $amount,
         public CurrencyCodePayouts $currencyCode,
+        public string|null $remittanceReference,
     ) {
     }
 
@@ -24,6 +25,7 @@ public static function from(array $data): self
             PayoutStatus::from($data['status']),
             $data['amount'],
             CurrencyCodePayouts::from($data['currency_code']),
+            $data['remittance_reference'] ?? null,
         );
     }
 }

src/Notifications/Entities/Report/ReportFilterName.php

@@ -24,7 +24,9 @@
  * @method static ReportFilterName ProductStatus()
  * @method static ReportFilterName ProductType()
  * @method static ReportFilterName ProductUpdatedAt()
+ * @method static ReportFilterName RemittanceReference()
  * @method static ReportFilterName Status()
+ * @method static ReportFilterName TransactionUpdatedAt()
  * @method static ReportFilterName Type()
  * @method static ReportFilterName UpdatedAt()
  */
@@ -40,7 +42,9 @@ final class ReportFilterName extends PaddleEnum
     private const ProductStatus = 'product_status';
     private const ProductType = 'product_type';
     private const ProductUpdatedAt = 'product_updated_at';
+    private const RemittanceReference = 'remittance_reference';
     private const Status = 'status';
+    private const TransactionUpdatedAt = 'transaction_updated_at';
     private const Type = 'type';
     private const UpdatedAt = 'updated_at';
 }

src/Notifications/Entities/Shared/TaxMode.php

@@ -17,10 +17,12 @@
  * @method static TaxMode AccountSetting()
  * @method static TaxMode External()
  * @method static TaxMode Internal()
+ * @method static TaxMode Location()
  */
 final class TaxMode extends PaddleEnum
 {
     private const AccountSetting = 'account_setting';
     private const External = 'external';
     private const Internal = 'internal';
+    private const Location = 'location';
 }

src/Notifications/Entities/Simulation/Payout.php

@@ -20,6 +20,7 @@ public function __construct(
         public readonly PayoutStatus|Undefined $status = new Undefined(),
         public readonly string|Undefined $amount = new Undefined(),
         public readonly CurrencyCodePayouts|Undefined $currencyCode = new Undefined(),
+        public string|Undefined $remittanceReference = new Undefined(),
     ) {
     }
 
@@ -30,6 +31,7 @@ public static function from(array $data): self
             status: self::optional($data, 'status', fn ($value) => PayoutStatus::from($value)),
             amount: self::optional($data, 'amount'),
             currencyCode: self::optional($data, 'currency_code', fn ($value) => CurrencyCodePayouts::from($value)),
+            remittanceReference: self::optional($data, 'remittance_reference'),
         );
     }
 
@@ -40,6 +42,7 @@ public function jsonSerialize(): mixed
             'status' => $this->status,
             'amount' => $this->amount,
             'currency_code' => $this->currencyCode,
+            'remittance_reference' => $this->remittanceReference,
         ]);
     }
 }

tests/Unit/Entities/_fixtures/notification/entity/payout.paid.json

@@ -2,5 +2,6 @@
     "id": "pay_01gsz4vmqbjk3x4vvtafffd540",
     "status": "paid",
     "amount": "10000",
-    "currency_code": "USD"
-}
+    "currency_code": "USD",
+    "remittance_reference": "some-reference"
+}