Cart API
The Cart API allows the UI Extension to interact with the POS cart contents including cart discounts, line items and customer. This API includes numerous functions to add and remove contents to the cart, as well as a subscribable object which allows the UI Extension to receive Cart updates.
Receiving cart updates
Anchor link to section titled "Receiving cart updates"
| Name | Type | Description | Options |
|---|---|---|---|
| newCart | Cart |
Cart object |
| Name | Type | Description |
|---|---|---|
| subtotal | string |
Total pretax amount. |
| taxTotal | string |
Appled taxes total. |
| grandTotal | string |
Total cart amount including taxes. |
| note | string? |
Cart note. |
| cartDiscount? | Discount? |
Cart discount. |
| cartDiscounts | Discount[]? |
Array of all cart and line item discounts. |
| customer? | Customer? |
Customer information if added to cart. |
| lineItems | LineItem[] |
Line items array. |
| properties | Record |
Custom key to value object to attribute to cart. |
| Name | Type | Description |
|---|---|---|
| amount | number |
Percentage or fixed monetary amount to be deducted. |
| discountDescription | string? |
Discount description. |
| type? | string? |
'Percentage' or 'Fixed' or 'Code'. |
| Name | Type | Description |
|---|---|---|
| id | number |
Customer UUID. |
string? |
Email associated with customer. | |
| firstName | string? |
Customer first name. |
| lastName | string? |
Customer last name. |
| note | string? |
Note added to customer profile. |
| Name | Type | Description |
|---|---|---|
| uuid | string |
UUID of line item |
| price | number? |
Line item price |
| quantity | number |
Line item quantity |
| title | string? |
Line item title |
| variantId | number? |
Line item variant UUID |
| productId | number? |
Product UUID |
| discounts | Discount[] |
An array of discounts applied to the line item |
| taxable | boolean |
Line item taxability |
| sku | string? |
Line item SKU |
| vendor | string? |
Line item vendor |
| properties | Record |
Custom key to value object to attribute to line item |
| isGiftCard | boolean |
Boolean to determine if line item is a gift card |
Cart level actions
Anchor link to section titled "Cart level actions"Note that all of these actions happen asynchronously. If you call multiple actions serially, please make sure you await the completion of the action, before calling the next action. Failure to do this may result in race conditions that cause the Cart to update inconsistently.
Apply a cart level discount
Anchor link to section titled "Apply a cart level discount"
| Name | Type | Description | Options |
|---|---|---|---|
| type | CartDiscountType |
Type of discount applied to cart | 'Percentage' or 'FixedAmount' or 'Code' |
| title | string |
Cart discount title | |
| amount | string? |
Percentage or fixed monetary amount to be deducted | Percentage: '0' to '1' Fixed: '0' and higher |
Apply a cart level discount code
Anchor link to section titled "Apply a cart level discount code"
| Name | Type | Description |
|---|---|---|
| code | string |
Code to be applied |
Remove cart level discount
Anchor link to section titled "Remove cart level discount"
Remove all cart level discounts
Anchor link to section titled "Remove all cart level discounts"
| Name | Type | Description |
|---|---|---|
| disableAutomaticDiscounts | boolean |
Whether to also disable automatic discounts from reapplying |
Add cart properties
Anchor link to section titled "Add cart properties"
| Name | Type | Description | Options |
|---|---|---|---|
| properties | Record |
Custom key to value object to attribute to the cart |
Remove cart properties
Anchor link to section titled "Remove cart properties"
Line item level actions
Anchor link to section titled "Line item level actions"Add custom sale to cart
Anchor link to section titled "Add custom sale to cart"
| Name | Type | Description | Options |
|---|---|---|---|
| customSale | CustomSale |
Custom sale object to add to the cart |
| Name | Type | Description |
|---|---|---|
| quantity | number |
Custom sale quantity |
| title | string |
Custom sale title |
| price | string |
Custom sale price |
| taxable | boolean |
Custom sale taxability |
Add line item to cart
Anchor link to section titled "Add line item to cart"
| Name | Type | Description | Options |
|---|---|---|---|
| variantId | number |
Product variant's numeric ID to add to the cart | |
| quantity | number |
Number of this variant to add to the cart |
Remove line item from cart
Anchor link to section titled "Remove line item from cart"
| Name | Type | Description | Options |
|---|---|---|---|
| uuid | string |
UUID of the line item |
Attribute the cart to a staff member
Anchor link to section titled "Attribute the cart to a staff member"
| Name | Type | Description | Options |
|---|---|---|---|
| staffId | number? |
Staff ID to attribute to the cart |
Attribute a line item to a staff member
Anchor link to section titled "Attribute a line item to a staff member"
| Name | Type | Description | Options |
|---|---|---|---|
| staffId | number? |
Staff ID to attribute to the line item | |
| lineItemUuid | string |
UUID of the line item |
Add line item properties
Anchor link to section titled "Add line item properties"
| Name | Type | Description | Options |
|---|---|---|---|
| uuid | string |
UUID of line item | |
| properties | Record |
Custom key to value object to attribute to line item |
Add line item properties to multiple line items
Anchor link to section titled "Add line item properties to multiple line items"
| Name | Type | Description |
|---|---|---|
| lineItemProperties | SetLineItemPropertiesInput[] |
A set of line item properties each associated with a line item UUID. The line item properties are set to the line item whose UUID matches the one provided. |
SetLineItemPropertiesInput
Anchor link to section titled "SetLineItemPropertiesInput"| Name | Type | Description |
|---|---|---|
| lineItemUuid | string |
The UUID belonging to the line item which should receive the custom properties. |
| properties | Record |
The custom properties to apply to the line item. |
Remove line item properties
Anchor link to section titled "Remove line item properties"
| Name | Type | Description | Options |
|---|---|---|---|
| uuid | string |
UUID of line item | |
| keys | string[] |
Collection of keys to be removed from the line item properties |
Add line item discount
Anchor link to section titled "Add line item discount"
| Name | Type | Description | Options |
|---|---|---|---|
| uuid | string |
UUID of line item | |
| type | LineItemDiscountType |
Type of discount applied to line item | 'Percentage' or 'FixedAmount' |
| title | string |
Line item discount title | |
| amount | string |
Percentage or fixed monetary amount deducted with the discount | Percentage: '0' to '1', Fixed: '0' and higher |
Add line item discount to multiple line items
Anchor link to section titled "Add line item discount to multiple line items"
| Name | Type | Description |
|---|---|---|
| lineItemDiscounts | SetLineItemDiscountInput[] |
A set of line item discounts associated with a line item UUID. The line item discount will be set to the line item matching the UUID. |
SetLineItemDiscountInput
Anchor link to section titled "SetLineItemDiscountInput"| Name | Type | Description |
|---|---|---|
| lineItemUuid | string |
The UUID belonging to the line item which should receive the discount. |
| lineItemDiscount | LineItemDiscount |
The discount to be applied to the line item. |
LineItemDiscount
Anchor link to section titled "LineItemDiscount"| Name | Type | Description |
|---|---|---|
| title | string |
The title of the line item discount. |
| type | 'Percentage' 'FixedAmount' |
The type of discount to be applied to the line item. |
| amount | string |
The percentage or fixed amount for the discount. |
Remove line item discount
Anchor link to section titled "Remove line item discount"
| Name | Type | Description | Options |
|---|---|---|---|
| uuid | string |
UUID of line item |
Customer actions
Anchor link to section titled "Customer actions"Add customer to cart
Anchor link to section titled "Add customer to cart"
| Name | Type | Description | Options |
|---|---|---|---|
| customer | Customer |
Existing customer. Note: only the ID field is used. |
Remove customer from cart
Anchor link to section titled "Remove customer from cart"
Add address to existing customer
Anchor link to section titled "Add address to existing customer"
| Name | Type | Description | Options |
|---|---|---|---|
| address | Address |
Customer address |
| Name | Type | Description |
|---|---|---|
| address1 | string? |
Street address line 1. |
| address2 | string? |
Street address line 2. |
| city | string? |
City name. |
| company | string? |
Customer company name. |
| firstName | string? |
Customer first name. |
| lastName | string? |
Customer last name. |
| phone | string? |
Customer phone number. |
| province | string? |
Province/State. |
| country | string? |
Country. |
| zip | string? |
Zip code. |
| name | string? |
Customer full name. |
| provinceCode | string? |
Province/State code. |
| countryCode | string? |
Country code. |
Delete address from existing customer
Anchor link to section titled "Delete address from existing customer"
| Name | Type | Description | Options |
|---|---|---|---|
| addressId | number |
ID of existing address to be deleted |
Set existing address as default address
Anchor link to section titled "Set existing address as default address"
| Name | Type | Description | Options |
|---|---|---|---|
| addressId | number |
ID of existing address to be set as default address |
| Name | Description |
|---|---|
| useCartSubscription() | A hook utilizing useState and the useStatefulSubscribableCart function to create a component state. This hook returns the latest Cart state which re-renders on change. |
| useStatefulSubscribableCart() | A hook utilizing the makeStatefulSubscribable function to allow multiple Cart subscriptions. This hook returns StatefulRemoteSubscribable object with a Cart in it. |
| destroyStatefulSubscribableCart() | A function destroying the subscriptions useStatefulSubscribableCart has. |