Fix: Transaction Preview Price

CHANGELOG.md

@@ -18,6 +18,30 @@ Check our main [developer changelog](https://developer.paddle.com/?utm_source=dx
 ### Fixed
 
 - Dropped `receipt_data` on create and preview of a one-time charge for Subscriptions and Transactions
+- `TransactionsClient::preview()` `TransactionPreview` response now allows null price ID for non-catalog prices:
+  - `TransactionPreview` `items[]->price` can now return `Price` (with `id`) or `TransactionPreviewPrice` (with nullable `id`)
+  - `TransactionPreview` `details->lineItems[]->priceId` is now nullable
+
+### Added
+- `TransactionsClient::create()` now supports operation items with optional properties:
+  - `Resources\Transactions\Operations\Create\TransactionCreateItem`
+  - `Resources\Transactions\Operations\Create\TransactionCreateItemWithPrice`
+- `TransactionsClient::update()` now supports operation items with optional properties:
+  - `Resources\Transactions\Operations\Update\TransactionUpdateItem`
+  - `Resources\Transactions\Operations\Update\TransactionUpdateItemWithPrice`
+- `TransactionsClient::preview()` now supports operation items with optional properties:
+  - `Resources\Transactions\Operations\Preview\TransactionItemPreviewWithNonCatalogPrice`
+  - `Resources\Transactions\Operations\Preview\TransactionItemPreviewWithPriceId`
+
+### Deprecated
+- `TransactionsClient::create()` operation items have been deprecated:
+  - `Entities\Transaction\TransactionCreateItem`
+  - `Entities\Transaction\TransactionCreateItemWithPrice`
+- `TransactionsClient::update()` operation items have been deprecated:
+  - `Entities\Transaction\TransactionUpdateTransactionItem`
+- `TransactionsClient::preview()` operation items have been deprecated:
+  - `Entities\Transaction\TransactionItemPreviewWithNonCatalogPrice`
+  - `Entities\Transaction\TransactionItemPreviewWithPriceId`
 
 # [1.3.1] - 2024-09-30
 

src/Entities/Shared/TransactionLineItemPreview.php

@@ -16,7 +16,7 @@
 class TransactionLineItemPreview
 {
     private function __construct(
-        public string $priceId,
+        public string|null $priceId,
         public int $quantity,
         public string $taxRate,
         public UnitTotals $unitTotals,

src/Entities/Transaction/TransactionCreateItem.php

@@ -11,6 +11,9 @@
 
 namespace Paddle\SDK\Entities\Transaction;
 
+/**
+ * @deprecated Replaced by \Paddle\SDK\Resources\Transactions\Operations\Create\TransactionCreateItem
+ */
 class TransactionCreateItem
 {
     public function __construct(

src/Entities/Transaction/TransactionCreateItemWithPrice.php

@@ -11,6 +11,9 @@
 
 namespace Paddle\SDK\Entities\Transaction;
 
+/**
+ * @deprecated Replaced by \Paddle\SDK\Resources\Transactions\Operations\Create\TransactionCreateItemWithPrice
+ */
 class TransactionCreateItemWithPrice
 {
     public function __construct(

src/Entities/Transaction/TransactionItemPreviewWithNonCatalogPrice.php

@@ -11,6 +11,9 @@
 
 namespace Paddle\SDK\Entities\Transaction;
 
+/**
+ * @deprecated Replaced by \Paddle\SDK\Resources\Transactions\Operations\Preview\TransactionItemPreviewWithNonCatalogPrice
+ */
 class TransactionItemPreviewWithNonCatalogPrice
 {
     public function __construct(

src/Entities/Transaction/TransactionItemPreviewWithPrice.php

@@ -16,7 +16,7 @@
 class TransactionItemPreviewWithPrice
 {
     private function __construct(
-        public Price $price,
+        public Price|TransactionPreviewPrice $price,
         public int $quantity,
         public bool $includeInTotals,
         public TransactionProration|null $proration,
@@ -26,7 +26,7 @@ private function __construct(
     public static function from(array $data): self
     {
         return new self(
-            Price::from($data['price']),
+            isset($data['price']['id']) ? Price::from($data['price']) : TransactionPreviewPrice::from($data['price']),
             $data['quantity'],
             $data['include_in_totals'],
             isset($data['proration']) ? TransactionProration::from($data['proration']) : null,

src/Entities/Transaction/TransactionItemPreviewWithPriceId.php

@@ -11,6 +11,9 @@
 
 namespace Paddle\SDK\Entities\Transaction;
 
+/**
+ * @deprecated Replaced by \Paddle\SDK\Resources\Transactions\Operations\Preview\TransactionItemPreviewWithPriceId
+ */
 class TransactionItemPreviewWithPriceId
 {
     public function __construct(

src/Entities/Transaction/TransactionNonCatalogPrice.php

@@ -18,6 +18,9 @@
 use Paddle\SDK\Entities\Shared\TimePeriod;
 use Paddle\SDK\Entities\Shared\UnitPriceOverride;
 
+/**
+ * @deprecated Replaced by \Paddle\SDK\Resources\Transactions\Operations\Price\TransactionNonCatalogPrice
+ */
 class TransactionNonCatalogPrice
 {
     /**

src/Entities/Transaction/TransactionNonCatalogPriceWithProduct.php

@@ -18,6 +18,9 @@
 use Paddle\SDK\Entities\Shared\TimePeriod;
 use Paddle\SDK\Entities\Shared\UnitPriceOverride;
 
+/**
+ * @deprecated Replaced by \Paddle\SDK\Resources\Transactions\Operations\Price\TransactionNonCatalogPriceWithProduct
+ */
 class TransactionNonCatalogPriceWithProduct
 {
     /**

src/Entities/Transaction/TransactionNonCatalogProduct.php

@@ -14,6 +14,9 @@
 use Paddle\SDK\Entities\Shared\CustomData;
 use Paddle\SDK\Entities\Shared\TaxCategory;
 
+/**
+ * @deprecated Replaced by \Paddle\SDK\Resources\Transactions\Operations\Price\TransactionNonCatalogProduct
+ */
 class TransactionNonCatalogProduct
 {
     public function __construct(

src/Entities/Transaction/TransactionPreviewPrice.php

@@ -0,0 +1,78 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * |------
+ * | ! Generated code !
+ * | Altering this code will result in changes being overwritten |
+ * |-------------------------------------------------------------|.
+ */
+
+namespace Paddle\SDK\Entities\Transaction;
+
+use Paddle\SDK\Entities\DateTime;
+use Paddle\SDK\Entities\Entity;
+use Paddle\SDK\Entities\Product;
+use Paddle\SDK\Entities\Shared\CatalogType;
+use Paddle\SDK\Entities\Shared\CustomData;
+use Paddle\SDK\Entities\Shared\ImportMeta;
+use Paddle\SDK\Entities\Shared\Money;
+use Paddle\SDK\Entities\Shared\PriceQuantity;
+use Paddle\SDK\Entities\Shared\Status;
+use Paddle\SDK\Entities\Shared\TaxMode;
+use Paddle\SDK\Entities\Shared\TimePeriod;
+use Paddle\SDK\Entities\Shared\UnitPriceOverride;
+
+class TransactionPreviewPrice implements Entity
+{
+    /**
+     * @param array<UnitPriceOverride> $unitPriceOverrides
+     */
+    private function __construct(
+        public string|null $id,
+        public string $productId,
+        public string|null $name,
+        public string $description,
+        public CatalogType|null $type,
+        public TimePeriod|null $billingCycle,
+        public TimePeriod|null $trialPeriod,
+        public TaxMode $taxMode,
+        public Money $unitPrice,
+        public array $unitPriceOverrides,
+        public PriceQuantity $quantity,
+        public Status $status,
+        public CustomData|null $customData,
+        public ImportMeta|null $importMeta,
+        public Product|null $product,
+        public \DateTimeInterface $createdAt,
+        public \DateTimeInterface $updatedAt,
+    ) {
+    }
+
+    public static function from(array $data): self
+    {
+        return new self(
+            id: $data['id'],
+            productId: $data['product_id'],
+            name: $data['name'] ?? null,
+            description: $data['description'],
+            type: CatalogType::from($data['type'] ?? ''),
+            billingCycle: isset($data['billing_cycle']) ? TimePeriod::from($data['billing_cycle']) : null,
+            trialPeriod: isset($data['trial_period']) ? TimePeriod::from($data['trial_period']) : null,
+            taxMode: TaxMode::from($data['tax_mode']),
+            unitPrice: Money::from($data['unit_price']),
+            unitPriceOverrides: array_map(
+                fn (array $override): UnitPriceOverride => UnitPriceOverride::from($override),
+                $data['unit_price_overrides'] ?? [],
+            ),
+            quantity: PriceQuantity::from($data['quantity']),
+            status: Status::from($data['status']),
+            customData: isset($data['custom_data']) ? new CustomData($data['custom_data']) : null,
+            importMeta: isset($data['import_meta']) ? ImportMeta::from($data['import_meta']) : null,
+            product: isset($data['product']) ? Product::from($data['product']) : null,
+            createdAt: DateTime::from($data['created_at']),
+            updatedAt: DateTime::from($data['updated_at']),
+        );
+    }
+}

src/Entities/Transaction/TransactionUpdateTransactionItem.php

@@ -11,6 +11,9 @@
 
 namespace Paddle\SDK\Entities\Transaction;
 
+/**
+ * @deprecated Replaced by \Paddle\SDK\Resources\Transactions\Operations\Update\TransactionUpdateItem
+ */
 class TransactionUpdateTransactionItem
 {
     public function __construct(

src/Resources/Transactions/Operations/Create/TransactionCreateItem.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Paddle\SDK\Resources\Transactions\Operations\Create;
+
+class TransactionCreateItem
+{
+    public function __construct(
+        public string $priceId,
+        public int $quantity,
+    ) {
+    }
+}

src/Resources/Transactions/Operations/Create/TransactionCreateItemWithPrice.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Paddle\SDK\Resources\Transactions\Operations\Create;
+
+use Paddle\SDK\Resources\Transactions\Operations\Price\TransactionNonCatalogPrice;
+use Paddle\SDK\Resources\Transactions\Operations\Price\TransactionNonCatalogPriceWithProduct;
+
+class TransactionCreateItemWithPrice
+{
+    public function __construct(
+        public TransactionNonCatalogPrice|TransactionNonCatalogPriceWithProduct $price,
+        public int $quantity,
+    ) {
+    }
+}

src/Resources/Transactions/Operations/CreateTransaction.php

@@ -10,18 +10,20 @@
 use Paddle\SDK\Entities\Shared\CurrencyCode;
 use Paddle\SDK\Entities\Shared\CustomData;
 use Paddle\SDK\Entities\Shared\TransactionStatus;
-use Paddle\SDK\Entities\Transaction\TransactionCreateItem;
-use Paddle\SDK\Entities\Transaction\TransactionCreateItemWithPrice;
+use Paddle\SDK\Entities\Transaction\TransactionCreateItem as EntityTransactionCreateItem;
+use Paddle\SDK\Entities\Transaction\TransactionCreateItemWithPrice as EntityTransactionCreateItemWithPrice;
 use Paddle\SDK\Entities\Transaction\TransactionTimePeriod;
 use Paddle\SDK\FiltersUndefined;
+use Paddle\SDK\Resources\Transactions\Operations\Create\TransactionCreateItem;
+use Paddle\SDK\Resources\Transactions\Operations\Create\TransactionCreateItemWithPrice;
 use Paddle\SDK\Undefined;
 
 class CreateTransaction implements \JsonSerializable
 {
     use FiltersUndefined;
 
     /**
-     * @param array<TransactionCreateItem|TransactionCreateItemWithPrice> $items
+     * @param array<TransactionCreateItem|TransactionCreateItemWithPrice|EntityTransactionCreateItem|EntityTransactionCreateItemWithPrice> $items
      */
     public function __construct(
         public readonly array $items,

src/Resources/Transactions/Operations/Preview/TransactionItemPreviewWithNonCatalogPrice.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Paddle\SDK\Resources\Transactions\Operations\Preview;
+
+use Paddle\SDK\FiltersUndefined;
+use Paddle\SDK\Resources\Transactions\Operations\Price\TransactionNonCatalogPrice;
+use Paddle\SDK\Resources\Transactions\Operations\Price\TransactionNonCatalogPriceWithProduct;
+use Paddle\SDK\Undefined;
+
+class TransactionItemPreviewWithNonCatalogPrice implements \JsonSerializable
+{
+    use FiltersUndefined;
+
+    public function __construct(
+        public TransactionNonCatalogPrice|TransactionNonCatalogPriceWithProduct $price,
+        public int $quantity,
+        public bool|Undefined $includeInTotals = new Undefined(),
+    ) {
+    }
+
+    public function jsonSerialize(): array
+    {
+        return $this->filterUndefined([
+            'price' => $this->price,
+            'quantity' => $this->quantity,
+            'include_in_totals' => $this->includeInTotals,
+        ]);
+    }
+}

src/Resources/Transactions/Operations/Preview/TransactionItemPreviewWithPriceId.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Paddle\SDK\Resources\Transactions\Operations\Preview;
+
+use Paddle\SDK\FiltersUndefined;
+use Paddle\SDK\Undefined;
+
+class TransactionItemPreviewWithPriceId implements \JsonSerializable
+{
+    use FiltersUndefined;
+
+    public function __construct(
+        public string $priceId,
+        public int $quantity,
+        public bool|Undefined $includeInTotals = new Undefined(),
+    ) {
+    }
+
+    public function jsonSerialize(): array
+    {
+        return $this->filterUndefined([
+            'price_id' => $this->priceId,
+            'quantity' => $this->quantity,
+            'include_in_totals' => $this->includeInTotals,
+        ]);
+    }
+}

src/Resources/Transactions/Operations/PreviewTransaction.php

@@ -7,17 +7,19 @@
 use Paddle\SDK\Entities\Shared\AddressPreview;
 use Paddle\SDK\Entities\Shared\CollectionMode;
 use Paddle\SDK\Entities\Shared\CurrencyCode;
-use Paddle\SDK\Entities\Transaction\TransactionItemPreviewWithNonCatalogPrice;
-use Paddle\SDK\Entities\Transaction\TransactionItemPreviewWithPriceId;
+use Paddle\SDK\Entities\Transaction\TransactionItemPreviewWithNonCatalogPrice as EntityItemPreviewWithNonCatalogPrice;
+use Paddle\SDK\Entities\Transaction\TransactionItemPreviewWithPriceId as EntityItemPreviewWithPriceId;
 use Paddle\SDK\FiltersUndefined;
+use Paddle\SDK\Resources\Transactions\Operations\Preview\TransactionItemPreviewWithNonCatalogPrice;
+use Paddle\SDK\Resources\Transactions\Operations\Preview\TransactionItemPreviewWithPriceId;
 use Paddle\SDK\Undefined;
 
 class PreviewTransaction implements \JsonSerializable
 {
     use FiltersUndefined;
 
     /**
-     * @param array<TransactionItemPreviewWithPriceId|TransactionItemPreviewWithNonCatalogPrice> $items
+     * @param array<TransactionItemPreviewWithPriceId|TransactionItemPreviewWithNonCatalogPrice|EntityItemPreviewWithPriceId|EntityItemPreviewWithNonCatalogPrice> $items
      */
     public function __construct(
         public readonly array $items,