Update POS cart api docs to reflect discount per unit allocation (#4231)

### Background

Resolves shop/issues-retail#26385

Update documentation for discount allocation change from ACROSS to EACH starting in API version 2026-04.

### Solution

Update docs and provide example

### 🎩

- Ran `yarn docs:point-of-sale 2026-04-rc` in this repo.
- Ran this to copy over the generated files (temporary command while the migration is finalized):

```
cp -r /Users/janezhu/src/github.com/Shopify/ui-extensions/packages/ui-extensions/docs/surfaces/point-of-sale/generated/pos_ui_extensions/2026-04-rc \
    /Users/janezhu/world/trees/root/src/areas/platforms/shopify-dev/db/data/docs/templated_apis/pos_ui_extensions/
```

- In `shopify-dev` repo (now in the monorepo), run `dev server` 
- Go to your local https://shopify-dev.shop.dev/docs/api/pos-ui-extensions/2026-04-rc/target-apis/contextual-apis/cart-api to see the updated docs:

![Screenshot 2026-03-26 at 3.01.12 PM.png](https://app.graphite.com/user-attachments/assets/2d595f68-36f8-4c56-aac4-30d85a23255b.png)

![Screenshot 2026-03-26 at 3.01.18 PM.png](https://app.graphite.com/user-attachments/assets/fad72ad5-d3db-4d88-89c4-a22cdd1675f8.png)





### Checklist

- [x] I have 🎩'd these changes
- [x] I have updated relevant documentation

Author: janezhu918

packages/ui-extensions/src/surfaces/point-of-sale/api/cart-api/cart-api.ts

@@ -158,12 +158,12 @@ export interface CartApiContent {
   removeLineItemProperties(uuid: string, keys: string[]): Promise<void>;
 
   /**
-   * Apply a discount to a specific line item using its `UUID`. Specify the discount type (`'Percentage'` or `'FixedAmount'`), title, and amount value with improved discount allocation tracking.
+   * Apply a discount to a specific line item using its `UUID`. Specify the discount type (`'Percentage'` or `'FixedAmount'`), title, and amount value with improved discount allocation tracking. For `FixedAmount` discounts, this is the per-unit amount. For example, passing `'5.00'` on a line item with quantity 2 results in $10.00 total discount.
    *
    * @param uuid the uuid of the line item that should receive a discount
    * @param type the type of discount applied (example: 'Percentage')
    * @param title the title attributed with the discount
-   * @param amount the percentage or fixed monetary amount deducted with the discout
+   * @param amount the percentage or fixed monetary amount deducted with the discount
    */
   setLineItemDiscount(
     uuid: string,
@@ -173,9 +173,9 @@ export interface CartApiContent {
   ): Promise<void>;
 
   /**
-   * Apply discounts to multiple line items simultaneously. Each input specifies the line item `UUID` and discount details for efficient bulk discount operations with enhanced validation and allocation tracking.
+   * Apply discounts to multiple line items simultaneously. Each input specifies the line item `UUID` and discount details for efficient bulk discount operations with enhanced validation and allocation tracking. For `FixedAmount` discounts, the amount is applied per unit.
    *
-   * @param lineItemDiscounts a map of discounts to add. They key is the uuid of the line item you want to add the discount to. The value is the discount input.
+   * @param lineItemDiscounts a map of discounts to add. The key is the uuid of the line item you want to add the discount to. The value is the discount input.
    */
   bulkSetLineItemDiscounts(
     lineItemDiscounts: SetLineItemDiscountInput[],