checkout:start
On this page
checkout:start starts checkout from a cart, performing the same validation the cart Pay button uses. Given an order instead, it takes a balance payment or captures a refund on that existing order. It can be configured on a POS action item or called from custom JavaScript via scAction.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
order_sc_id |
String | No | SC ID of an existing order to start checkout for. Takes precedence over cart_sc_id. See Start checkout for an existing order. |
cart_sc_id |
String | No | SC ID of the cart to start checkout from. If omitted, the active cart is used. If provided and different from the active cart, that cart is resumed first. |
Behavior
Without order_sc_id, the action works from a cart:
- If
cart_sc_idrefers to a cart other than the active one, the action resumes that cart first (using the same linkage safety check ascart:resume). If no such cart exists, the alert “Cart not found.” is shown. - The cart is validated using the same rules the Pay button uses. If any check fails, an alert modal explains the reason and the action stops.
- A checkout session is started for the cart.
- If the cart has a non-zero amount to pay (the common case), the user is taken to the checkout payment screen.
- If the cart total is zero (for example a fully-deposited cart or a pure refund), the order is created immediately and the user is navigated to the order record. For refund carts, the matching credit payments are created too.
If cart_sc_id refers to a cart that is already linked to an order, the existing “order connected” modal is shown instead of starting checkout, matching the behavior of cart:resume.
Validation rules
The action shows an alert and stops if any of the following conditions are detected:
| Reason | Alert message |
|---|---|
empty_cart |
Unable to start checkout with an empty cart |
syncing |
Cart is still syncing. Please wait and try again. |
pending_items |
Some items are still being added. Please wait and try again. |
fulfillment_save_failed |
A fulfillment change didn’t save. The cart has been refreshed: check its fulfillments and re-enter any that are missing. |
fulfillments_changed |
This cart was updated elsewhere. The cart has been refreshed: check its fulfillments before continuing. |
expired_items |
A rental hold has expired. Review the cart before proceeding. |
fulfillment_needs_attention |
Delivery details have changed. Please confirm them before continuing. |
customer_required_subscription |
A customer is required to check out subscription items. |
customer_required_save_card |
A customer is required to check out items that save a card for later billing. |
customer_required_serial_item |
A customer is required to check out items with serial numbers. |
customer_required_delivery |
A customer is required to check out a delivery or non-takeaway fulfillment. |
customer_required_rental |
A customer is required to check out rental items. |
customer_required_voucher |
A customer is required for vouchers that auto-generate a code or PIN. |
customer_required |
A customer is required for this order. |
serial_numbers_missing |
Serial numbers are missing for one or more items. |
invalid_discount |
Cart discount exceeds the maximum allowed for the current items. |
offline_save_refused |
This sale cannot be saved while offline. Reconnect and try again. |
offline_save_refused applies only to a zero-total cart, where the order is created straight away and the register refuses to save it offline.
Start checkout for an existing order
With order_sc_id, the action starts checkout for that order instead of a cart, the same way the Make payment and Give refund actions on an order record do:
- The order is loaded from the register. If it isn’t there, the alert “Order not found.” is shown.
- An open order is refused, because the balance of an open order is taken by resuming the order’s cart with
order:resume. - If the customer has paid more than the order total, a refund capture starts. The register must be online, and it fetches a fresh copy of the order first.
- If the order is
INCOMPLETEwith items still to pay for, an additional payment starts. - Otherwise the action stops, because there is nothing to settle.
Both payment and refund open the checkout payment screen, which picks the form from the order totals.
| Reason | Alert message |
|---|---|
open_order |
This order is still open. Resume it to take payment. |
no_checkout_state |
This order has no payment or refund to process. |
refund_offline |
Can’t start a refund while offline. |
refund_fetch_failed |
Couldn’t load this order. Please try again. |
To refund a completed sale that is not overpaid, use checkout:refund, described in the POS actions reference.
Returned context
When checkout starts successfully, the action returns context available to the next action in a chain or to Liquid templates:
| Field | Type | When |
|---|---|---|
cart_sc_id |
String | When started from a cart (the active cart at completion) |
order_sc_id |
String | When started for an existing order |
order_id |
String | The existing order’s ID when started with order_sc_id, or the new order’s ID when a zero-total cart created one immediately |
Usage
Action item configuration
Set the Action field on a s_c__Pos_Action_Item__c record:
checkout:start
To target a specific cart:
checkout:start
with Params set to:
cart_sc_id={{ record.id }}
To take payment on an existing order from an order layout, set Params to:
order_sc_id={{ record.id }}
Liquid/HTML template
```html
```
```html
```
JavaScript
```javascript
scAction(‘checkout:start’) scAction(‘checkout:start’, { cart_sc_id: ‘abc-123’ }) scAction(‘checkout:start’, { order_sc_id: ‘def-456’ }) ```
With success/error handling:
```javascript
scAction( ‘checkout:start’, {}, { onSuccess: () => console.log(‘Checkout started’), onError: (error) => console.error(‘Could not start checkout:’, error), } ) ```
Was this article helpful?
Thanks for your feedback! It helps us improve our docs.