Skip to content

Held Carts

Hyvä POS is on the App Store

The free app is out for iPhone, iPad and Mac: install it from the App Store, connect your Magento store and sell. PRO, the Magento module with a license per terminal, follows shortly. News and pricing are at hyva.io/pos.

Method Route Purpose
GET /V1/pos/held-carts/location/:locationId The location's shared parked carts
POST /V1/pos/held-carts Park a cart server-side
POST /V1/pos/held-carts/:heldCartId/recall Claim a parked cart for this register
DELETE /V1/pos/held-carts/:heldCartId Discard a parked cart
DELETE /V1/pos/held-carts/uuid/:cartUuid Discard by cart UUID (when the numeric id is unknown, e.g. offline-created carts)

All routes require the Hyva_Pos::locations ACL resource. A held cart is a parked in-progress sale: the cashier holds it on one register, any register at the same location can recall it and finish the sale. The server stores the full cart as an opaque JSON blob (cart_data) plus a summary row (customer name, item count, grand total) so registers can render the parked-carts list without deserializing every cart.

Sharing and the Enforcement Flag

Cross-terminal sharing is controlled by the Magento configuration flag Share Held Carts (hyva_pos/general/share_held_carts, Stores → Configuration → Hyvä POS). The flag is delivered to the app as share_held_carts in GET /V1/pos/config. When enabled, every terminal at a location syncs its parked carts through these routes; when disabled, holds stay local to the device.

The companion lock Lock Held Cart Sharing (hyva_pos_lock/enforcement/held_carts) is delivered as enforcement.held_carts in the same config payload. When set, the Magento value is enforced on every terminal and the corresponding POS setting becomes read-only on the device: a terminal cannot opt out of (or into) sharing locally.

List Held Carts for a Location

GET /V1/pos/held-carts/location/:locationId: all parked carts at a location, newest first. The POS polls this to populate the parked-carts sheet on every register. Optional query parameter pageSize (default 100).

Response: an array of held-cart rows:

[
  {
    "held_cart_id": 41,
    "location_id": 3,
    "staff_id": 12,
    "staff_name": "Anna",
    "terminal_id": null,
    "cart_uuid": "8F5E2C7A-1B0D-4A6B-9E1F-3C2D4E5F6A7B",
    "cart_data": "{\"id\":\"8F5E2C7A-...\",\"items\":[...]}",
    "customer_name": "Jane Doe",
    "item_count": 3,
    "grand_total": 129.85,
    "currency_code": "EUR",
    "hold_comment": "Waiting on a size check",
    "recalled_by_staff_id": null,
    "recalled_at": null,
    "created_at": "2026-08-12 10:41:03",
    "updated_at": "2026-08-12 10:41:03"
  }
]

cart_data is the serialized cart as the app produced it. Treat it as a blob: its schema belongs to the POS app and changes between app versions. A row with a non-null recalled_by_staff_id has already been claimed by another register.

Park a Cart

POST /V1/pos/held-carts: saves a cart server-side. The POS calls this when the cashier taps Hold on an active sale.

Request: the row is wrapped in a heldCart key. location_id, cart_uuid, cart_data, customer_name, item_count, grand_total, and currency_code are what the app always sends; staff_id, staff_name, terminal_id, and hold_comment are optional:

{
  "heldCart": {
    "location_id": 3,
    "cart_uuid": "8F5E2C7A-1B0D-4A6B-9E1F-3C2D4E5F6A7B",
    "cart_data": "{\"id\":\"8F5E2C7A-...\",\"items\":[...]}",
    "customer_name": "Jane Doe",
    "item_count": 3,
    "grand_total": 129.85,
    "currency_code": "EUR",
    "staff_id": 12,
    "staff_name": "Anna",
    "hold_comment": "Waiting on a size check"
  }
}

Response: the saved row in the shape shown above, now carrying the server-assigned held_cart_id and timestamps. cart_uuid is the client-generated identity of the cart; re-posting the same UUID updates rather than duplicates. Holding a recalled cart again (the same cart_uuid) clears the recall and takes the incoming location_id, so the cart is listed again.

Errors: 400 (CouldNotSaveException) when the row cannot be persisted.

Recall a Held Cart

POST /V1/pos/held-carts/:heldCartId/recall: claims a parked cart for the recalling register. The claim is atomic: the server sets recalled_by_staff_id and recalled_at in one statement, so two registers recalling the same cart at the same moment cannot both succeed.

Request:

{
  "staffId": 12
}

Response: the full held-cart row including cart_data, which the recalling register deserializes back into an active sale. The route runs Hyva\Pos\Api\HeldCartRecallInterface::execute, and every recall is written to the audit log with the staff member and the location. A plugin on the deprecated HeldCartRepositoryInterface::recall no longer runs for REST recalls; the method stays and delegates to the new service.

Errors: 400 with Cart was already recalled by another terminal. when the cart was already recalled by another register, and for an unknown id; surface this as "another register took this sale", not as a technical failure.

Discard a Held Cart

DELETE /V1/pos/held-carts/:heldCartId: deletes by server id. The POS calls this after a recalled cart completes checkout, and when a cashier explicitly discards a parked sale.

DELETE /V1/pos/held-carts/uuid/:cartUuid: deletes by the client-generated cart UUID. Used when the register never learned the server id, typically a cart parked while offline and synced later.

Response: true on success. Errors: 400 (CouldNotDeleteException) when the delete fails.