[Woo POS] [Receipts] Set order metadata with the formatted change due amount string when a cash payment is made #15559

jaclync · 2025-04-28T07:15:35Z

Just one reviewer is required.

✅ ⚠️ for author: potential merge conflicts with #15557.

Description

This pull request sends the change amount from each cash payment in POS in the order's metadata _cash_change_amount field. The most important changes involve adding functionality for encoding and passing the cash payment change due amount, updating relevant protocols and controllers, and adding comprehensive test coverage. There was a small refactoring to replace OrderAction.updateOrder in PointOfSaleOrderController with a new POSOrderServiceProtocol.markOrderAsCompletedWithCashPayment, so that we don't have to change many of the existing OrderAction.updateOrder use cases for the new parameter.

POS Cash Payment Enhancements:

Added a new optional parameter cashPaymentChangeDueAmount to the updateOrder and updatePOSOrder methods in OrdersRemote to encode and pass cash payment change amounts.
Updated POSOrdersRemoteProtocol to include the cashPaymentChangeDueAmount parameter in the updatePOSOrder method.
Updated PointOfSaleOrderControllerProtocol and its implementations to handle the changeDueAmount parameter when collecting cash payments. The core order update logic was moved to POSOrderServiceProtocol.markOrderAsCompletedWithCashPayment so that order update actions can call the async/await OrdersRemote.updatePOSOrder with the cash payment change due amount parameter there.

UI and View Model Updates:

Modified PointOfSaleCollectCashView to calculate and pass the change due amount using a helper method.
Enhanced CollectCashViewHelper with methods to compute and format the change due amount.

Test Coverage:

Added unit tests in OrdersRemoteTests to verify encoding of cash payment change amounts and ensure no metadata is included when the parameter is absent.
Updated PointOfSaleOrderControllerTests to validate the behavior of collectCashPayment with and without a change due amount, and to ensure proper error handling and analytics tracking.
Added unit tests in POSOrderServiceTests for the new function markOrderAsCompletedWithCashPayment with the core order update logic with change due amount.

Steps to reproduce

No change due amount

Switch to a store eligible for POS and has at least one eligible product, if needed
Go to Menu tab > Point of Sale
Add product(s) to cart and check out
Tap Cash payment and enter the exact order amount, then mark payment as complete --> should hear a cha-ching
In an API testing tool (I personally used Postman), check the API response of the newly completed order --> the meta_data value should have an entry with key _cash_change_amount with the zero formatted change due amount as its value. In the response, payment_method should be cod and payment_method_title should be the localized version of "Pay in Person", just like before

Non-zero change due amount

Tap to create a new order in POS
Add product(s) to cart and check out
Tap Cash payment and enter a higher amount than the order amount, note the change due amount, then mark payment as complete --> should hear a cha-ching
In an API testing tool (I personally used Postman), check the API response of the newly completed order --> the meta_data value should have an entry with key _cash_change_amount with the formatted change due amount as its value. The amount string should be formatted with the store currency settings but does not include the currency symbol. In the response, payment_method should be cod and payment_method_title should be the localized version of "Pay in Person", just like before

Screenshots

Example request body:

{
  "payment_method_title" : "Pay in Person",
  "payment_method" : "cod",
  "status" : "completed",
  "meta_data" : [
    {
      "id" : 0,
      "key" : "_cash_change_amount",
      "value" : "5"
    }
  ]
}

I have considered if this change warrants user-facing release notes and have added them to RELEASE-NOTES.txt if necessary.

Reviewer (or Author, in the case of optional code reviews):

Please make sure these conditions are met before approving the PR, or request changes if the PR needs improvement:

The PR is small and has a clear, single focus, or a valid explanation is provided in the description. If needed, please request to split it into smaller PRs.
Ensure Adequate Unit Test Coverage: The changes are reasonably covered by unit tests or an explanation is provided in the PR description.
Manual Testing: The author listed all the tests they ran, including smoke tests when needed (e.g., for refactorings). The reviewer confirmed that the PR works as expected on all devices (phone/tablet) and no regressions are added.

…`updateOrder` and `updatePOSOrder`.

…tOfSaleOrderController` to `POSOrderService` to avoid having to update `OrderAction.updateOrder` that implies a lot more unnecessary changes from existing usage.

…ore logic is moved to the service.

wpmobilebot · 2025-04-28T07:25:03Z

📲 You can test the changes from this Pull Request in WooCommerce iOS Prototype by scanning the QR code below to install the corresponding build.

	App Name	WooCommerce iOS Prototype
	Build Number	`29790`
	Version	`PR #15559`
	Bundle ID	`com.automattic.alpha.woocommerce`
	Commit	`04e6921`
	Installation URL	2m9ur1pimqmkg

Automatticians: You can use our internal self-serve MC tool to give yourself access to those builds if needed.

joshheald

Works well; a question inline about whether we should send the change even when it's 0

joshheald · 2025-04-28T13:14:45Z

WooCommerce/Classes/POS/Controllers/PointOfSaleOrderController.swift

-        let fieldsToUpdate: [OrderUpdateField] = [
-            .status,
-            .paymentMethodID,
-            .paymentMethodTitle]
-        let updatedOrder = order.copy(status: .completed,
-                                      paymentMethodID: PaymentGateway.Constants.cashOnDeliveryGatewayID,
-                                      paymentMethodTitle: Localization.cashPaymentMethodTitle)
-
-        let _ = try await withCheckedThrowingContinuation { continuation in
-            let action = OrderAction.updateOrder(siteID: siteID,
-                                                 order: updatedOrder,
-                                                 giftCard: nil,
-                                                 fields: fieldsToUpdate,
-                                                 onCompletion: { [weak self] result in
-                guard let self = self else { return }
-                switch result {
-                case .success:
-                    self.celebrate()
-                case .failure:
-                    analytics.track(.pointOfSaleCashPaymentFailed)
-                }
-                continuation.resume(with: result)
-            })
-            stores.dispatch(action)


Nice tidying up, this should definitely be in the service

joshheald · 2025-04-28T13:16:16Z

WooCommerce/Classes/POS/Models/PointOfSaleAggregateModel.swift

+    func collectCashPayment(changeDueAmount: String?) async throws {
+        try await orderController.collectCashPayment(changeDueAmount: changeDueAmount)


Why make this optional? There's always a change amount for cash payments, it's just that sometimes it's $0. There's potentially value in specifically knowing that the app calculated the change as zero... are there other reasons not to send it in that case?

Good question, it's optional not only for 0 change due amount but also for unexpected scenarios like when it cannot parse the currency and input text:

woocommerce-ios/WooCommerce/Classes/POS/ViewHelpers/CollectCashViewHelper.swift

Lines 24 to 25 in 4db63d3

guard let orderDecimal = parseCurrency(orderTotal),

let inputDecimal = parseCurrency(textFieldAmountInput) else {

I agree that 0 change due amount can be shown on the receipt as well. The zero case was skipped before just because it was following the logic where the UI doesn't show a message for 0 change due amount. From Perplexity:

If the change due is zero, many POS systems will omit displaying or printing the change due amount, often configurable by the user or store settings.

I also checked a few receipt examples and a bunch of them do show 0 change due amount. I believe the best UX is for the app to set the order metadata for all >= 0 change due amount, and the backend can decide whether to show it or not (we will show it by default for Basic POS) like based on a POS configuration in the future.

Updated in bcf0589 and ready for another check!

Looks good to me 👍 thanks!

Another thought (sorry, should have come up with this yesterday):

Why send the formatted value? The API doesn't send us formatted values, it sends a currency code and an unformatted string for the amount. Perhaps we should reply in the same way?

We don't really support multicurrency well, but we shouldn't make it harder for ourselves – relying on the currency set on the order is reasonable. We can throw an error in the app if someone tries to give change in a different currency to the order – I don't think that'll even come up yet though.

Great thought, better late than never! I was sending the formatted value just so that the backend can just display it right away. I just checked the order API response including other metadata like from WooPayments, the amounts are not formatted. Let me try making it work in core first, then I will update the PR.

Removed the currency symbol in 7111d68. Can be tested with woocommerce/woocommerce#57734 that displays the formatted change due amount.

…ue-amount-for-pos-cash-payment

…OS cash payment.

…ue-amount-for-pos-cash-payment

wpmobilebot · 2025-05-02T03:34:43Z

Version 22.3 has now entered code-freeze, so the milestone of this PR has been updated to 22.4.

…rency symbol.

…ue-amount-for-pos-cash-payment

jaclync · 2025-05-06T07:15:53Z

@joshheald I updated the PR to send the cash payment change due amount without the currency symbol, if you'd like to take another look. This can be tested with woocommerce/woocommerce#57734 that displays the formatted change due amount with the order currency symbol.

…ue-amount-for-pos-cash-payment

jaclync · 2025-05-13T01:50:46Z

Merging as the core work woocommerce/woocommerce#57734 was merged.

dangermattic · 2025-05-13T05:31:48Z

	1 Warning
⚠️	View files have been modified, but no screenshot or video is included in the pull request. Consider adding some for clarity.

Generated by 🚫 Danger

jaclync added 4 commits April 28, 2025 15:15

OrdersRemote: add cashPaymentChangeDueAmount optional parameter to …

990f73b

…`updateOrder` and `updatePOSOrder`.

Move core logic of marking order as paid with cash payment from `Poin…

2ac52b3

…tOfSaleOrderController` to `POSOrderService` to avoid having to update `OrderAction.updateOrder` that implies a lot more unnecessary changes from existing usage.

OrdersRemote: add test cases for change due amount.

1252feb

Add/update POS order service and controller unit tests now that the c…

28342f1

…ore logic is moved to the service.

jaclync marked this pull request as ready for review April 28, 2025 08:27

jaclync changed the title ~~Feat/woomob 378 set formatted cash change due amount for pos cash payment~~ [Woo POS] [Receipts] Set order metadata with the formatted change due amount string when a cash payment is made Apr 28, 2025

jaclync added type: task An internally driven task. feature: point of sale labels Apr 28, 2025

jaclync added this to the 22.3 milestone Apr 28, 2025

jaclync requested review from joshheald, iamgabrielma and staskus April 28, 2025 08:28

joshheald self-assigned this Apr 28, 2025

joshheald approved these changes Apr 28, 2025

View reviewed changes

jaclync added 3 commits April 29, 2025 08:34

Merge branch 'trunk' into feat/WOOMOB-378-set-formatted-cash-change-d…

c8afd88

…ue-amount-for-pos-cash-payment

Include zero change due amount case for setting order metadata from P…

bcf0589

…OS cash payment.

Merge branch 'trunk' into feat/WOOMOB-378-set-formatted-cash-change-d…

4a7a5f0

…ue-amount-for-pos-cash-payment

wpmobilebot modified the milestones: 22.3, 22.4 May 2, 2025

jaclync added 2 commits May 6, 2025 15:10

Update cash payment change due amount metadata to not include the cur…

7111d68

…rency symbol.

Merge branch 'trunk' into feat/WOOMOB-378-set-formatted-cash-change-d…

fe5bdb5

…ue-amount-for-pos-cash-payment

Merge branch 'trunk' into feat/WOOMOB-378-set-formatted-cash-change-d…

04e6921

…ue-amount-for-pos-cash-payment

jaclync enabled auto-merge May 13, 2025 01:27

jaclync merged commit 4940372 into trunk May 13, 2025
13 checks passed

jaclync deleted the feat/WOOMOB-378-set-formatted-cash-change-due-amount-for-pos-cash-payment branch May 13, 2025 01:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[Woo POS] [Receipts] Set order metadata with the formatted change due amount string when a cash payment is made #15559

[Woo POS] [Receipts] Set order metadata with the formatted change due amount string when a cash payment is made #15559

Uh oh!

jaclync commented Apr 28, 2025 •

edited

Loading

Uh oh!

wpmobilebot commented Apr 28, 2025 •

edited

Loading

Uh oh!

joshheald left a comment

Uh oh!

joshheald Apr 28, 2025

Uh oh!

joshheald Apr 28, 2025

Uh oh!

jaclync Apr 29, 2025

Uh oh!

joshheald Apr 29, 2025

Uh oh!

jaclync Apr 30, 2025

Uh oh!

jaclync May 6, 2025

Uh oh!

wpmobilebot commented May 2, 2025

Uh oh!

jaclync commented May 6, 2025

Uh oh!

Uh oh!

jaclync commented May 13, 2025

Uh oh!

dangermattic commented May 13, 2025

Uh oh!

Uh oh!

		func collectCashPayment(changeDueAmount: String?) async throws {
		try await orderController.collectCashPayment(changeDueAmount: changeDueAmount)

	guard let orderDecimal = parseCurrency(orderTotal),
	let inputDecimal = parseCurrency(textFieldAmountInput) else {

[Woo POS] [Receipts] Set order metadata with the formatted change due amount string when a cash payment is made #15559

[Woo POS] [Receipts] Set order metadata with the formatted change due amount string when a cash payment is made #15559

Uh oh!

Conversation

jaclync commented Apr 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

POS Cash Payment Enhancements:

UI and View Model Updates:

Test Coverage:

Steps to reproduce

No change due amount

Non-zero change due amount

Screenshots

Reviewer (or Author, in the case of optional code reviews):

Uh oh!

wpmobilebot commented Apr 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joshheald left a comment

Choose a reason for hiding this comment

Uh oh!

joshheald Apr 28, 2025

Choose a reason for hiding this comment

Uh oh!

joshheald Apr 28, 2025

Choose a reason for hiding this comment

Uh oh!

jaclync Apr 29, 2025

Choose a reason for hiding this comment

Uh oh!

joshheald Apr 29, 2025

Choose a reason for hiding this comment

Uh oh!

jaclync Apr 30, 2025

Choose a reason for hiding this comment

Uh oh!

jaclync May 6, 2025

Choose a reason for hiding this comment

Uh oh!

wpmobilebot commented May 2, 2025

Uh oh!

jaclync commented May 6, 2025

Uh oh!

Uh oh!

jaclync commented May 13, 2025

Uh oh!

dangermattic commented May 13, 2025

Uh oh!

Uh oh!

jaclync commented Apr 28, 2025 •

edited

Loading

wpmobilebot commented Apr 28, 2025 •

edited

Loading