diff --git a/.fern/metadata.json b/.fern/metadata.json index e7deddec..2e04b593 100644 --- a/.fern/metadata.json +++ b/.fern/metadata.json @@ -1,5 +1,5 @@ { - "cliVersion": "3.98.5", + "cliVersion": "5.56.0", "generatorName": "fernapi/fern-php-sdk", "generatorVersion": "2.1.5", "generatorConfig": { @@ -23,5 +23,6 @@ } } }, - "sdkVersion": "45.2.0-rc.0" + "originGitCommit": "b2dac8b2c1b9fe87c0e1fe3eb6257b259caa0715", + "sdkVersion": "46.0.1.20260715" } \ No newline at end of file diff --git a/.fern/replay.lock b/.fern/replay.lock index 5cb1aff4..1dcaec16 100644 --- a/.fern/replay.lock +++ b/.fern/replay.lock @@ -6,5 +6,11 @@ generations: timestamp: 2026-05-19T21:15:19.797Z cli_version: unknown generator_versions: {} -current_generation: d62b84d994b80d7a4e31128be4970c153b102e7c + - commit_sha: 5f33bef37d47ae514ce417bb27e1aad232f269c2 + tree_hash: 8199b765565a95cd970ea13691e2f82c392041b0 + timestamp: 2026-07-14T16:57:30.288Z + cli_version: unknown + generator_versions: + fernapi/fern-php-sdk: 2.1.5 +current_generation: 5f33bef37d47ae514ce417bb27e1aad232f269c2 patches: [] diff --git a/composer.json b/composer.json index 082f2073..a19de6a2 100644 --- a/composer.json +++ b/composer.json @@ -1,6 +1,6 @@ { "name": "square/square", - "version": "45.2.0-rc.0", + "version": "46.0.1.20260715", "description": "Use Square APIs to manage and run business including payment, customer, product, inventory, and employee management.", "keywords": [ "square", diff --git a/reference.md b/reference.md index 35f1d2b1..2924e291 100644 --- a/reference.md +++ b/reference.md @@ -2372,9 +2372,15 @@ batches will be processed in order as long as the total object count for the request (items, variations, modifier lists, discounts, and taxes) is no more than 10,000. +This endpoint uses full-replacement semantics. The client must send the complete object, and any +field absent from the request is interpreted as an intentional clear. This logic applies to +nested objects as well. For example, omitting inlined children like variations will delete them. + To ensure consistency, only one update request is processed at a time per seller account. While one (batch or non-batch) update request is being processed, other (batched and non-batched) -update requests are rejected with the `429` error code. +update requests are rejected with the `429` error code. Prefer batching related changes into a +single call rather than issuing many small writes, since each write acquires the lock separately +and parallel writes to the same seller will contend with each other, producing `429` errors. @@ -2534,6 +2540,8 @@ Returns a list of all [CatalogObject](entity:CatalogObject)s of the specified ty The `types` parameter is specified as a comma-separated list of the [CatalogObjectType](entity:CatalogObjectType) values, for example, "`ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, `CATEGORY`, `DISCOUNT`, `TAX`, `IMAGE`". +Always specify `types` explicitly. When upgrading to a newer API version, omitting `types` may +cause new object types to appear in results that were not returned under the previous version. __Important:__ ListCatalog does not return deleted catalog items. To retrieve deleted catalog items, use [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects) @@ -2647,6 +2655,11 @@ endpoint in the following aspects: - `SearchCatalogItems` supports the custom attribute query filters to return items or item variations that contain custom attribute values, where `SearchCatalogObjects` does not. - `SearchCatalogItems` does not support the `include_deleted_objects` filter to search for deleted items or item variations, whereas `SearchCatalogObjects` does. - The both endpoints have different call conventions, including the query filter formats. + +The `object_types` parameter is specified as a list of [CatalogObjectType](entity:CatalogObjectType) values. +Always specify `object_types` explicitly. When upgrading to a newer API version, omitting +`object_types` may cause new object types to appear in results that were not returned under +the previous version. @@ -5518,24 +5531,516 @@ Otherwise, the endpoint returns the gift cards of all states.
-**$limit:** `?int` +**$limit:** `?int` + +If a limit is provided, the endpoint returns only the specified number of results per page. +The maximum value is 200. The default value is 30. +For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). + +
+
+ +
+
+ +**$cursor:** `?string` + +A pagination cursor returned by a previous call to this endpoint. +Provide this cursor to retrieve the next set of results for the original query. +If a cursor is not provided, the endpoint returns the first page of the results. +For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). + +
+
+ +
+
+ +**$customerId:** `?string` — If a customer ID is provided, the endpoint returns only the gift cards linked to the specified customer. + +
+
+ + + + + + + + +
$client->giftCards->create($request) -> CreateGiftCardResponse +
+
+ +#### 📝 Description + +
+
+ +
+
+ +Creates a digital gift card or registers a physical (plastic) gift card. The resulting gift card +has a `PENDING` state. To activate a gift card so that it can be redeemed for purchases, call +[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) and create an `ACTIVATE` +activity with the initial balance. Alternatively, you can use [RefundPayment](api-endpoint:Refunds-RefundPayment) +to refund a payment to the new gift card. +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```php +$client->giftCards->create( + new CreateGiftCardRequest([ + 'idempotencyKey' => 'NC9Tm69EjbjtConu', + 'locationId' => '81FN9BNFZTKS4', + 'giftCard' => new GiftCard([ + 'type' => GiftCardType::Digital->value, + ]), + ]), +); +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**$idempotencyKey:** `string` + +A unique identifier for this request, used to ensure idempotency. For more information, +see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency). + +
+
+ +
+
+ +**$locationId:** `string` + +The ID of the [location](entity:Location) where the gift card should be registered for +reporting purposes. Gift cards can be redeemed at any of the seller's locations. + +
+
+ +
+
+ +**$giftCard:** `GiftCard` + +The gift card to create. The `type` field is required for this request. The `gan_source` +and `gan` fields are included as follows: + +To direct Square to generate a 16-digit GAN, omit `gan_source` and `gan`. + +To provide a custom GAN, include `gan_source` and `gan`. +- For `gan_source`, specify `OTHER`. +- For `gan`, provide a custom GAN containing 8 to 20 alphanumeric characters. The GAN must be +unique for the seller and cannot start with the same bank identification number (BIN) as major +credit cards. Do not use GANs that are easy to guess (such as 12345678) because they greatly +increase the risk of fraud. It is the responsibility of the developer to ensure the security +of their custom GANs. For more information, see +[Custom GANs](https://developer.squareup.com/docs/gift-cards/using-gift-cards-api#custom-gans). + +To register an unused, physical gift card that the seller previously ordered from Square, +include `gan` and provide the GAN that is printed on the gift card. + +
+
+
+
+ + +
+
+
+ +
$client->giftCards->getFromGan($request) -> GetGiftCardFromGanResponse +
+
+ +#### 📝 Description + +
+
+ +
+
+ +Retrieves a gift card using the gift card account number (GAN). +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```php +$client->giftCards->getFromGan( + new GetGiftCardFromGanRequest([ + 'gan' => '7783320001001635', + ]), +); +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**$gan:** `string` + +The gift card account number (GAN) of the gift card to retrieve. +The maximum length of a GAN is 255 digits to account for third-party GANs that have been imported. +Square-issued gift cards have 16-digit GANs. + +
+
+
+
+ + +
+
+
+ +
$client->giftCards->getFromNonce($request) -> GetGiftCardFromNonceResponse +
+
+ +#### 📝 Description + +
+
+ +
+
+ +Retrieves a gift card using a secure payment token that represents the gift card. +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```php +$client->giftCards->getFromNonce( + new GetGiftCardFromNonceRequest([ + 'nonce' => 'cnon:7783322135245171', + ]), +); +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**$nonce:** `string` + +The payment token of the gift card to retrieve. Payment tokens are generated by the +Web Payments SDK or In-App Payments SDK. + +
+
+
+
+ + +
+
+
+ +
$client->giftCards->linkCustomer($request) -> LinkCustomerToGiftCardResponse +
+
+ +#### 📝 Description + +
+
+ +
+
+ +Links a customer to a gift card, which is also referred to as adding a card on file. +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```php +$client->giftCards->linkCustomer( + new LinkCustomerToGiftCardRequest([ + 'giftCardId' => 'gift_card_id', + 'customerId' => 'GKY0FZ3V717AH8Q2D821PNT2ZW', + ]), +); +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**$giftCardId:** `string` — The ID of the gift card to be linked. + +
+
+ +
+
+ +**$customerId:** `string` — The ID of the customer to link to the gift card. + +
+
+
+
+ + +
+
+
+ +
$client->giftCards->unlinkCustomer($request) -> UnlinkCustomerFromGiftCardResponse +
+
+ +#### 📝 Description + +
+
+ +
+
+ +Unlinks a customer from a gift card, which is also referred to as removing a card on file. +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```php +$client->giftCards->unlinkCustomer( + new UnlinkCustomerFromGiftCardRequest([ + 'giftCardId' => 'gift_card_id', + 'customerId' => 'GKY0FZ3V717AH8Q2D821PNT2ZW', + ]), +); +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**$giftCardId:** `string` — The ID of the gift card to be unlinked. + +
+
+ +
+
+ +**$customerId:** `string` — The ID of the customer to unlink from the gift card. + +
+
+
+
+ + +
+
+
+ +
$client->giftCards->get($request) -> GetGiftCardResponse +
+
+ +#### 📝 Description + +
+
+ +
+
+ +Retrieves a gift card using the gift card ID. +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```php +$client->giftCards->get( + new GetGiftCardsRequest([ + 'id' => 'id', + ]), +); +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**$id:** `string` — The ID of the gift card to retrieve. + +
+
+
+
+ + +
+
+
+ +## Inventory +
$client->inventory->listInventoryAdjustmentReasons($request) -> ListInventoryAdjustmentReasonsResponse +
+
+ +#### 📝 Description + +
+
+ +
+
+ +Returns the standard and custom inventory adjustment reasons available +to the seller. +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
-If a limit is provided, the endpoint returns only the specified number of results per page. -The maximum value is 200. The default value is 30. -For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). - +```php +$client->inventory->listInventoryAdjustmentReasons( + new ListInventoryAdjustmentReasonsRequest([ + 'includeDeleted' => true, + 'includeSystemCodes' => true, + ]), +); +``` +
+
+#### ⚙️ Parameters +
-**$cursor:** `?string` +
+
-A pagination cursor returned by a previous call to this endpoint. -Provide this cursor to retrieve the next set of results for the original query. -If a cursor is not provided, the endpoint returns the first page of the results. -For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). +**$includeDeleted:** `?bool` + +Indicates whether the response should include deleted custom inventory +adjustment reasons. The default value is `false`.
@@ -5543,7 +6048,12 @@ For more information, see [Pagination](https://developer.squareup.com/docs/worki
-**$customerId:** `?string` — If a customer ID is provided, the endpoint returns only the gift cards linked to the specified customer. +**$includeSystemCodes:** `?bool` + +Indicates whether the response should include Square-generated system +inventory adjustment reason codes that cannot be used to write adjustments +from the Connect API, such as `SALE`, `RECOUNT`, `TRANSFER`, `IN_TRANSIT`, +and `CANCELED_SALE`. The default value is `false`.
@@ -5555,7 +6065,7 @@ For more information, see [Pagination](https://developer.squareup.com/docs/worki
-
$client->giftCards->create($request) -> CreateGiftCardResponse +
$client->inventory->createInventoryAdjustmentReason($request) -> CreateInventoryAdjustmentReasonResponse
@@ -5567,11 +6077,7 @@ For more information, see [Pagination](https://developer.squareup.com/docs/worki
-Creates a digital gift card or registers a physical (plastic) gift card. The resulting gift card -has a `PENDING` state. To activate a gift card so that it can be redeemed for purchases, call -[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) and create an `ACTIVATE` -activity with the initial balance. Alternatively, you can use [RefundPayment](api-endpoint:Refunds-RefundPayment) -to refund a payment to the new gift card. +Creates a custom inventory adjustment reason.
@@ -5586,12 +6092,15 @@ to refund a payment to the new gift card.
```php -$client->giftCards->create( - new CreateGiftCardRequest([ - 'idempotencyKey' => 'NC9Tm69EjbjtConu', - 'locationId' => '81FN9BNFZTKS4', - 'giftCard' => new GiftCard([ - 'type' => GiftCardType::Digital->value, +$client->inventory->createInventoryAdjustmentReason( + new CreateInventoryAdjustmentReasonRequest([ + 'idempotencyKey' => '27b2f2b1-1c2a-4b9e-8f3a-0d9c3a1e5b47', + 'adjustmentReason' => new InventoryAdjustmentReason([ + 'id' => new InventoryAdjustmentReasonId([ + 'type' => InventoryAdjustmentReasonIdType::Custom->value, + ]), + 'name' => 'Donated to charity', + 'direction' => InventoryAdjustmentReasonDirection::Decrease->value, ]), ]), ); @@ -5611,19 +6120,9 @@ $client->giftCards->create( **$idempotencyKey:** `string` -A unique identifier for this request, used to ensure idempotency. For more information, -see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency). - -
-
- -
-
- -**$locationId:** `string` - -The ID of the [location](entity:Location) where the gift card should be registered for -reporting purposes. Gift cards can be redeemed at any of the seller's locations. +A client-supplied, universally unique identifier to make this +[CreateInventoryAdjustmentReason](api-endpoint:Inventory-CreateInventoryAdjustmentReason) +request idempotent.
@@ -5631,24 +6130,10 @@ reporting purposes. Gift cards can be redeemed at any of the seller's locations.
-**$giftCard:** `GiftCard` - -The gift card to create. The `type` field is required for this request. The `gan_source` -and `gan` fields are included as follows: - -To direct Square to generate a 16-digit GAN, omit `gan_source` and `gan`. - -To provide a custom GAN, include `gan_source` and `gan`. -- For `gan_source`, specify `OTHER`. -- For `gan`, provide a custom GAN containing 8 to 20 alphanumeric characters. The GAN must be -unique for the seller and cannot start with the same bank identification number (BIN) as major -credit cards. Do not use GANs that are easy to guess (such as 12345678) because they greatly -increase the risk of fraud. It is the responsibility of the developer to ensure the security -of their custom GANs. For more information, see -[Custom GANs](https://developer.squareup.com/docs/gift-cards/using-gift-cards-api#custom-gans). +**$adjustmentReason:** `InventoryAdjustmentReason` -To register an unused, physical gift card that the seller previously ordered from Square, -include `gan` and provide the GAN that is printed on the gift card. +The custom inventory adjustment reason to create. Only custom +adjustment reasons can be created.
@@ -5660,7 +6145,7 @@ include `gan` and provide the GAN that is printed on the gift card.
-
$client->giftCards->getFromGan($request) -> GetGiftCardFromGanResponse +
$client->inventory->deleteInventoryAdjustmentReason($request) -> DeleteInventoryAdjustmentReasonResponse
@@ -5672,7 +6157,7 @@ include `gan` and provide the GAN that is printed on the gift card.
-Retrieves a gift card using the gift card account number (GAN). +Soft deletes a custom inventory adjustment reason.
@@ -5687,9 +6172,12 @@ Retrieves a gift card using the gift card account number (GAN).
```php -$client->giftCards->getFromGan( - new GetGiftCardFromGanRequest([ - 'gan' => '7783320001001635', +$client->inventory->deleteInventoryAdjustmentReason( + new DeleteInventoryAdjustmentReasonRequest([ + 'reasonId' => new InventoryAdjustmentReasonId([ + 'type' => InventoryAdjustmentReasonIdType::Custom->value, + 'customReasonId' => 'R5BX3PDCZ6EXAMPLE', + ]), ]), ); ``` @@ -5706,11 +6194,7 @@ $client->giftCards->getFromGan(
-**$gan:** `string` - -The gift card account number (GAN) of the gift card to retrieve. -The maximum length of a GAN is 255 digits to account for third-party GANs that have been imported. -Square-issued gift cards have 16-digit GANs. +**$reasonId:** `InventoryAdjustmentReasonId` — The identifier of the custom inventory adjustment reason to soft delete.
@@ -5722,7 +6206,7 @@ Square-issued gift cards have 16-digit GANs.
-
$client->giftCards->getFromNonce($request) -> GetGiftCardFromNonceResponse +
$client->inventory->restoreInventoryAdjustmentReason($request) -> RestoreInventoryAdjustmentReasonResponse
@@ -5734,7 +6218,7 @@ Square-issued gift cards have 16-digit GANs.
-Retrieves a gift card using a secure payment token that represents the gift card. +Restores a soft-deleted custom inventory adjustment reason.
@@ -5749,9 +6233,12 @@ Retrieves a gift card using a secure payment token that represents the gift card
```php -$client->giftCards->getFromNonce( - new GetGiftCardFromNonceRequest([ - 'nonce' => 'cnon:7783322135245171', +$client->inventory->restoreInventoryAdjustmentReason( + new RestoreInventoryAdjustmentReasonRequest([ + 'reasonId' => new InventoryAdjustmentReasonId([ + 'type' => InventoryAdjustmentReasonIdType::Custom->value, + 'customReasonId' => 'R5BX3PDCZ6EXAMPLE', + ]), ]), ); ``` @@ -5768,10 +6255,10 @@ $client->giftCards->getFromNonce(
-**$nonce:** `string` +**$reasonId:** `InventoryAdjustmentReasonId` -The payment token of the gift card to retrieve. Payment tokens are generated by the -Web Payments SDK or In-App Payments SDK. +The identifier of the soft-deleted custom inventory adjustment reason +to restore.
@@ -5783,7 +6270,7 @@ Web Payments SDK or In-App Payments SDK.
-
$client->giftCards->linkCustomer($request) -> LinkCustomerToGiftCardResponse +
$client->inventory->retrieveInventoryAdjustmentReason($request) -> RetrieveInventoryAdjustmentReasonResponse
@@ -5795,7 +6282,8 @@ Web Payments SDK or In-App Payments SDK.
-Links a customer to a gift card, which is also referred to as adding a card on file. +Returns the inventory adjustment reason identified by the provided +`reason_id`. Deleted custom reasons can be retrieved by ID.
@@ -5810,10 +6298,12 @@ Links a customer to a gift card, which is also referred to as adding a card on f
```php -$client->giftCards->linkCustomer( - new LinkCustomerToGiftCardRequest([ - 'giftCardId' => 'gift_card_id', - 'customerId' => 'GKY0FZ3V717AH8Q2D821PNT2ZW', +$client->inventory->retrieveInventoryAdjustmentReason( + new RetrieveInventoryAdjustmentReasonRequest([ + 'reasonId' => new InventoryAdjustmentReasonId([ + 'type' => InventoryAdjustmentReasonIdType::Custom->value, + 'customReasonId' => 'R5BX3PDCZ6EXAMPLE', + ]), ]), ); ``` @@ -5830,15 +6320,7 @@ $client->giftCards->linkCustomer(
-**$giftCardId:** `string` — The ID of the gift card to be linked. - -
-
- -
-
- -**$customerId:** `string` — The ID of the customer to link to the gift card. +**$reasonId:** `InventoryAdjustmentReasonId` — The identifier of the inventory adjustment reason to retrieve.
@@ -5850,7 +6332,7 @@ $client->giftCards->linkCustomer(
-
$client->giftCards->unlinkCustomer($request) -> UnlinkCustomerFromGiftCardResponse +
$client->inventory->updateInventoryAdjustmentReason($request) -> UpdateInventoryAdjustmentReasonResponse
@@ -5862,7 +6344,7 @@ $client->giftCards->linkCustomer(
-Unlinks a customer from a gift card, which is also referred to as removing a card on file. +Updates a custom inventory adjustment reason.
@@ -5877,10 +6359,19 @@ Unlinks a customer from a gift card, which is also referred to as removing a car
```php -$client->giftCards->unlinkCustomer( - new UnlinkCustomerFromGiftCardRequest([ - 'giftCardId' => 'gift_card_id', - 'customerId' => 'GKY0FZ3V717AH8Q2D821PNT2ZW', +$client->inventory->updateInventoryAdjustmentReason( + new UpdateInventoryAdjustmentReasonRequest([ + 'reasonId' => new InventoryAdjustmentReasonId([ + 'type' => InventoryAdjustmentReasonIdType::Custom->value, + 'customReasonId' => 'R5BX3PDCZ6EXAMPLE', + ]), + 'adjustmentReason' => new InventoryAdjustmentReason([ + 'id' => new InventoryAdjustmentReasonId([ + 'type' => InventoryAdjustmentReasonIdType::Custom->value, + 'customReasonId' => 'R5BX3PDCZ6EXAMPLE', + ]), + 'name' => 'Charitable donation', + ]), ]), ); ``` @@ -5897,7 +6388,7 @@ $client->giftCards->unlinkCustomer(
-**$giftCardId:** `string` — The ID of the gift card to be unlinked. +**$reasonId:** `InventoryAdjustmentReasonId` — The identifier of the custom inventory adjustment reason to update.
@@ -5905,7 +6396,12 @@ $client->giftCards->unlinkCustomer(
-**$customerId:** `string` — The ID of the customer to unlink from the gift card. +**$adjustmentReason:** `InventoryAdjustmentReason` + +The requested custom inventory adjustment reason update. Only the +`name` field can be updated. Deleted custom reasons cannot be updated. To +restore a deleted custom reason, call +[RestoreInventoryAdjustmentReason](api-endpoint:Inventory-RestoreInventoryAdjustmentReason).
@@ -5917,7 +6413,7 @@ $client->giftCards->unlinkCustomer(
-
$client->giftCards->get($request) -> GetGiftCardResponse +
$client->inventory->deprecatedGetAdjustment($request) -> GetInventoryAdjustmentResponse
@@ -5929,7 +6425,8 @@ $client->giftCards->unlinkCustomer(
-Retrieves a gift card using the gift card ID. +Deprecated version of [RetrieveInventoryAdjustment](api-endpoint:Inventory-RetrieveInventoryAdjustment) after the endpoint URL +is updated to conform to the standard convention.
@@ -5944,9 +6441,9 @@ Retrieves a gift card using the gift card ID.
```php -$client->giftCards->get( - new GetGiftCardsRequest([ - 'id' => 'id', +$client->inventory->deprecatedGetAdjustment( + new DeprecatedGetAdjustmentInventoryRequest([ + 'adjustmentId' => 'adjustment_id', ]), ); ``` @@ -5963,7 +6460,7 @@ $client->giftCards->get(
-**$id:** `string` — The ID of the gift card to retrieve. +**$adjustmentId:** `string` — ID of the [InventoryAdjustment](entity:InventoryAdjustment) to retrieve.
@@ -5975,8 +6472,7 @@ $client->giftCards->get(
-## Inventory -
$client->inventory->deprecatedGetAdjustment($request) -> GetInventoryAdjustmentResponse +
$client->inventory->updateInventoryAdjustment($request) -> UpdateInventoryAdjustmentResponse
@@ -5988,8 +6484,10 @@ $client->giftCards->get(
-Deprecated version of [RetrieveInventoryAdjustment](api-endpoint:Inventory-RetrieveInventoryAdjustment) after the endpoint URL -is updated to conform to the standard convention. +Applies an update to the provided adjustment. + +On success: returns the newly updated adjustment. +On failure: returns a list of related errors.
@@ -6004,9 +6502,10 @@ is updated to conform to the standard convention.
```php -$client->inventory->deprecatedGetAdjustment( - new DeprecatedGetAdjustmentInventoryRequest([ - 'adjustmentId' => 'adjustment_id', +$client->inventory->updateInventoryAdjustment( + new UpdateInventoryAdjustmentRequest([ + 'idempotencyKey' => '8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe', + 'adjustment' => new InventoryAdjustment([]), ]), ); ``` @@ -6023,7 +6522,35 @@ $client->inventory->deprecatedGetAdjustment(
-**$adjustmentId:** `string` — ID of the [InventoryAdjustment](entity:InventoryAdjustment) to retrieve. +**$idempotencyKey:** `string` + +A client-supplied, universally unique identifier (UUID) for the +request. + +See [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) in the +[Build Basics](https://developer.squareup.com/docs/buildbasics) section for more +information. + +
+
+ +
+
+ +**$adjustment:** `InventoryAdjustment` + +Represents the updates being written to a past/existing inventory adjustment. +This works using sparse updates, meaning that any fields omitted from the inputted InventoryAdjustment +will retain their values. + +Only updates to the quantity, cost_money, vendor_id, and reason_id fields of an InventoryAdjustment can be made here. +Note that the quantity field must be provided, but it can be identical to the current quantity if there are no desired quantity changes. +cost_money and vendor_id can only be written to adjustments that add stock to the system (from_state of NONE or UNLINKED_RETURN) and to untracked sale adjustments. +reason_id can be changed to any reason that is valid for the adjustment's state transition. The reason of a system-generated adjustment (for example, SALE or RECOUNT) cannot be changed. +Adjustments generated by Square from other records cannot be updated. This includes inferred adjustments created by physical counts, transfer-like cross-location adjustments, and component adjustments. +Adjustments linked to purchase orders cannot be updated. Adjustments linked to sales can only have cost_money and vendor_id updated, and only for untracked sales. +Restock adjustments linked to an itemized return can have their quantity updated, up to the quantity remaining on the return. +Adjustments older than one year cannot be updated.
@@ -6654,65 +7181,6 @@ ID of the
- - -
- -
$client->inventory->getTransfer($request) -> GetInventoryTransferResponse -
-
- -#### 📝 Description - -
-
- -
-
- -Returns the [InventoryTransfer](entity:InventoryTransfer) object -with the provided `transfer_id`. -
-
-
-
- -#### 🔌 Usage - -
-
- -
-
- -```php -$client->inventory->getTransfer( - new GetTransferInventoryRequest([ - 'transferId' => 'transfer_id', - ]), -); -``` -
-
-
-
- -#### ⚙️ Parameters - -
-
- -
-
- -**$transferId:** `string` — ID of the [InventoryTransfer](entity:InventoryTransfer) to retrieve. - -
-
-
-
- -
@@ -6896,6 +7364,50 @@ See the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagin + + +
+ +
$client->inventory->getTransfer($request) +
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```php +$client->inventory->getTransfer( + new GetTransferInventoryRequest([ + 'transferId' => 'transfer_id', + ]), +); +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**$transferId:** `string` + +
+
+
+
+ +
@@ -17668,6 +18180,10 @@ $client->catalog->images->update( Creates a new or updates the specified [CatalogObject](entity:CatalogObject). +This endpoint uses full-replacement semantics. The client must send the complete object, and any +field absent from the request is interpreted as an intentional clear. This logic applies to +nested objects as well. For example, omitting inlined children like variations will delete them. + To ensure consistency, only one update request is processed at a time per seller account. While one (batch or non-batch) update request is being processed, other (batched and non-batched) update requests are rejected with the `429` error code. diff --git a/src/Catalog/CatalogClient.php b/src/Catalog/CatalogClient.php index 647ce4c0..4947a26d 100644 --- a/src/Catalog/CatalogClient.php +++ b/src/Catalog/CatalogClient.php @@ -203,9 +203,15 @@ public function batchGet(BatchGetCatalogObjectsRequest $request, ?array $options * request (items, variations, modifier lists, discounts, and taxes) is no more * than 10,000. * + * This endpoint uses full-replacement semantics. The client must send the complete object, and any + * field absent from the request is interpreted as an intentional clear. This logic applies to + * nested objects as well. For example, omitting inlined children like variations will delete them. + * * To ensure consistency, only one update request is processed at a time per seller account. * While one (batch or non-batch) update request is being processed, other (batched and non-batched) - * update requests are rejected with the `429` error code. + * update requests are rejected with the `429` error code. Prefer batching related changes into a + * single call rather than issuing many small writes, since each write acquires the lock separately + * and parallel writes to the same seller will contend with each other, producing `429` errors. * * @param BatchUpsertCatalogObjectsRequest $request * @param ?array{ @@ -300,6 +306,8 @@ public function info(?array $options = null): CatalogInfoResponse * * The `types` parameter is specified as a comma-separated list of the [CatalogObjectType](entity:CatalogObjectType) values, * for example, "`ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, `CATEGORY`, `DISCOUNT`, `TAX`, `IMAGE`". + * Always specify `types` explicitly. When upgrading to a newer API version, omitting `types` may + * cause new object types to appear in results that were not returned under the previous version. * * __Important:__ ListCatalog does not return deleted catalog items. To retrieve * deleted catalog items, use [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects) @@ -343,6 +351,11 @@ public function list(ListCatalogRequest $request = new ListCatalogRequest(), ?ar * - `SearchCatalogItems` does not support the `include_deleted_objects` filter to search for deleted items or item variations, whereas `SearchCatalogObjects` does. * - The both endpoints have different call conventions, including the query filter formats. * + * The `object_types` parameter is specified as a list of [CatalogObjectType](entity:CatalogObjectType) values. + * Always specify `object_types` explicitly. When upgrading to a newer API version, omitting + * `object_types` may cause new object types to appear in results that were not returned under + * the previous version. + * * @param SearchCatalogObjectsRequest $request * @param ?array{ * baseUrl?: string, @@ -542,6 +555,8 @@ public function updateItemTaxes(UpdateItemTaxesRequest $request, ?array $options * * The `types` parameter is specified as a comma-separated list of the [CatalogObjectType](entity:CatalogObjectType) values, * for example, "`ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, `CATEGORY`, `DISCOUNT`, `TAX`, `IMAGE`". + * Always specify `types` explicitly. When upgrading to a newer API version, omitting `types` may + * cause new object types to appear in results that were not returned under the previous version. * * __Important:__ ListCatalog does not return deleted catalog items. To retrieve * deleted catalog items, use [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects) diff --git a/src/Catalog/Object/ObjectClient.php b/src/Catalog/Object/ObjectClient.php index 44669f5b..d3476a32 100644 --- a/src/Catalog/Object/ObjectClient.php +++ b/src/Catalog/Object/ObjectClient.php @@ -57,6 +57,10 @@ public function __construct( /** * Creates a new or updates the specified [CatalogObject](entity:CatalogObject). * + * This endpoint uses full-replacement semantics. The client must send the complete object, and any + * field absent from the request is interpreted as an intentional clear. This logic applies to + * nested objects as well. For example, omitting inlined children like variations will delete them. + * * To ensure consistency, only one update request is processed at a time per seller account. * While one (batch or non-batch) update request is being processed, other (batched and non-batched) * update requests are rejected with the `429` error code. diff --git a/src/Inventory/InventoryClient.php b/src/Inventory/InventoryClient.php index a194f717..9cabce1f 100644 --- a/src/Inventory/InventoryClient.php +++ b/src/Inventory/InventoryClient.php @@ -4,8 +4,8 @@ use Psr\Http\Client\ClientInterface; use Square\Core\Client\RawClient; -use Square\Inventory\Requests\DeprecatedGetAdjustmentInventoryRequest; -use Square\Types\GetInventoryAdjustmentResponse; +use Square\Inventory\Requests\ListInventoryAdjustmentReasonsRequest; +use Square\Types\ListInventoryAdjustmentReasonsResponse; use Square\Exceptions\SquareException; use Square\Exceptions\SquareApiException; use Square\Core\Json\JsonApiRequest; @@ -13,6 +13,20 @@ use Square\Core\Client\HttpMethod; use JsonException; use Psr\Http\Client\ClientExceptionInterface; +use Square\Inventory\Requests\CreateInventoryAdjustmentReasonRequest; +use Square\Types\CreateInventoryAdjustmentReasonResponse; +use Square\Inventory\Requests\DeleteInventoryAdjustmentReasonRequest; +use Square\Types\DeleteInventoryAdjustmentReasonResponse; +use Square\Inventory\Requests\RestoreInventoryAdjustmentReasonRequest; +use Square\Types\RestoreInventoryAdjustmentReasonResponse; +use Square\Inventory\Requests\RetrieveInventoryAdjustmentReasonRequest; +use Square\Types\RetrieveInventoryAdjustmentReasonResponse; +use Square\Inventory\Requests\UpdateInventoryAdjustmentReasonRequest; +use Square\Types\UpdateInventoryAdjustmentReasonResponse; +use Square\Inventory\Requests\DeprecatedGetAdjustmentInventoryRequest; +use Square\Types\GetInventoryAdjustmentResponse; +use Square\Inventory\Requests\UpdateInventoryAdjustmentRequest; +use Square\Types\UpdateInventoryAdjustmentResponse; use Square\Inventory\Requests\GetAdjustmentInventoryRequest; use Square\Types\BatchChangeInventoryRequest; use Square\Types\BatchChangeInventoryResponse; @@ -27,12 +41,11 @@ use Square\Inventory\Requests\DeprecatedGetPhysicalCountInventoryRequest; use Square\Types\GetInventoryPhysicalCountResponse; use Square\Inventory\Requests\GetPhysicalCountInventoryRequest; -use Square\Inventory\Requests\GetTransferInventoryRequest; -use Square\Types\GetInventoryTransferResponse; use Square\Inventory\Requests\GetInventoryRequest; use Square\Types\GetInventoryCountResponse; use Square\Inventory\Requests\ChangesInventoryRequest; use Square\Types\GetInventoryChangesResponse; +use Square\Inventory\Requests\GetTransferInventoryRequest; class InventoryClient { @@ -70,6 +83,291 @@ public function __construct( $this->options = $options ?? []; } + /** + * Returns the standard and custom inventory adjustment reasons available + * to the seller. + * + * @param ListInventoryAdjustmentReasonsRequest $request + * @param ?array{ + * baseUrl?: string, + * maxRetries?: int, + * timeout?: float, + * headers?: array, + * queryParameters?: array, + * bodyProperties?: array, + * } $options + * @return ListInventoryAdjustmentReasonsResponse + * @throws SquareException + * @throws SquareApiException + */ + public function listInventoryAdjustmentReasons(ListInventoryAdjustmentReasonsRequest $request = new ListInventoryAdjustmentReasonsRequest(), ?array $options = null): ListInventoryAdjustmentReasonsResponse + { + $options = array_merge($this->options, $options ?? []); + $query = []; + if ($request->getIncludeDeleted() != null) { + $query['include_deleted'] = $request->getIncludeDeleted(); + } + if ($request->getIncludeSystemCodes() != null) { + $query['include_system_codes'] = $request->getIncludeSystemCodes(); + } + try { + $response = $this->client->sendRequest( + new JsonApiRequest( + baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value, + path: "v2/inventory/adjustment-reasons", + method: HttpMethod::GET, + query: $query, + ), + $options, + ); + $statusCode = $response->getStatusCode(); + if ($statusCode >= 200 && $statusCode < 400) { + $json = $response->getBody()->getContents(); + return ListInventoryAdjustmentReasonsResponse::fromJson($json); + } + } catch (JsonException $e) { + throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e); + } catch (ClientExceptionInterface $e) { + throw new SquareException(message: $e->getMessage(), previous: $e); + } + throw new SquareApiException( + message: 'API request failed', + statusCode: $statusCode, + body: $response->getBody()->getContents(), + ); + } + + /** + * Creates a custom inventory adjustment reason. + * + * @param CreateInventoryAdjustmentReasonRequest $request + * @param ?array{ + * baseUrl?: string, + * maxRetries?: int, + * timeout?: float, + * headers?: array, + * queryParameters?: array, + * bodyProperties?: array, + * } $options + * @return CreateInventoryAdjustmentReasonResponse + * @throws SquareException + * @throws SquareApiException + */ + public function createInventoryAdjustmentReason(CreateInventoryAdjustmentReasonRequest $request, ?array $options = null): CreateInventoryAdjustmentReasonResponse + { + $options = array_merge($this->options, $options ?? []); + try { + $response = $this->client->sendRequest( + new JsonApiRequest( + baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value, + path: "v2/inventory/adjustment-reasons/create", + method: HttpMethod::POST, + body: $request, + ), + $options, + ); + $statusCode = $response->getStatusCode(); + if ($statusCode >= 200 && $statusCode < 400) { + $json = $response->getBody()->getContents(); + return CreateInventoryAdjustmentReasonResponse::fromJson($json); + } + } catch (JsonException $e) { + throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e); + } catch (ClientExceptionInterface $e) { + throw new SquareException(message: $e->getMessage(), previous: $e); + } + throw new SquareApiException( + message: 'API request failed', + statusCode: $statusCode, + body: $response->getBody()->getContents(), + ); + } + + /** + * Soft deletes a custom inventory adjustment reason. + * + * @param DeleteInventoryAdjustmentReasonRequest $request + * @param ?array{ + * baseUrl?: string, + * maxRetries?: int, + * timeout?: float, + * headers?: array, + * queryParameters?: array, + * bodyProperties?: array, + * } $options + * @return DeleteInventoryAdjustmentReasonResponse + * @throws SquareException + * @throws SquareApiException + */ + public function deleteInventoryAdjustmentReason(DeleteInventoryAdjustmentReasonRequest $request, ?array $options = null): DeleteInventoryAdjustmentReasonResponse + { + $options = array_merge($this->options, $options ?? []); + try { + $response = $this->client->sendRequest( + new JsonApiRequest( + baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value, + path: "v2/inventory/adjustment-reasons/delete", + method: HttpMethod::POST, + body: $request, + ), + $options, + ); + $statusCode = $response->getStatusCode(); + if ($statusCode >= 200 && $statusCode < 400) { + $json = $response->getBody()->getContents(); + return DeleteInventoryAdjustmentReasonResponse::fromJson($json); + } + } catch (JsonException $e) { + throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e); + } catch (ClientExceptionInterface $e) { + throw new SquareException(message: $e->getMessage(), previous: $e); + } + throw new SquareApiException( + message: 'API request failed', + statusCode: $statusCode, + body: $response->getBody()->getContents(), + ); + } + + /** + * Restores a soft-deleted custom inventory adjustment reason. + * + * @param RestoreInventoryAdjustmentReasonRequest $request + * @param ?array{ + * baseUrl?: string, + * maxRetries?: int, + * timeout?: float, + * headers?: array, + * queryParameters?: array, + * bodyProperties?: array, + * } $options + * @return RestoreInventoryAdjustmentReasonResponse + * @throws SquareException + * @throws SquareApiException + */ + public function restoreInventoryAdjustmentReason(RestoreInventoryAdjustmentReasonRequest $request, ?array $options = null): RestoreInventoryAdjustmentReasonResponse + { + $options = array_merge($this->options, $options ?? []); + try { + $response = $this->client->sendRequest( + new JsonApiRequest( + baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value, + path: "v2/inventory/adjustment-reasons/restore", + method: HttpMethod::POST, + body: $request, + ), + $options, + ); + $statusCode = $response->getStatusCode(); + if ($statusCode >= 200 && $statusCode < 400) { + $json = $response->getBody()->getContents(); + return RestoreInventoryAdjustmentReasonResponse::fromJson($json); + } + } catch (JsonException $e) { + throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e); + } catch (ClientExceptionInterface $e) { + throw new SquareException(message: $e->getMessage(), previous: $e); + } + throw new SquareApiException( + message: 'API request failed', + statusCode: $statusCode, + body: $response->getBody()->getContents(), + ); + } + + /** + * Returns the inventory adjustment reason identified by the provided + * `reason_id`. Deleted custom reasons can be retrieved by ID. + * + * @param RetrieveInventoryAdjustmentReasonRequest $request + * @param ?array{ + * baseUrl?: string, + * maxRetries?: int, + * timeout?: float, + * headers?: array, + * queryParameters?: array, + * bodyProperties?: array, + * } $options + * @return RetrieveInventoryAdjustmentReasonResponse + * @throws SquareException + * @throws SquareApiException + */ + public function retrieveInventoryAdjustmentReason(RetrieveInventoryAdjustmentReasonRequest $request, ?array $options = null): RetrieveInventoryAdjustmentReasonResponse + { + $options = array_merge($this->options, $options ?? []); + try { + $response = $this->client->sendRequest( + new JsonApiRequest( + baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value, + path: "v2/inventory/adjustment-reasons/retrieve", + method: HttpMethod::POST, + body: $request, + ), + $options, + ); + $statusCode = $response->getStatusCode(); + if ($statusCode >= 200 && $statusCode < 400) { + $json = $response->getBody()->getContents(); + return RetrieveInventoryAdjustmentReasonResponse::fromJson($json); + } + } catch (JsonException $e) { + throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e); + } catch (ClientExceptionInterface $e) { + throw new SquareException(message: $e->getMessage(), previous: $e); + } + throw new SquareApiException( + message: 'API request failed', + statusCode: $statusCode, + body: $response->getBody()->getContents(), + ); + } + + /** + * Updates a custom inventory adjustment reason. + * + * @param UpdateInventoryAdjustmentReasonRequest $request + * @param ?array{ + * baseUrl?: string, + * maxRetries?: int, + * timeout?: float, + * headers?: array, + * queryParameters?: array, + * bodyProperties?: array, + * } $options + * @return UpdateInventoryAdjustmentReasonResponse + * @throws SquareException + * @throws SquareApiException + */ + public function updateInventoryAdjustmentReason(UpdateInventoryAdjustmentReasonRequest $request, ?array $options = null): UpdateInventoryAdjustmentReasonResponse + { + $options = array_merge($this->options, $options ?? []); + try { + $response = $this->client->sendRequest( + new JsonApiRequest( + baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value, + path: "v2/inventory/adjustment-reasons/update", + method: HttpMethod::PUT, + body: $request, + ), + $options, + ); + $statusCode = $response->getStatusCode(); + if ($statusCode >= 200 && $statusCode < 400) { + $json = $response->getBody()->getContents(); + return UpdateInventoryAdjustmentReasonResponse::fromJson($json); + } + } catch (JsonException $e) { + throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e); + } catch (ClientExceptionInterface $e) { + throw new SquareException(message: $e->getMessage(), previous: $e); + } + throw new SquareApiException( + message: 'API request failed', + statusCode: $statusCode, + body: $response->getBody()->getContents(), + ); + } + /** * Deprecated version of [RetrieveInventoryAdjustment](api-endpoint:Inventory-RetrieveInventoryAdjustment) after the endpoint URL * is updated to conform to the standard convention. @@ -116,6 +414,55 @@ public function deprecatedGetAdjustment(DeprecatedGetAdjustmentInventoryRequest ); } + /** + * Applies an update to the provided adjustment. + * + * On success: returns the newly updated adjustment. + * On failure: returns a list of related errors. + * + * @param UpdateInventoryAdjustmentRequest $request + * @param ?array{ + * baseUrl?: string, + * maxRetries?: int, + * timeout?: float, + * headers?: array, + * queryParameters?: array, + * bodyProperties?: array, + * } $options + * @return UpdateInventoryAdjustmentResponse + * @throws SquareException + * @throws SquareApiException + */ + public function updateInventoryAdjustment(UpdateInventoryAdjustmentRequest $request, ?array $options = null): UpdateInventoryAdjustmentResponse + { + $options = array_merge($this->options, $options ?? []); + try { + $response = $this->client->sendRequest( + new JsonApiRequest( + baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value, + path: "v2/inventory/adjustments/update", + method: HttpMethod::PUT, + body: $request, + ), + $options, + ); + $statusCode = $response->getStatusCode(); + if ($statusCode >= 200 && $statusCode < 400) { + $json = $response->getBody()->getContents(); + return UpdateInventoryAdjustmentResponse::fromJson($json); + } + } catch (JsonException $e) { + throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e); + } catch (ClientExceptionInterface $e) { + throw new SquareException(message: $e->getMessage(), previous: $e); + } + throw new SquareApiException( + message: 'API request failed', + statusCode: $statusCode, + body: $response->getBody()->getContents(), + ); + } + /** * Returns the [InventoryAdjustment](entity:InventoryAdjustment) object * with the provided `adjustment_id`. @@ -520,52 +867,6 @@ public function getPhysicalCount(GetPhysicalCountInventoryRequest $request, ?arr ); } - /** - * Returns the [InventoryTransfer](entity:InventoryTransfer) object - * with the provided `transfer_id`. - * - * @param GetTransferInventoryRequest $request - * @param ?array{ - * baseUrl?: string, - * maxRetries?: int, - * timeout?: float, - * headers?: array, - * queryParameters?: array, - * bodyProperties?: array, - * } $options - * @return GetInventoryTransferResponse - * @throws SquareException - * @throws SquareApiException - */ - public function getTransfer(GetTransferInventoryRequest $request, ?array $options = null): GetInventoryTransferResponse - { - $options = array_merge($this->options, $options ?? []); - try { - $response = $this->client->sendRequest( - new JsonApiRequest( - baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value, - path: "v2/inventory/transfers/{$request->getTransferId()}", - method: HttpMethod::GET, - ), - $options, - ); - $statusCode = $response->getStatusCode(); - if ($statusCode >= 200 && $statusCode < 400) { - $json = $response->getBody()->getContents(); - return GetInventoryTransferResponse::fromJson($json); - } - } catch (JsonException $e) { - throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e); - } catch (ClientExceptionInterface $e) { - throw new SquareException(message: $e->getMessage(), previous: $e); - } - throw new SquareApiException( - message: 'API request failed', - statusCode: $statusCode, - body: $response->getBody()->getContents(), - ); - } - /** * Retrieves the current calculated stock count for a given * [CatalogObject](entity:CatalogObject) at a given set of @@ -639,6 +940,45 @@ public function changes(ChangesInventoryRequest $request, ?array $options = null ); } + /** + * @param GetTransferInventoryRequest $request + * @param ?array{ + * baseUrl?: string, + * maxRetries?: int, + * timeout?: float, + * headers?: array, + * queryParameters?: array, + * bodyProperties?: array, + * } $options + * @throws SquareException + * @throws SquareApiException + */ + public function getTransfer(GetTransferInventoryRequest $request, ?array $options = null): void + { + $options = array_merge($this->options, $options ?? []); + try { + $response = $this->client->sendRequest( + new JsonApiRequest( + baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value, + path: "v2/inventory/transfers/{$request->getTransferId()}", + method: HttpMethod::GET, + ), + $options, + ); + $statusCode = $response->getStatusCode(); + if ($statusCode >= 200 && $statusCode < 400) { + return; + } + } catch (ClientExceptionInterface $e) { + throw new SquareException(message: $e->getMessage(), previous: $e); + } + throw new SquareApiException( + message: 'API request failed', + statusCode: $statusCode, + body: $response->getBody()->getContents(), + ); + } + /** * Returns historical physical counts and adjustments based on the * provided filter criteria. diff --git a/src/Inventory/Requests/CreateInventoryAdjustmentReasonRequest.php b/src/Inventory/Requests/CreateInventoryAdjustmentReasonRequest.php new file mode 100644 index 00000000..82e93927 --- /dev/null +++ b/src/Inventory/Requests/CreateInventoryAdjustmentReasonRequest.php @@ -0,0 +1,78 @@ +idempotencyKey = $values['idempotencyKey']; + $this->adjustmentReason = $values['adjustmentReason']; + } + + /** + * @return string + */ + public function getIdempotencyKey(): string + { + return $this->idempotencyKey; + } + + /** + * @param string $value + */ + public function setIdempotencyKey(string $value): self + { + $this->idempotencyKey = $value; + $this->_setField('idempotencyKey'); + return $this; + } + + /** + * @return InventoryAdjustmentReason + */ + public function getAdjustmentReason(): InventoryAdjustmentReason + { + return $this->adjustmentReason; + } + + /** + * @param InventoryAdjustmentReason $value + */ + public function setAdjustmentReason(InventoryAdjustmentReason $value): self + { + $this->adjustmentReason = $value; + $this->_setField('adjustmentReason'); + return $this; + } +} diff --git a/src/Inventory/Requests/DeleteInventoryAdjustmentReasonRequest.php b/src/Inventory/Requests/DeleteInventoryAdjustmentReasonRequest.php new file mode 100644 index 00000000..dce11526 --- /dev/null +++ b/src/Inventory/Requests/DeleteInventoryAdjustmentReasonRequest.php @@ -0,0 +1,45 @@ +reasonId = $values['reasonId']; + } + + /** + * @return InventoryAdjustmentReasonId + */ + public function getReasonId(): InventoryAdjustmentReasonId + { + return $this->reasonId; + } + + /** + * @param InventoryAdjustmentReasonId $value + */ + public function setReasonId(InventoryAdjustmentReasonId $value): self + { + $this->reasonId = $value; + $this->_setField('reasonId'); + return $this; + } +} diff --git a/src/Inventory/Requests/GetTransferInventoryRequest.php b/src/Inventory/Requests/GetTransferInventoryRequest.php index cf862992..9fece810 100644 --- a/src/Inventory/Requests/GetTransferInventoryRequest.php +++ b/src/Inventory/Requests/GetTransferInventoryRequest.php @@ -7,7 +7,7 @@ class GetTransferInventoryRequest extends JsonSerializableType { /** - * @var string $transferId ID of the [InventoryTransfer](entity:InventoryTransfer) to retrieve. + * @var string $transferId */ private string $transferId; diff --git a/src/Inventory/Requests/ListInventoryAdjustmentReasonsRequest.php b/src/Inventory/Requests/ListInventoryAdjustmentReasonsRequest.php new file mode 100644 index 00000000..6511b8d3 --- /dev/null +++ b/src/Inventory/Requests/ListInventoryAdjustmentReasonsRequest.php @@ -0,0 +1,75 @@ +includeDeleted = $values['includeDeleted'] ?? null; + $this->includeSystemCodes = $values['includeSystemCodes'] ?? null; + } + + /** + * @return ?bool + */ + public function getIncludeDeleted(): ?bool + { + return $this->includeDeleted; + } + + /** + * @param ?bool $value + */ + public function setIncludeDeleted(?bool $value = null): self + { + $this->includeDeleted = $value; + $this->_setField('includeDeleted'); + return $this; + } + + /** + * @return ?bool + */ + public function getIncludeSystemCodes(): ?bool + { + return $this->includeSystemCodes; + } + + /** + * @param ?bool $value + */ + public function setIncludeSystemCodes(?bool $value = null): self + { + $this->includeSystemCodes = $value; + $this->_setField('includeSystemCodes'); + return $this; + } +} diff --git a/src/Inventory/Requests/RestoreInventoryAdjustmentReasonRequest.php b/src/Inventory/Requests/RestoreInventoryAdjustmentReasonRequest.php new file mode 100644 index 00000000..6dd162fe --- /dev/null +++ b/src/Inventory/Requests/RestoreInventoryAdjustmentReasonRequest.php @@ -0,0 +1,48 @@ +reasonId = $values['reasonId']; + } + + /** + * @return InventoryAdjustmentReasonId + */ + public function getReasonId(): InventoryAdjustmentReasonId + { + return $this->reasonId; + } + + /** + * @param InventoryAdjustmentReasonId $value + */ + public function setReasonId(InventoryAdjustmentReasonId $value): self + { + $this->reasonId = $value; + $this->_setField('reasonId'); + return $this; + } +} diff --git a/src/Inventory/Requests/RetrieveInventoryAdjustmentReasonRequest.php b/src/Inventory/Requests/RetrieveInventoryAdjustmentReasonRequest.php new file mode 100644 index 00000000..4984716c --- /dev/null +++ b/src/Inventory/Requests/RetrieveInventoryAdjustmentReasonRequest.php @@ -0,0 +1,45 @@ +reasonId = $values['reasonId']; + } + + /** + * @return InventoryAdjustmentReasonId + */ + public function getReasonId(): InventoryAdjustmentReasonId + { + return $this->reasonId; + } + + /** + * @param InventoryAdjustmentReasonId $value + */ + public function setReasonId(InventoryAdjustmentReasonId $value): self + { + $this->reasonId = $value; + $this->_setField('reasonId'); + return $this; + } +} diff --git a/src/Inventory/Requests/UpdateInventoryAdjustmentReasonRequest.php b/src/Inventory/Requests/UpdateInventoryAdjustmentReasonRequest.php new file mode 100644 index 00000000..811cdf78 --- /dev/null +++ b/src/Inventory/Requests/UpdateInventoryAdjustmentReasonRequest.php @@ -0,0 +1,77 @@ +reasonId = $values['reasonId']; + $this->adjustmentReason = $values['adjustmentReason']; + } + + /** + * @return InventoryAdjustmentReasonId + */ + public function getReasonId(): InventoryAdjustmentReasonId + { + return $this->reasonId; + } + + /** + * @param InventoryAdjustmentReasonId $value + */ + public function setReasonId(InventoryAdjustmentReasonId $value): self + { + $this->reasonId = $value; + $this->_setField('reasonId'); + return $this; + } + + /** + * @return InventoryAdjustmentReason + */ + public function getAdjustmentReason(): InventoryAdjustmentReason + { + return $this->adjustmentReason; + } + + /** + * @param InventoryAdjustmentReason $value + */ + public function setAdjustmentReason(InventoryAdjustmentReason $value): self + { + $this->adjustmentReason = $value; + $this->_setField('adjustmentReason'); + return $this; + } +} diff --git a/src/Inventory/Requests/UpdateInventoryAdjustmentRequest.php b/src/Inventory/Requests/UpdateInventoryAdjustmentRequest.php new file mode 100644 index 00000000..44885e59 --- /dev/null +++ b/src/Inventory/Requests/UpdateInventoryAdjustmentRequest.php @@ -0,0 +1,91 @@ +idempotencyKey = $values['idempotencyKey']; + $this->adjustment = $values['adjustment']; + } + + /** + * @return string + */ + public function getIdempotencyKey(): string + { + return $this->idempotencyKey; + } + + /** + * @param string $value + */ + public function setIdempotencyKey(string $value): self + { + $this->idempotencyKey = $value; + $this->_setField('idempotencyKey'); + return $this; + } + + /** + * @return InventoryAdjustment + */ + public function getAdjustment(): InventoryAdjustment + { + return $this->adjustment; + } + + /** + * @param InventoryAdjustment $value + */ + public function setAdjustment(InventoryAdjustment $value): self + { + $this->adjustment = $value; + $this->_setField('adjustment'); + return $this; + } +} diff --git a/src/SquareClient.php b/src/SquareClient.php index a4603007..30d6c9e8 100644 --- a/src/SquareClient.php +++ b/src/SquareClient.php @@ -259,11 +259,11 @@ public function __construct( $token ??= $this->getFromEnvOrThrow('SQUARE_TOKEN', 'Please pass in token or set the environment variable SQUARE_TOKEN.'); $defaultHeaders = [ 'Authorization' => "Bearer $token", - 'Square-Version' => '2026-05-20', + 'Square-Version' => '2026-07-15', 'X-Fern-Language' => 'PHP', 'X-Fern-SDK-Name' => 'Square', - 'X-Fern-SDK-Version' => '45.2.0-rc.0', - 'User-Agent' => 'square/square/45.2.0-rc.0', + 'X-Fern-SDK-Version' => '46.0.1.20260715', + 'User-Agent' => 'square/square/46.0.1.20260715', ]; if ($version != null) { $defaultHeaders['Square-Version'] = $version; diff --git a/src/Types/BatchRetrieveInventoryChangesRequest.php b/src/Types/BatchRetrieveInventoryChangesRequest.php index d6ff7249..58f131ce 100644 --- a/src/Types/BatchRetrieveInventoryChangesRequest.php +++ b/src/Types/BatchRetrieveInventoryChangesRequest.php @@ -82,6 +82,27 @@ class BatchRetrieveInventoryChangesRequest extends JsonSerializableType #[JsonProperty('limit')] private ?int $limit; + /** + * Specification of how returned inventory changes should be ordered. + * + * Currently, inventory changes can only be ordered by the occurred_at field. + * The default sort order for occurred_at is ASC (changes are returned oldest-first by default). + * + * @var ?BatchRetrieveInventoryChangesSort $sort + */ + #[JsonProperty('sort')] + private ?BatchRetrieveInventoryChangesSort $sort; + + /** + * The filter to return `ADJUSTMENT` query results by inventory + * adjustment reason. This filter is only applied when set. The request cannot + * include both `reason_ids` and `states`. + * + * @var ?array $reasonIds + */ + #[JsonProperty('reason_ids'), ArrayType([InventoryAdjustmentReasonId::class])] + private ?array $reasonIds; + /** * @param array{ * catalogObjectIds?: ?array, @@ -92,6 +113,8 @@ class BatchRetrieveInventoryChangesRequest extends JsonSerializableType * updatedBefore?: ?string, * cursor?: ?string, * limit?: ?int, + * sort?: ?BatchRetrieveInventoryChangesSort, + * reasonIds?: ?array, * } $values */ public function __construct( @@ -105,6 +128,8 @@ public function __construct( $this->updatedBefore = $values['updatedBefore'] ?? null; $this->cursor = $values['cursor'] ?? null; $this->limit = $values['limit'] ?? null; + $this->sort = $values['sort'] ?? null; + $this->reasonIds = $values['reasonIds'] ?? null; } /** @@ -251,6 +276,42 @@ public function setLimit(?int $value = null): self return $this; } + /** + * @return ?BatchRetrieveInventoryChangesSort + */ + public function getSort(): ?BatchRetrieveInventoryChangesSort + { + return $this->sort; + } + + /** + * @param ?BatchRetrieveInventoryChangesSort $value + */ + public function setSort(?BatchRetrieveInventoryChangesSort $value = null): self + { + $this->sort = $value; + $this->_setField('sort'); + return $this; + } + + /** + * @return ?array + */ + public function getReasonIds(): ?array + { + return $this->reasonIds; + } + + /** + * @param ?array $value + */ + public function setReasonIds(?array $value = null): self + { + $this->reasonIds = $value; + $this->_setField('reasonIds'); + return $this; + } + /** * @return string */ diff --git a/src/Types/BatchRetrieveInventoryChangesSort.php b/src/Types/BatchRetrieveInventoryChangesSort.php new file mode 100644 index 00000000..5350b36b --- /dev/null +++ b/src/Types/BatchRetrieveInventoryChangesSort.php @@ -0,0 +1,84 @@ + $order + */ + #[JsonProperty('order')] + private ?string $order; + + /** + * @param array{ + * field?: ?'OCCURRED_AT', + * order?: ?value-of, + * } $values + */ + public function __construct( + array $values = [], + ) { + $this->field = $values['field'] ?? null; + $this->order = $values['order'] ?? null; + } + + /** + * @return ?'OCCURRED_AT' + */ + public function getField(): ?string + { + return $this->field; + } + + /** + * @param ?'OCCURRED_AT' $value + */ + public function setField(?string $value = null): self + { + $this->field = $value; + $this->_setField('field'); + return $this; + } + + /** + * @return ?value-of + */ + public function getOrder(): ?string + { + return $this->order; + } + + /** + * @param ?value-of $value + */ + public function setOrder(?string $value = null): self + { + $this->order = $value; + $this->_setField('order'); + return $this; + } + + /** + * @return string + */ + public function __toString(): string + { + return $this->toJson(); + } +} diff --git a/src/Types/CatalogCategory.php b/src/Types/CatalogCategory.php index 60c5f46d..30956f06 100644 --- a/src/Types/CatalogCategory.php +++ b/src/Types/CatalogCategory.php @@ -36,7 +36,10 @@ class CatalogCategory extends JsonSerializableType private ?string $categoryType; /** - * @var ?CatalogObjectCategory $parentCategory The ID of the parent category of this category instance. + * The parent category of this category instance. This includes the parent category ID and an ordinal + * value that determines the category's relative position among sibling categories with the same parent. + * + * @var ?CatalogObjectCategory $parentCategory */ #[JsonProperty('parent_category')] private ?CatalogObjectCategory $parentCategory; diff --git a/src/Types/CatalogItem.php b/src/Types/CatalogItem.php index a2d6464e..6cacd070 100644 --- a/src/Types/CatalogItem.php +++ b/src/Types/CatalogItem.php @@ -166,7 +166,10 @@ class CatalogItem extends JsonSerializableType private ?string $sortName; /** - * @var ?array $categories The list of categories. + * The list of categories to which this item belongs. Each entry includes the category ID and an ordinal + * value that determines the item's relative position within that category. + * + * @var ?array $categories */ #[JsonProperty('categories'), ArrayType([CatalogObjectCategory::class])] private ?array $categories; diff --git a/src/Types/CatalogItemVariation.php b/src/Types/CatalogItemVariation.php index 3b145a72..16635000 100644 --- a/src/Types/CatalogItemVariation.php +++ b/src/Types/CatalogItemVariation.php @@ -90,7 +90,11 @@ class CatalogItemVariation extends JsonSerializableType private ?array $locationOverrides; /** - * @var ?bool $trackInventory If `true`, inventory tracking is active for the variation. + * If `true`, inventory tracking is active for the variation at all locations by default. + * This value can be overridden for specific locations using `ItemVariationLocationOverrides.track_inventory`. + * If unset at both levels, inventory tracking is disabled. + * + * @var ?bool $trackInventory */ #[JsonProperty('track_inventory')] private ?bool $trackInventory; @@ -98,6 +102,8 @@ class CatalogItemVariation extends JsonSerializableType /** * Indicates whether the item variation displays an alert when its inventory quantity is less than or equal * to its `inventory_alert_threshold`. + * + * Deprecated because this field has never been global. * See [InventoryAlertType](#type-inventoryalerttype) for possible values * * @var ?value-of $inventoryAlertType @@ -107,9 +113,9 @@ class CatalogItemVariation extends JsonSerializableType /** * If the inventory quantity for the variation is less than or equal to this value and `inventory_alert_type` - * is `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard. + * is `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard. This value is always an integer. * - * This value is always an integer. + * Deprecated because this field has never been global. * * @var ?int $inventoryAlertThreshold */ @@ -222,6 +228,16 @@ class CatalogItemVariation extends JsonSerializableType #[JsonProperty('kitchen_name')] private ?string $kitchenName; + /** + * Details of the vendor this product is purchased from. + * This field can be set only if the seller has an active subscription + * to either Square for Retail Premium or Square for Restaurants Premium. + * + * @var ?array $vendorInformation + */ + #[JsonProperty('vendor_information'), ArrayType([CatalogItemVariationVendorInformation::class])] + private ?array $vendorInformation; + /** * @param array{ * itemId?: ?string, @@ -246,6 +262,7 @@ class CatalogItemVariation extends JsonSerializableType * teamMemberIds?: ?array, * stockableConversion?: ?CatalogStockConversion, * kitchenName?: ?string, + * vendorInformation?: ?array, * } $values */ public function __construct( @@ -273,6 +290,7 @@ public function __construct( $this->teamMemberIds = $values['teamMemberIds'] ?? null; $this->stockableConversion = $values['stockableConversion'] ?? null; $this->kitchenName = $values['kitchenName'] ?? null; + $this->vendorInformation = $values['vendorInformation'] ?? null; } /** @@ -671,6 +689,24 @@ public function setKitchenName(?string $value = null): self return $this; } + /** + * @return ?array + */ + public function getVendorInformation(): ?array + { + return $this->vendorInformation; + } + + /** + * @param ?array $value + */ + public function setVendorInformation(?array $value = null): self + { + $this->vendorInformation = $value; + $this->_setField('vendorInformation'); + return $this; + } + /** * @return string */ diff --git a/src/Types/CatalogItemVariationVendorInformation.php b/src/Types/CatalogItemVariationVendorInformation.php new file mode 100644 index 00000000..2198c967 --- /dev/null +++ b/src/Types/CatalogItemVariationVendorInformation.php @@ -0,0 +1,116 @@ +vendorId = $values['vendorId'] ?? null; + $this->vendorCode = $values['vendorCode'] ?? null; + $this->unitCostMoney = $values['unitCostMoney'] ?? null; + } + + /** + * @return ?string + */ + public function getVendorId(): ?string + { + return $this->vendorId; + } + + /** + * @param ?string $value + */ + public function setVendorId(?string $value = null): self + { + $this->vendorId = $value; + $this->_setField('vendorId'); + return $this; + } + + /** + * @return ?string + */ + public function getVendorCode(): ?string + { + return $this->vendorCode; + } + + /** + * @param ?string $value + */ + public function setVendorCode(?string $value = null): self + { + $this->vendorCode = $value; + $this->_setField('vendorCode'); + return $this; + } + + /** + * @return ?Money + */ + public function getUnitCostMoney(): ?Money + { + return $this->unitCostMoney; + } + + /** + * @param ?Money $value + */ + public function setUnitCostMoney(?Money $value = null): self + { + $this->unitCostMoney = $value; + $this->_setField('unitCostMoney'); + return $this; + } + + /** + * @return string + */ + public function __toString(): string + { + return $this->toJson(); + } +} diff --git a/src/Types/CatalogObjectCategory.php b/src/Types/CatalogObjectCategory.php index 3587e54c..3c22e694 100644 --- a/src/Types/CatalogObjectCategory.php +++ b/src/Types/CatalogObjectCategory.php @@ -20,7 +20,11 @@ class CatalogObjectCategory extends JsonSerializableType private ?string $id; /** - * @var ?int $ordinal The order of the object within the context of the category. + * The position of this object within the specified category. When an item is assigned to a category, + * the ordinal determines the item's position relative to other items in the same category. When used for a + * parent category reference, the ordinal determines the category's position among its sibling categories. + * + * @var ?int $ordinal */ #[JsonProperty('ordinal')] private ?int $ordinal; diff --git a/src/Types/CreateInventoryAdjustmentReasonResponse.php b/src/Types/CreateInventoryAdjustmentReasonResponse.php new file mode 100644 index 00000000..daae24fb --- /dev/null +++ b/src/Types/CreateInventoryAdjustmentReasonResponse.php @@ -0,0 +1,82 @@ + $errors Errors encountered when the request fails. + */ + #[JsonProperty('errors'), ArrayType([Error::class])] + private ?array $errors; + + /** + * @var ?InventoryAdjustmentReason $adjustmentReason The successfully created inventory adjustment reason. + */ + #[JsonProperty('adjustment_reason')] + private ?InventoryAdjustmentReason $adjustmentReason; + + /** + * @param array{ + * errors?: ?array, + * adjustmentReason?: ?InventoryAdjustmentReason, + * } $values + */ + public function __construct( + array $values = [], + ) { + $this->errors = $values['errors'] ?? null; + $this->adjustmentReason = $values['adjustmentReason'] ?? null; + } + + /** + * @return ?array + */ + public function getErrors(): ?array + { + return $this->errors; + } + + /** + * @param ?array $value + */ + public function setErrors(?array $value = null): self + { + $this->errors = $value; + $this->_setField('errors'); + return $this; + } + + /** + * @return ?InventoryAdjustmentReason + */ + public function getAdjustmentReason(): ?InventoryAdjustmentReason + { + return $this->adjustmentReason; + } + + /** + * @param ?InventoryAdjustmentReason $value + */ + public function setAdjustmentReason(?InventoryAdjustmentReason $value = null): self + { + $this->adjustmentReason = $value; + $this->_setField('adjustmentReason'); + return $this; + } + + /** + * @return string + */ + public function __toString(): string + { + return $this->toJson(); + } +} diff --git a/src/Types/DeleteInventoryAdjustmentReasonResponse.php b/src/Types/DeleteInventoryAdjustmentReasonResponse.php new file mode 100644 index 00000000..03390dc0 --- /dev/null +++ b/src/Types/DeleteInventoryAdjustmentReasonResponse.php @@ -0,0 +1,82 @@ + $errors Errors encountered when the request fails. + */ + #[JsonProperty('errors'), ArrayType([Error::class])] + private ?array $errors; + + /** + * @var ?InventoryAdjustmentReason $adjustmentReason The successfully soft-deleted inventory adjustment reason. + */ + #[JsonProperty('adjustment_reason')] + private ?InventoryAdjustmentReason $adjustmentReason; + + /** + * @param array{ + * errors?: ?array, + * adjustmentReason?: ?InventoryAdjustmentReason, + * } $values + */ + public function __construct( + array $values = [], + ) { + $this->errors = $values['errors'] ?? null; + $this->adjustmentReason = $values['adjustmentReason'] ?? null; + } + + /** + * @return ?array + */ + public function getErrors(): ?array + { + return $this->errors; + } + + /** + * @param ?array $value + */ + public function setErrors(?array $value = null): self + { + $this->errors = $value; + $this->_setField('errors'); + return $this; + } + + /** + * @return ?InventoryAdjustmentReason + */ + public function getAdjustmentReason(): ?InventoryAdjustmentReason + { + return $this->adjustmentReason; + } + + /** + * @param ?InventoryAdjustmentReason $value + */ + public function setAdjustmentReason(?InventoryAdjustmentReason $value = null): self + { + $this->adjustmentReason = $value; + $this->_setField('adjustmentReason'); + return $this; + } + + /** + * @return string + */ + public function __toString(): string + { + return $this->toJson(); + } +} diff --git a/src/Types/DeviceCheckoutOptions.php b/src/Types/DeviceCheckoutOptions.php index af8b304d..d7e92c74 100644 --- a/src/Types/DeviceCheckoutOptions.php +++ b/src/Types/DeviceCheckoutOptions.php @@ -48,7 +48,7 @@ class DeviceCheckoutOptions extends JsonSerializableType * Controls whether the mobile client applies Auto Card Surcharge (ACS) during checkout. * If true, ACS is applied based on Dashboard configuration. * If false, ACS is not applied regardless of that configuration. - * For more information, see [Add a Card Surcharge](https://developer.squareupstaging.com/docs/terminal-api/additional-payment-checkout-features#add-a-card-surcharge). + * For more information, see [Add a Card Surcharge](https://developer.squareup.com/docs/terminal-api/additional-payment-checkout-features#add-a-card-surcharge). * * @var ?bool $allowAutoCardSurcharge */ diff --git a/src/Types/ExcludeStrategy.php b/src/Types/ExcludeStrategy.php index 777874b9..91bce93c 100644 --- a/src/Types/ExcludeStrategy.php +++ b/src/Types/ExcludeStrategy.php @@ -6,4 +6,5 @@ enum ExcludeStrategy: string { case LeastExpensive = "LEAST_EXPENSIVE"; case MostExpensive = "MOST_EXPENSIVE"; + case MostExpensiveLowestValue = "MOST_EXPENSIVE_LOWEST_VALUE"; } diff --git a/src/Types/Fulfillment.php b/src/Types/Fulfillment.php index afa66ca7..26e53e44 100644 --- a/src/Types/Fulfillment.php +++ b/src/Types/Fulfillment.php @@ -123,6 +123,15 @@ class Fulfillment extends JsonSerializableType #[JsonProperty('delivery_details')] private ?FulfillmentDeliveryDetails $deliveryDetails; + /** + * Contains details for an in-store fulfillment. These details are required when the fulfillment + * type is `IN_STORE`. + * + * @var ?FulfillmentInStoreDetails $inStoreDetails + */ + #[JsonProperty('in_store_details')] + private ?FulfillmentInStoreDetails $inStoreDetails; + /** * @param array{ * uid?: ?string, @@ -134,6 +143,7 @@ class Fulfillment extends JsonSerializableType * pickupDetails?: ?FulfillmentPickupDetails, * shipmentDetails?: ?FulfillmentShipmentDetails, * deliveryDetails?: ?FulfillmentDeliveryDetails, + * inStoreDetails?: ?FulfillmentInStoreDetails, * } $values */ public function __construct( @@ -148,6 +158,7 @@ public function __construct( $this->pickupDetails = $values['pickupDetails'] ?? null; $this->shipmentDetails = $values['shipmentDetails'] ?? null; $this->deliveryDetails = $values['deliveryDetails'] ?? null; + $this->inStoreDetails = $values['inStoreDetails'] ?? null; } /** @@ -312,6 +323,24 @@ public function setDeliveryDetails(?FulfillmentDeliveryDetails $value = null): s return $this; } + /** + * @return ?FulfillmentInStoreDetails + */ + public function getInStoreDetails(): ?FulfillmentInStoreDetails + { + return $this->inStoreDetails; + } + + /** + * @param ?FulfillmentInStoreDetails $value + */ + public function setInStoreDetails(?FulfillmentInStoreDetails $value = null): self + { + $this->inStoreDetails = $value; + $this->_setField('inStoreDetails'); + return $this; + } + /** * @return string */ diff --git a/src/Types/FulfillmentInStoreDetails.php b/src/Types/FulfillmentInStoreDetails.php new file mode 100644 index 00000000..2be14358 --- /dev/null +++ b/src/Types/FulfillmentInStoreDetails.php @@ -0,0 +1,237 @@ +note = $values['note'] ?? null; + $this->recipient = $values['recipient'] ?? null; + $this->placedAt = $values['placedAt'] ?? null; + $this->completedAt = $values['completedAt'] ?? null; + $this->inProgressAt = $values['inProgressAt'] ?? null; + $this->preparedAt = $values['preparedAt'] ?? null; + $this->canceledAt = $values['canceledAt'] ?? null; + } + + /** + * @return ?string + */ + public function getNote(): ?string + { + return $this->note; + } + + /** + * @param ?string $value + */ + public function setNote(?string $value = null): self + { + $this->note = $value; + $this->_setField('note'); + return $this; + } + + /** + * @return ?FulfillmentRecipient + */ + public function getRecipient(): ?FulfillmentRecipient + { + return $this->recipient; + } + + /** + * @param ?FulfillmentRecipient $value + */ + public function setRecipient(?FulfillmentRecipient $value = null): self + { + $this->recipient = $value; + $this->_setField('recipient'); + return $this; + } + + /** + * @return ?string + */ + public function getPlacedAt(): ?string + { + return $this->placedAt; + } + + /** + * @param ?string $value + */ + public function setPlacedAt(?string $value = null): self + { + $this->placedAt = $value; + $this->_setField('placedAt'); + return $this; + } + + /** + * @return ?string + */ + public function getCompletedAt(): ?string + { + return $this->completedAt; + } + + /** + * @param ?string $value + */ + public function setCompletedAt(?string $value = null): self + { + $this->completedAt = $value; + $this->_setField('completedAt'); + return $this; + } + + /** + * @return ?string + */ + public function getInProgressAt(): ?string + { + return $this->inProgressAt; + } + + /** + * @param ?string $value + */ + public function setInProgressAt(?string $value = null): self + { + $this->inProgressAt = $value; + $this->_setField('inProgressAt'); + return $this; + } + + /** + * @return ?string + */ + public function getPreparedAt(): ?string + { + return $this->preparedAt; + } + + /** + * @param ?string $value + */ + public function setPreparedAt(?string $value = null): self + { + $this->preparedAt = $value; + $this->_setField('preparedAt'); + return $this; + } + + /** + * @return ?string + */ + public function getCanceledAt(): ?string + { + return $this->canceledAt; + } + + /** + * @param ?string $value + */ + public function setCanceledAt(?string $value = null): self + { + $this->canceledAt = $value; + $this->_setField('canceledAt'); + return $this; + } + + /** + * @return string + */ + public function __toString(): string + { + return $this->toJson(); + } +} diff --git a/src/Types/FulfillmentType.php b/src/Types/FulfillmentType.php index c965dab8..6bfc9ff6 100644 --- a/src/Types/FulfillmentType.php +++ b/src/Types/FulfillmentType.php @@ -7,4 +7,5 @@ enum FulfillmentType: string case Pickup = "PICKUP"; case Shipment = "SHIPMENT"; case Delivery = "DELIVERY"; + case InStore = "IN_STORE"; } diff --git a/src/Types/InventoryAdjustment.php b/src/Types/InventoryAdjustment.php index 96882b30..89b39bb2 100644 --- a/src/Types/InventoryAdjustment.php +++ b/src/Types/InventoryAdjustment.php @@ -52,12 +52,21 @@ class InventoryAdjustment extends JsonSerializableType /** * The Square-generated ID of the [Location](entity:Location) where the related - * quantity of items is being tracked. + * quantity of items is being tracked before the adjustment. * - * @var ?string $locationId + * @var ?string $fromLocationId */ - #[JsonProperty('location_id')] - private ?string $locationId; + #[JsonProperty('from_location_id')] + private ?string $fromLocationId; + + /** + * The Square-generated ID of the [Location](entity:Location) where the related + * quantity of items is being tracked after the adjustment. + * + * @var ?string $toLocationId + */ + #[JsonProperty('to_location_id')] + private ?string $toLocationId; /** * The Square-generated ID of the @@ -188,13 +197,50 @@ class InventoryAdjustment extends JsonSerializableType #[JsonProperty('adjustment_group')] private ?InventoryAdjustmentGroup $adjustmentGroup; + /** + * The total amount paid by the merchant to the supplying vendor for these units of the product. + * This field is only applicable for stock receive adjustments that introduce stock into the system (from_state is NONE or UNLINKED_RETURN). + * May be empty. + * This field will only accept writes if the merchant has an active subscription for either Retail Plus, Restaurants Plus, or Restaurants Premium. + * + * @var ?Money $costMoney + */ + #[JsonProperty('cost_money')] + private ?Money $costMoney; + + /** + * The Square-generated ID of the Vendor from which the merchant purchased this product. + * This field is only applicable for stock receive adjustments that introduce stock into the system (from_state is NONE or UNLINKED_RETURN). + * This field will only accept writes if the merchant has an active subscription for either Retail Plus, Restaurants Plus, or Restaurants Premium. + * + * @var ?string $vendorId + */ + #[JsonProperty('vendor_id')] + private ?string $vendorId; + + /** + * The Square-generated ID of the InventoryPhysicalCount (recount) that generated this adjustment, if applicable. + * The quantity of an adjustment generated by a physical count cannot be edited. + * + * @var ?string $physicalCountId + */ + #[JsonProperty('physical_count_id')] + private ?string $physicalCountId; + + /** + * @var ?InventoryAdjustmentReasonId $reasonId Identifies the reason for this inventory adjustment. + */ + #[JsonProperty('reason_id')] + private ?InventoryAdjustmentReasonId $reasonId; + /** * @param array{ * id?: ?string, * referenceId?: ?string, * fromState?: ?value-of, * toState?: ?value-of, - * locationId?: ?string, + * fromLocationId?: ?string, + * toLocationId?: ?string, * catalogObjectId?: ?string, * catalogObjectType?: ?string, * quantity?: ?string, @@ -209,6 +255,10 @@ class InventoryAdjustment extends JsonSerializableType * purchaseOrderId?: ?string, * goodsReceiptId?: ?string, * adjustmentGroup?: ?InventoryAdjustmentGroup, + * costMoney?: ?Money, + * vendorId?: ?string, + * physicalCountId?: ?string, + * reasonId?: ?InventoryAdjustmentReasonId, * } $values */ public function __construct( @@ -218,7 +268,8 @@ public function __construct( $this->referenceId = $values['referenceId'] ?? null; $this->fromState = $values['fromState'] ?? null; $this->toState = $values['toState'] ?? null; - $this->locationId = $values['locationId'] ?? null; + $this->fromLocationId = $values['fromLocationId'] ?? null; + $this->toLocationId = $values['toLocationId'] ?? null; $this->catalogObjectId = $values['catalogObjectId'] ?? null; $this->catalogObjectType = $values['catalogObjectType'] ?? null; $this->quantity = $values['quantity'] ?? null; @@ -233,6 +284,10 @@ public function __construct( $this->purchaseOrderId = $values['purchaseOrderId'] ?? null; $this->goodsReceiptId = $values['goodsReceiptId'] ?? null; $this->adjustmentGroup = $values['adjustmentGroup'] ?? null; + $this->costMoney = $values['costMoney'] ?? null; + $this->vendorId = $values['vendorId'] ?? null; + $this->physicalCountId = $values['physicalCountId'] ?? null; + $this->reasonId = $values['reasonId'] ?? null; } /** @@ -310,18 +365,36 @@ public function setToState(?string $value = null): self /** * @return ?string */ - public function getLocationId(): ?string + public function getFromLocationId(): ?string + { + return $this->fromLocationId; + } + + /** + * @param ?string $value + */ + public function setFromLocationId(?string $value = null): self + { + $this->fromLocationId = $value; + $this->_setField('fromLocationId'); + return $this; + } + + /** + * @return ?string + */ + public function getToLocationId(): ?string { - return $this->locationId; + return $this->toLocationId; } /** * @param ?string $value */ - public function setLocationId(?string $value = null): self + public function setToLocationId(?string $value = null): self { - $this->locationId = $value; - $this->_setField('locationId'); + $this->toLocationId = $value; + $this->_setField('toLocationId'); return $this; } @@ -577,6 +650,78 @@ public function setAdjustmentGroup(?InventoryAdjustmentGroup $value = null): sel return $this; } + /** + * @return ?Money + */ + public function getCostMoney(): ?Money + { + return $this->costMoney; + } + + /** + * @param ?Money $value + */ + public function setCostMoney(?Money $value = null): self + { + $this->costMoney = $value; + $this->_setField('costMoney'); + return $this; + } + + /** + * @return ?string + */ + public function getVendorId(): ?string + { + return $this->vendorId; + } + + /** + * @param ?string $value + */ + public function setVendorId(?string $value = null): self + { + $this->vendorId = $value; + $this->_setField('vendorId'); + return $this; + } + + /** + * @return ?string + */ + public function getPhysicalCountId(): ?string + { + return $this->physicalCountId; + } + + /** + * @param ?string $value + */ + public function setPhysicalCountId(?string $value = null): self + { + $this->physicalCountId = $value; + $this->_setField('physicalCountId'); + return $this; + } + + /** + * @return ?InventoryAdjustmentReasonId + */ + public function getReasonId(): ?InventoryAdjustmentReasonId + { + return $this->reasonId; + } + + /** + * @param ?InventoryAdjustmentReasonId $value + */ + public function setReasonId(?InventoryAdjustmentReasonId $value = null): self + { + $this->reasonId = $value; + $this->_setField('reasonId'); + return $this; + } + /** * @return string */ diff --git a/src/Types/InventoryAdjustmentReason.php b/src/Types/InventoryAdjustmentReason.php new file mode 100644 index 00000000..d871877d --- /dev/null +++ b/src/Types/InventoryAdjustmentReason.php @@ -0,0 +1,210 @@ + $direction + */ + #[JsonProperty('direction')] + private ?string $direction; + + /** + * An RFC 3339-formatted timestamp that indicates when the custom + * adjustment reason was created. This field is empty for standard + * adjustment reasons. + * + * @var ?string $createdAt + */ + #[JsonProperty('created_at')] + private ?string $createdAt; + + /** + * An RFC 3339-formatted timestamp that indicates when the custom + * adjustment reason was last updated. This field is empty for standard + * adjustment reasons. + * + * @var ?string $updatedAt + */ + #[JsonProperty('updated_at')] + private ?string $updatedAt; + + /** + * Indicates whether this custom inventory adjustment reason has been + * deleted. Deleted custom reasons can still be retrieved by ID, but are + * omitted from list responses unless deleted reasons are explicitly included. + * To restore a deleted custom reason, call + * [RestoreInventoryAdjustmentReason](api-endpoint:Inventory-RestoreInventoryAdjustmentReason). + * This field is always `false` for standard and system-generated adjustment + * reasons. + * + * @var ?bool $isDeleted + */ + #[JsonProperty('is_deleted')] + private ?bool $isDeleted; + + /** + * @param array{ + * id: InventoryAdjustmentReasonId, + * name?: ?string, + * direction?: ?value-of, + * createdAt?: ?string, + * updatedAt?: ?string, + * isDeleted?: ?bool, + * } $values + */ + public function __construct( + array $values, + ) { + $this->id = $values['id']; + $this->name = $values['name'] ?? null; + $this->direction = $values['direction'] ?? null; + $this->createdAt = $values['createdAt'] ?? null; + $this->updatedAt = $values['updatedAt'] ?? null; + $this->isDeleted = $values['isDeleted'] ?? null; + } + + /** + * @return InventoryAdjustmentReasonId + */ + public function getId(): InventoryAdjustmentReasonId + { + return $this->id; + } + + /** + * @param InventoryAdjustmentReasonId $value + */ + public function setId(InventoryAdjustmentReasonId $value): self + { + $this->id = $value; + $this->_setField('id'); + return $this; + } + + /** + * @return ?string + */ + public function getName(): ?string + { + return $this->name; + } + + /** + * @param ?string $value + */ + public function setName(?string $value = null): self + { + $this->name = $value; + $this->_setField('name'); + return $this; + } + + /** + * @return ?value-of + */ + public function getDirection(): ?string + { + return $this->direction; + } + + /** + * @param ?value-of $value + */ + public function setDirection(?string $value = null): self + { + $this->direction = $value; + $this->_setField('direction'); + return $this; + } + + /** + * @return ?string + */ + public function getCreatedAt(): ?string + { + return $this->createdAt; + } + + /** + * @param ?string $value + */ + public function setCreatedAt(?string $value = null): self + { + $this->createdAt = $value; + $this->_setField('createdAt'); + return $this; + } + + /** + * @return ?string + */ + public function getUpdatedAt(): ?string + { + return $this->updatedAt; + } + + /** + * @param ?string $value + */ + public function setUpdatedAt(?string $value = null): self + { + $this->updatedAt = $value; + $this->_setField('updatedAt'); + return $this; + } + + /** + * @return ?bool + */ + public function getIsDeleted(): ?bool + { + return $this->isDeleted; + } + + /** + * @param ?bool $value + */ + public function setIsDeleted(?bool $value = null): self + { + $this->isDeleted = $value; + $this->_setField('isDeleted'); + return $this; + } + + /** + * @return string + */ + public function __toString(): string + { + return $this->toJson(); + } +} diff --git a/src/Types/InventoryAdjustmentReasonDirection.php b/src/Types/InventoryAdjustmentReasonDirection.php new file mode 100644 index 00000000..396a5748 --- /dev/null +++ b/src/Types/InventoryAdjustmentReasonDirection.php @@ -0,0 +1,9 @@ + $type + */ + #[JsonProperty('type')] + private string $type; + + /** + * The Square-generated ID of the custom adjustment reason. This field + * is only set when `type` is `CUSTOM`. + * + * @var ?string $customReasonId + */ + #[JsonProperty('custom_reason_id')] + private ?string $customReasonId; + + /** + * @param array{ + * type: value-of, + * customReasonId?: ?string, + * } $values + */ + public function __construct( + array $values, + ) { + $this->type = $values['type']; + $this->customReasonId = $values['customReasonId'] ?? null; + } + + /** + * @return value-of + */ + public function getType(): string + { + return $this->type; + } + + /** + * @param value-of $value + */ + public function setType(string $value): self + { + $this->type = $value; + $this->_setField('type'); + return $this; + } + + /** + * @return ?string + */ + public function getCustomReasonId(): ?string + { + return $this->customReasonId; + } + + /** + * @param ?string $value + */ + public function setCustomReasonId(?string $value = null): self + { + $this->customReasonId = $value; + $this->_setField('customReasonId'); + return $this; + } + + /** + * @return string + */ + public function __toString(): string + { + return $this->toJson(); + } +} diff --git a/src/Types/InventoryAdjustmentReasonIdType.php b/src/Types/InventoryAdjustmentReasonIdType.php new file mode 100644 index 00000000..94356b0a --- /dev/null +++ b/src/Types/InventoryAdjustmentReasonIdType.php @@ -0,0 +1,23 @@ +, * physicalCount?: ?InventoryPhysicalCount, * adjustment?: ?InventoryAdjustment, - * transfer?: ?InventoryTransfer, * measurementUnit?: ?CatalogMeasurementUnit, * measurementUnitId?: ?string, * } $values @@ -80,7 +67,6 @@ public function __construct( $this->type = $values['type'] ?? null; $this->physicalCount = $values['physicalCount'] ?? null; $this->adjustment = $values['adjustment'] ?? null; - $this->transfer = $values['transfer'] ?? null; $this->measurementUnit = $values['measurementUnit'] ?? null; $this->measurementUnitId = $values['measurementUnitId'] ?? null; } @@ -139,24 +125,6 @@ public function setAdjustment(?InventoryAdjustment $value = null): self return $this; } - /** - * @return ?InventoryTransfer - */ - public function getTransfer(): ?InventoryTransfer - { - return $this->transfer; - } - - /** - * @param ?InventoryTransfer $value - */ - public function setTransfer(?InventoryTransfer $value = null): self - { - $this->transfer = $value; - $this->_setField('transfer'); - return $this; - } - /** * @return ?CatalogMeasurementUnit */ diff --git a/src/Types/InventoryChangeType.php b/src/Types/InventoryChangeType.php index 0e85c42f..84259497 100644 --- a/src/Types/InventoryChangeType.php +++ b/src/Types/InventoryChangeType.php @@ -6,5 +6,4 @@ enum InventoryChangeType: string { case PhysicalCount = "PHYSICAL_COUNT"; case Adjustment = "ADJUSTMENT"; - case Transfer = "TRANSFER"; } diff --git a/src/Types/InventoryCount.php b/src/Types/InventoryCount.php index f0720af9..95acb3c6 100644 --- a/src/Types/InventoryCount.php +++ b/src/Types/InventoryCount.php @@ -8,7 +8,8 @@ /** * Represents Square-estimated quantity of items in a particular state at a * particular seller location based on the known history of physical counts and - * inventory adjustments. + * inventory adjustments. The absence of an inventory count indicates that the + * catalog object hasn't interacted with the given inventory state at the given location. */ class InventoryCount extends JsonSerializableType { diff --git a/src/Types/InventoryPhysicalCount.php b/src/Types/InventoryPhysicalCount.php index a3269090..b99411eb 100644 --- a/src/Types/InventoryPhysicalCount.php +++ b/src/Types/InventoryPhysicalCount.php @@ -124,6 +124,16 @@ class InventoryPhysicalCount extends JsonSerializableType #[JsonProperty('created_at')] private ?string $createdAt; + /** + * The Square-generated ID of the InventoryAdjustment that was generated by this physical count in order to + * adjust the current stock count to reflect the re-counted quantity. + * This field may be empty if the merchant does not have an active subscription for either Retail Plus, Restaurants Plus, or Restaurants Premium. + * + * @var ?string $adjustmentId + */ + #[JsonProperty('adjustment_id')] + private ?string $adjustmentId; + /** * @param array{ * id?: ?string, @@ -138,6 +148,7 @@ class InventoryPhysicalCount extends JsonSerializableType * teamMemberId?: ?string, * occurredAt?: ?string, * createdAt?: ?string, + * adjustmentId?: ?string, * } $values */ public function __construct( @@ -155,6 +166,7 @@ public function __construct( $this->teamMemberId = $values['teamMemberId'] ?? null; $this->occurredAt = $values['occurredAt'] ?? null; $this->createdAt = $values['createdAt'] ?? null; + $this->adjustmentId = $values['adjustmentId'] ?? null; } /** @@ -373,6 +385,24 @@ public function setCreatedAt(?string $value = null): self return $this; } + /** + * @return ?string + */ + public function getAdjustmentId(): ?string + { + return $this->adjustmentId; + } + + /** + * @param ?string $value + */ + public function setAdjustmentId(?string $value = null): self + { + $this->adjustmentId = $value; + $this->_setField('adjustmentId'); + return $this; + } + /** * @return string */ diff --git a/src/Types/InventoryState.php b/src/Types/InventoryState.php index 96afe83f..38c945da 100644 --- a/src/Types/InventoryState.php +++ b/src/Types/InventoryState.php @@ -20,4 +20,5 @@ enum InventoryState: string case Decomposed = "DECOMPOSED"; case SupportedByNewerVersion = "SUPPORTED_BY_NEWER_VERSION"; case InTransit = "IN_TRANSIT"; + case Untracked = "UNTRACKED"; } diff --git a/src/Types/InventoryTransfer.php b/src/Types/InventoryTransfer.php deleted file mode 100644 index 6e9e9370..00000000 --- a/src/Types/InventoryTransfer.php +++ /dev/null @@ -1,412 +0,0 @@ - $state - */ - #[JsonProperty('state')] - private ?string $state; - - /** - * The Square-generated ID of the [Location](entity:Location) where the related - * quantity of items was tracked before the transfer. - * - * @var ?string $fromLocationId - */ - #[JsonProperty('from_location_id')] - private ?string $fromLocationId; - - /** - * The Square-generated ID of the [Location](entity:Location) where the related - * quantity of items was tracked after the transfer. - * - * @var ?string $toLocationId - */ - #[JsonProperty('to_location_id')] - private ?string $toLocationId; - - /** - * The Square-generated ID of the - * [CatalogObject](entity:CatalogObject) being tracked. - * - * @var ?string $catalogObjectId - */ - #[JsonProperty('catalog_object_id')] - private ?string $catalogObjectId; - - /** - * The [type](entity:CatalogObjectType) of the [CatalogObject](entity:CatalogObject) being tracked. - * - * The Inventory API supports setting and reading the `"catalog_object_type": "ITEM_VARIATION"` field value. - * In addition, it can also read the `"catalog_object_type": "ITEM"` field value that is set by the Square Restaurants app. - * - * @var ?string $catalogObjectType - */ - #[JsonProperty('catalog_object_type')] - private ?string $catalogObjectType; - - /** - * The number of items affected by the transfer as a decimal string. - * Can support up to 5 digits after the decimal point. - * - * @var ?string $quantity - */ - #[JsonProperty('quantity')] - private ?string $quantity; - - /** - * A client-generated RFC 3339-formatted timestamp that indicates when - * the transfer took place. For write actions, the `occurred_at` timestamp - * cannot be older than 24 hours or in the future relative to the time of the - * request. - * - * @var ?string $occurredAt - */ - #[JsonProperty('occurred_at')] - private ?string $occurredAt; - - /** - * An RFC 3339-formatted timestamp that indicates when Square - * received the transfer request. - * - * @var ?string $createdAt - */ - #[JsonProperty('created_at')] - private ?string $createdAt; - - /** - * Information about the application that initiated the - * inventory transfer. - * - * @var ?SourceApplication $source - */ - #[JsonProperty('source')] - private ?SourceApplication $source; - - /** - * The Square-generated ID of the [Employee](entity:Employee) responsible for the - * inventory transfer. - * - * @var ?string $employeeId - */ - #[JsonProperty('employee_id')] - private ?string $employeeId; - - /** - * The Square-generated ID of the [Team Member](entity:TeamMember) responsible for the - * inventory transfer. - * - * @var ?string $teamMemberId - */ - #[JsonProperty('team_member_id')] - private ?string $teamMemberId; - - /** - * @param array{ - * id?: ?string, - * referenceId?: ?string, - * state?: ?value-of, - * fromLocationId?: ?string, - * toLocationId?: ?string, - * catalogObjectId?: ?string, - * catalogObjectType?: ?string, - * quantity?: ?string, - * occurredAt?: ?string, - * createdAt?: ?string, - * source?: ?SourceApplication, - * employeeId?: ?string, - * teamMemberId?: ?string, - * } $values - */ - public function __construct( - array $values = [], - ) { - $this->id = $values['id'] ?? null; - $this->referenceId = $values['referenceId'] ?? null; - $this->state = $values['state'] ?? null; - $this->fromLocationId = $values['fromLocationId'] ?? null; - $this->toLocationId = $values['toLocationId'] ?? null; - $this->catalogObjectId = $values['catalogObjectId'] ?? null; - $this->catalogObjectType = $values['catalogObjectType'] ?? null; - $this->quantity = $values['quantity'] ?? null; - $this->occurredAt = $values['occurredAt'] ?? null; - $this->createdAt = $values['createdAt'] ?? null; - $this->source = $values['source'] ?? null; - $this->employeeId = $values['employeeId'] ?? null; - $this->teamMemberId = $values['teamMemberId'] ?? null; - } - - /** - * @return ?string - */ - public function getId(): ?string - { - return $this->id; - } - - /** - * @param ?string $value - */ - public function setId(?string $value = null): self - { - $this->id = $value; - $this->_setField('id'); - return $this; - } - - /** - * @return ?string - */ - public function getReferenceId(): ?string - { - return $this->referenceId; - } - - /** - * @param ?string $value - */ - public function setReferenceId(?string $value = null): self - { - $this->referenceId = $value; - $this->_setField('referenceId'); - return $this; - } - - /** - * @return ?value-of - */ - public function getState(): ?string - { - return $this->state; - } - - /** - * @param ?value-of $value - */ - public function setState(?string $value = null): self - { - $this->state = $value; - $this->_setField('state'); - return $this; - } - - /** - * @return ?string - */ - public function getFromLocationId(): ?string - { - return $this->fromLocationId; - } - - /** - * @param ?string $value - */ - public function setFromLocationId(?string $value = null): self - { - $this->fromLocationId = $value; - $this->_setField('fromLocationId'); - return $this; - } - - /** - * @return ?string - */ - public function getToLocationId(): ?string - { - return $this->toLocationId; - } - - /** - * @param ?string $value - */ - public function setToLocationId(?string $value = null): self - { - $this->toLocationId = $value; - $this->_setField('toLocationId'); - return $this; - } - - /** - * @return ?string - */ - public function getCatalogObjectId(): ?string - { - return $this->catalogObjectId; - } - - /** - * @param ?string $value - */ - public function setCatalogObjectId(?string $value = null): self - { - $this->catalogObjectId = $value; - $this->_setField('catalogObjectId'); - return $this; - } - - /** - * @return ?string - */ - public function getCatalogObjectType(): ?string - { - return $this->catalogObjectType; - } - - /** - * @param ?string $value - */ - public function setCatalogObjectType(?string $value = null): self - { - $this->catalogObjectType = $value; - $this->_setField('catalogObjectType'); - return $this; - } - - /** - * @return ?string - */ - public function getQuantity(): ?string - { - return $this->quantity; - } - - /** - * @param ?string $value - */ - public function setQuantity(?string $value = null): self - { - $this->quantity = $value; - $this->_setField('quantity'); - return $this; - } - - /** - * @return ?string - */ - public function getOccurredAt(): ?string - { - return $this->occurredAt; - } - - /** - * @param ?string $value - */ - public function setOccurredAt(?string $value = null): self - { - $this->occurredAt = $value; - $this->_setField('occurredAt'); - return $this; - } - - /** - * @return ?string - */ - public function getCreatedAt(): ?string - { - return $this->createdAt; - } - - /** - * @param ?string $value - */ - public function setCreatedAt(?string $value = null): self - { - $this->createdAt = $value; - $this->_setField('createdAt'); - return $this; - } - - /** - * @return ?SourceApplication - */ - public function getSource(): ?SourceApplication - { - return $this->source; - } - - /** - * @param ?SourceApplication $value - */ - public function setSource(?SourceApplication $value = null): self - { - $this->source = $value; - $this->_setField('source'); - return $this; - } - - /** - * @return ?string - */ - public function getEmployeeId(): ?string - { - return $this->employeeId; - } - - /** - * @param ?string $value - */ - public function setEmployeeId(?string $value = null): self - { - $this->employeeId = $value; - $this->_setField('employeeId'); - return $this; - } - - /** - * @return ?string - */ - public function getTeamMemberId(): ?string - { - return $this->teamMemberId; - } - - /** - * @param ?string $value - */ - public function setTeamMemberId(?string $value = null): self - { - $this->teamMemberId = $value; - $this->_setField('teamMemberId'); - return $this; - } - - /** - * @return string - */ - public function __toString(): string - { - return $this->toJson(); - } -} diff --git a/src/Types/ItemVariationLocationOverrides.php b/src/Types/ItemVariationLocationOverrides.php index 42dce4f5..d482ef6e 100644 --- a/src/Types/ItemVariationLocationOverrides.php +++ b/src/Types/ItemVariationLocationOverrides.php @@ -32,7 +32,11 @@ class ItemVariationLocationOverrides extends JsonSerializableType private ?string $pricingType; /** - * @var ?bool $trackInventory If `true`, inventory tracking is active for the `CatalogItemVariation` at this `Location`. + * Indicates whether inventory tracking is active for the `CatalogItemVariation` at this `Location`. + * When set, this value explicitly overrides the global `track_inventory` setting. When unset, the location + * should use the global value. If both global and location-level values are unset, inventory tracking is disabled. + * + * @var ?bool $trackInventory */ #[JsonProperty('track_inventory')] private ?bool $trackInventory; diff --git a/src/Types/ListInventoryAdjustmentReasonsResponse.php b/src/Types/ListInventoryAdjustmentReasonsResponse.php new file mode 100644 index 00000000..ab828e21 --- /dev/null +++ b/src/Types/ListInventoryAdjustmentReasonsResponse.php @@ -0,0 +1,85 @@ + $errors Errors encountered when the request fails. + */ + #[JsonProperty('errors'), ArrayType([Error::class])] + private ?array $errors; + + /** + * The standard, system-generated, and custom inventory adjustment + * reasons available to the seller. + * + * @var ?array $adjustmentReasons + */ + #[JsonProperty('adjustment_reasons'), ArrayType([InventoryAdjustmentReason::class])] + private ?array $adjustmentReasons; + + /** + * @param array{ + * errors?: ?array, + * adjustmentReasons?: ?array, + * } $values + */ + public function __construct( + array $values = [], + ) { + $this->errors = $values['errors'] ?? null; + $this->adjustmentReasons = $values['adjustmentReasons'] ?? null; + } + + /** + * @return ?array + */ + public function getErrors(): ?array + { + return $this->errors; + } + + /** + * @param ?array $value + */ + public function setErrors(?array $value = null): self + { + $this->errors = $value; + $this->_setField('errors'); + return $this; + } + + /** + * @return ?array + */ + public function getAdjustmentReasons(): ?array + { + return $this->adjustmentReasons; + } + + /** + * @param ?array $value + */ + public function setAdjustmentReasons(?array $value = null): self + { + $this->adjustmentReasons = $value; + $this->_setField('adjustmentReasons'); + return $this; + } + + /** + * @return string + */ + public function __toString(): string + { + return $this->toJson(); + } +} diff --git a/src/Types/LoyaltyEvent.php b/src/Types/LoyaltyEvent.php index 473c4bb3..76709af4 100644 --- a/src/Types/LoyaltyEvent.php +++ b/src/Types/LoyaltyEvent.php @@ -21,10 +21,10 @@ class LoyaltyEvent extends JsonSerializableType * The type of the loyalty event. * See [LoyaltyEventType](#type-loyaltyeventtype) for possible values * - * @var value-of $type + * @var ?value-of $type */ #[JsonProperty('type')] - private string $type; + private ?string $type; /** * @var ?string $createdAt The timestamp when the event was created, in RFC 3339 format. @@ -78,10 +78,10 @@ class LoyaltyEvent extends JsonSerializableType * Defines whether the event was generated by the Square Point of Sale. * See [LoyaltyEventSource](#type-loyaltyeventsource) for possible values * - * @var value-of $source + * @var ?value-of $source */ #[JsonProperty('source')] - private string $source; + private ?string $source; /** * @var ?LoyaltyEventExpirePoints $expirePoints Provides metadata when the event `type` is `EXPIRE_POINTS`. @@ -103,9 +103,8 @@ class LoyaltyEvent extends JsonSerializableType /** * @param array{ - * type: value-of, - * source: value-of, * id?: ?string, + * type?: ?value-of, * createdAt?: ?string, * accumulatePoints?: ?LoyaltyEventAccumulatePoints, * createReward?: ?LoyaltyEventCreateReward, @@ -114,16 +113,17 @@ class LoyaltyEvent extends JsonSerializableType * adjustPoints?: ?LoyaltyEventAdjustPoints, * loyaltyAccountId?: ?string, * locationId?: ?string, + * source?: ?value-of, * expirePoints?: ?LoyaltyEventExpirePoints, * otherEvent?: ?LoyaltyEventOther, * accumulatePromotionPoints?: ?LoyaltyEventAccumulatePromotionPoints, * } $values */ public function __construct( - array $values, + array $values = [], ) { $this->id = $values['id'] ?? null; - $this->type = $values['type']; + $this->type = $values['type'] ?? null; $this->createdAt = $values['createdAt'] ?? null; $this->accumulatePoints = $values['accumulatePoints'] ?? null; $this->createReward = $values['createReward'] ?? null; @@ -132,7 +132,7 @@ public function __construct( $this->adjustPoints = $values['adjustPoints'] ?? null; $this->loyaltyAccountId = $values['loyaltyAccountId'] ?? null; $this->locationId = $values['locationId'] ?? null; - $this->source = $values['source']; + $this->source = $values['source'] ?? null; $this->expirePoints = $values['expirePoints'] ?? null; $this->otherEvent = $values['otherEvent'] ?? null; $this->accumulatePromotionPoints = $values['accumulatePromotionPoints'] ?? null; @@ -157,17 +157,17 @@ public function setId(?string $value = null): self } /** - * @return value-of + * @return ?value-of */ - public function getType(): string + public function getType(): ?string { return $this->type; } /** - * @param value-of $value + * @param ?value-of $value */ - public function setType(string $value): self + public function setType(?string $value = null): self { $this->type = $value; $this->_setField('type'); @@ -319,17 +319,17 @@ public function setLocationId(?string $value = null): self } /** - * @return value-of + * @return ?value-of */ - public function getSource(): string + public function getSource(): ?string { return $this->source; } /** - * @param value-of $value + * @param ?value-of $value */ - public function setSource(string $value): self + public function setSource(?string $value = null): self { $this->source = $value; $this->_setField('source'); diff --git a/src/Types/Order.php b/src/Types/Order.php index 5e9fb41e..5730cf81 100644 --- a/src/Types/Order.php +++ b/src/Types/Order.php @@ -39,7 +39,19 @@ class Order extends JsonSerializableType private ?string $referenceId; /** - * @var ?OrderSource $source The origination details of the order. + * The latest source details of the order. + * + * This field reflects the most recent source that interacted with or modified the order, + * and may change during the order lifecycle. For example: + * - An order created via API (source.name = "MyPOS") paid with Square Terminal may have + * source updated to reflect the Terminal application (which uses REGISTER, like POS) + * - An order updated or completed by a different application may have source updated + * to reflect that application. + * + * To preserve the original source from order creation regardless of subsequent updates, + * use the `creation_source` field instead. + * + * @var ?OrderSource $source */ #[JsonProperty('source')] private ?OrderSource $source; diff --git a/src/Types/OrderLineItemModifier.php b/src/Types/OrderLineItemModifier.php index 3c1fabf8..1280c8fc 100644 --- a/src/Types/OrderLineItemModifier.php +++ b/src/Types/OrderLineItemModifier.php @@ -96,6 +96,12 @@ class OrderLineItemModifier extends JsonSerializableType #[JsonProperty('metadata'), ArrayType(['string' => new Union('string', 'null')])] private ?array $metadata; + /** + * @var ?string $parentModifierUid The `uid` of the parent modifier, if this modifier is nested under another modifier. + */ + #[JsonProperty('parent_modifier_uid')] + private ?string $parentModifierUid; + /** * @param array{ * uid?: ?string, @@ -106,6 +112,7 @@ class OrderLineItemModifier extends JsonSerializableType * basePriceMoney?: ?Money, * totalPriceMoney?: ?Money, * metadata?: ?array, + * parentModifierUid?: ?string, * } $values */ public function __construct( @@ -119,6 +126,7 @@ public function __construct( $this->basePriceMoney = $values['basePriceMoney'] ?? null; $this->totalPriceMoney = $values['totalPriceMoney'] ?? null; $this->metadata = $values['metadata'] ?? null; + $this->parentModifierUid = $values['parentModifierUid'] ?? null; } /** @@ -265,6 +273,24 @@ public function setMetadata(?array $value = null): self return $this; } + /** + * @return ?string + */ + public function getParentModifierUid(): ?string + { + return $this->parentModifierUid; + } + + /** + * @param ?string $value + */ + public function setParentModifierUid(?string $value = null): self + { + $this->parentModifierUid = $value; + $this->_setField('parentModifierUid'); + return $this; + } + /** * @return string */ diff --git a/src/Types/RestoreInventoryAdjustmentReasonResponse.php b/src/Types/RestoreInventoryAdjustmentReasonResponse.php new file mode 100644 index 00000000..9d1a7ee7 --- /dev/null +++ b/src/Types/RestoreInventoryAdjustmentReasonResponse.php @@ -0,0 +1,82 @@ + $errors Errors encountered when the request fails. + */ + #[JsonProperty('errors'), ArrayType([Error::class])] + private ?array $errors; + + /** + * @var ?InventoryAdjustmentReason $adjustmentReason The successfully restored inventory adjustment reason. + */ + #[JsonProperty('adjustment_reason')] + private ?InventoryAdjustmentReason $adjustmentReason; + + /** + * @param array{ + * errors?: ?array, + * adjustmentReason?: ?InventoryAdjustmentReason, + * } $values + */ + public function __construct( + array $values = [], + ) { + $this->errors = $values['errors'] ?? null; + $this->adjustmentReason = $values['adjustmentReason'] ?? null; + } + + /** + * @return ?array + */ + public function getErrors(): ?array + { + return $this->errors; + } + + /** + * @param ?array $value + */ + public function setErrors(?array $value = null): self + { + $this->errors = $value; + $this->_setField('errors'); + return $this; + } + + /** + * @return ?InventoryAdjustmentReason + */ + public function getAdjustmentReason(): ?InventoryAdjustmentReason + { + return $this->adjustmentReason; + } + + /** + * @param ?InventoryAdjustmentReason $value + */ + public function setAdjustmentReason(?InventoryAdjustmentReason $value = null): self + { + $this->adjustmentReason = $value; + $this->_setField('adjustmentReason'); + return $this; + } + + /** + * @return string + */ + public function __toString(): string + { + return $this->toJson(); + } +} diff --git a/src/Types/RetrieveInventoryAdjustmentReasonResponse.php b/src/Types/RetrieveInventoryAdjustmentReasonResponse.php new file mode 100644 index 00000000..3e0e4a8d --- /dev/null +++ b/src/Types/RetrieveInventoryAdjustmentReasonResponse.php @@ -0,0 +1,85 @@ + $errors Errors encountered when the request fails. + */ + #[JsonProperty('errors'), ArrayType([Error::class])] + private ?array $errors; + + /** + * The successfully retrieved inventory adjustment reason. Deleted custom + * reasons can be retrieved by ID and have `is_deleted` set to `true`. + * + * @var ?InventoryAdjustmentReason $adjustmentReason + */ + #[JsonProperty('adjustment_reason')] + private ?InventoryAdjustmentReason $adjustmentReason; + + /** + * @param array{ + * errors?: ?array, + * adjustmentReason?: ?InventoryAdjustmentReason, + * } $values + */ + public function __construct( + array $values = [], + ) { + $this->errors = $values['errors'] ?? null; + $this->adjustmentReason = $values['adjustmentReason'] ?? null; + } + + /** + * @return ?array + */ + public function getErrors(): ?array + { + return $this->errors; + } + + /** + * @param ?array $value + */ + public function setErrors(?array $value = null): self + { + $this->errors = $value; + $this->_setField('errors'); + return $this; + } + + /** + * @return ?InventoryAdjustmentReason + */ + public function getAdjustmentReason(): ?InventoryAdjustmentReason + { + return $this->adjustmentReason; + } + + /** + * @param ?InventoryAdjustmentReason $value + */ + public function setAdjustmentReason(?InventoryAdjustmentReason $value = null): self + { + $this->adjustmentReason = $value; + $this->_setField('adjustmentReason'); + return $this; + } + + /** + * @return string + */ + public function __toString(): string + { + return $this->toJson(); + } +} diff --git a/src/Types/UpdateInventoryAdjustmentReasonResponse.php b/src/Types/UpdateInventoryAdjustmentReasonResponse.php new file mode 100644 index 00000000..2f6eeba4 --- /dev/null +++ b/src/Types/UpdateInventoryAdjustmentReasonResponse.php @@ -0,0 +1,82 @@ + $errors Errors encountered when the request fails. + */ + #[JsonProperty('errors'), ArrayType([Error::class])] + private ?array $errors; + + /** + * @var ?InventoryAdjustmentReason $adjustmentReason The successfully updated inventory adjustment reason. + */ + #[JsonProperty('adjustment_reason')] + private ?InventoryAdjustmentReason $adjustmentReason; + + /** + * @param array{ + * errors?: ?array, + * adjustmentReason?: ?InventoryAdjustmentReason, + * } $values + */ + public function __construct( + array $values = [], + ) { + $this->errors = $values['errors'] ?? null; + $this->adjustmentReason = $values['adjustmentReason'] ?? null; + } + + /** + * @return ?array + */ + public function getErrors(): ?array + { + return $this->errors; + } + + /** + * @param ?array $value + */ + public function setErrors(?array $value = null): self + { + $this->errors = $value; + $this->_setField('errors'); + return $this; + } + + /** + * @return ?InventoryAdjustmentReason + */ + public function getAdjustmentReason(): ?InventoryAdjustmentReason + { + return $this->adjustmentReason; + } + + /** + * @param ?InventoryAdjustmentReason $value + */ + public function setAdjustmentReason(?InventoryAdjustmentReason $value = null): self + { + $this->adjustmentReason = $value; + $this->_setField('adjustmentReason'); + return $this; + } + + /** + * @return string + */ + public function __toString(): string + { + return $this->toJson(); + } +} diff --git a/src/Types/GetInventoryTransferResponse.php b/src/Types/UpdateInventoryAdjustmentResponse.php similarity index 62% rename from src/Types/GetInventoryTransferResponse.php rename to src/Types/UpdateInventoryAdjustmentResponse.php index 9450786e..e9215d11 100644 --- a/src/Types/GetInventoryTransferResponse.php +++ b/src/Types/UpdateInventoryAdjustmentResponse.php @@ -6,7 +6,7 @@ use Square\Core\Json\JsonProperty; use Square\Core\Types\ArrayType; -class GetInventoryTransferResponse extends JsonSerializableType +class UpdateInventoryAdjustmentResponse extends JsonSerializableType { /** * @var ?array $errors Any errors that occurred during the request. @@ -15,22 +15,22 @@ class GetInventoryTransferResponse extends JsonSerializableType private ?array $errors; /** - * @var ?InventoryTransfer $transfer The requested [InventoryTransfer](entity:InventoryTransfer). + * @var ?InventoryAdjustment $adjustment The newly updated adjustment. */ - #[JsonProperty('transfer')] - private ?InventoryTransfer $transfer; + #[JsonProperty('adjustment')] + private ?InventoryAdjustment $adjustment; /** * @param array{ * errors?: ?array, - * transfer?: ?InventoryTransfer, + * adjustment?: ?InventoryAdjustment, * } $values */ public function __construct( array $values = [], ) { $this->errors = $values['errors'] ?? null; - $this->transfer = $values['transfer'] ?? null; + $this->adjustment = $values['adjustment'] ?? null; } /** @@ -52,20 +52,20 @@ public function setErrors(?array $value = null): self } /** - * @return ?InventoryTransfer + * @return ?InventoryAdjustment */ - public function getTransfer(): ?InventoryTransfer + public function getAdjustment(): ?InventoryAdjustment { - return $this->transfer; + return $this->adjustment; } /** - * @param ?InventoryTransfer $value + * @param ?InventoryAdjustment $value */ - public function setTransfer(?InventoryTransfer $value = null): self + public function setAdjustment(?InventoryAdjustment $value = null): self { - $this->transfer = $value; - $this->_setField('transfer'); + $this->adjustment = $value; + $this->_setField('adjustment'); return $this; } diff --git a/tests/Integration/InventoryTest.php b/tests/Integration/InventoryTest.php index b61a4005..fce136c9 100644 --- a/tests/Integration/InventoryTest.php +++ b/tests/Integration/InventoryTest.php @@ -94,7 +94,8 @@ public static function setUpBeforeClass(): void $adjustment = new InventoryAdjustment([ 'fromState' => 'NONE', 'toState' => 'IN_STOCK', - 'locationId' => self::$locationId, + 'fromLocationId' => self::$locationId, + 'toLocationId' => self::$locationId, 'catalogObjectId' => self::$itemVariationId, 'quantity' => '100', 'occurredAt' => (new DateTimeImmutable())->sub(new DateInterval('PT8H'))->format(DateTimeInterface::ATOM), @@ -174,7 +175,8 @@ public function testBatchChangeInventory(): void $adjustment = new InventoryAdjustment([ 'fromState' => 'NONE', 'toState' => 'IN_STOCK', - 'locationId' => self::$locationId, + 'fromLocationId' => self::$locationId, + 'toLocationId' => self::$locationId, 'catalogObjectId' => self::$itemVariationId, 'quantity' => '50', // Different quantity than setup 'occurredAt' => (new DateTimeImmutable())->format(DateTimeInterface::ATOM), @@ -281,7 +283,8 @@ public function testRetrieveInventoryAdjustment(): void $adjustment = new InventoryAdjustment([ 'fromState' => 'NONE', 'toState' => 'IN_STOCK', - 'locationId' => self::$locationId, + 'fromLocationId' => self::$locationId, + 'toLocationId' => self::$locationId, 'catalogObjectId' => self::$itemVariationId, 'quantity' => '10', 'occurredAt' => (new DateTimeImmutable())->format(DateTimeInterface::ATOM),