Cart: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Create a cart and add products

A custom storefront or POS system needs to create carts and add products for customers. This is the foundational flow for any e-commerce integration.

To create a cart with products:

1. Call Create Cart with initial catalog items:

   Copy

2. Save the returned cart.id for future operations on this cart.

3. To add more items later, call Add Line Items with the saved cart ID:

   Copy

4. The response includes the updated cart with all line items and their current prices.

Apply a coupon and calculate cart totals

Customers often have discount coupons they want to apply before checkout. This flow shows how to apply a coupon and display updated pricing.

To apply a coupon and calculate totals:

1. Call Add Coupon with the coupon code:

   Copy

   If the coupon is valid, it's added to the cart. If invalid, you'll receive an error with details.

2. Call Calculate Cart to get the detailed pricing breakdown:

   Copy

3. The response includes:

   • summary.priceSummary: Subtotal, discount amount, delivery cost, tax, and total
   • summary.discounts: Applied discounts including the coupon
   • summary.priceVerificationToken: Save this token for checkout
   • summary.violations: Any business rule violations

4. Display the pricing summary to the customer, showing original price, discount, and final total.

Complete the checkout process

When a customer is ready to buy, the cart needs to be validated, calculated, and placed as an order. This flow covers the full checkout sequence.

To complete the checkout process:

1. Ensure the cart has all required information:

   • Customer info (name, email, phone)
   • Delivery address and selected delivery method
   • Line items are in stock

2. Call Update Cart to set customer information if not already set:

   Copy

3. Call Set Delivery Method to select shipping:

   Copy

4. Call Calculate Cart to get the full pricing breakdown, including delivery, taxes, fees, and gift cards:

   Copy

5. Check for violations in summary.violations. If any exist, display them to the customer and don't proceed.

6. Save the summary.priceVerificationToken from the calculation response.

7. Display the final pricing to the customer for confirmation.

8. Call Place Order to complete checkout:

   Copy

9. The response includes:

   • orderId: The created order ID
   • completed: Whether the order was created and payment completed
   • paymentGatewayOrderId: Payment gateway order ID, returned when money needs to be charged. Pass it as the paymentId parameter to the Wix Pay startPayment() function to collect payment. This requires Velo; if your app can't run Velo code, send the customer to the Wix-hosted checkout page with Get Checkout URL instead.

10. If completed is true, redirect the customer to your order confirmation page. Otherwise, handle the pending payment state.

Manage session-based shopping with the current cart

For standard e-commerce shopping flows, the Current Cart service lets you manage the customer's cart without tracking cart IDs. The cart is automatically associated with the customer's session.

To build a session-based shopping experience:

1. Call Add Line Items To Current Cart when a customer clicks "Add to Cart":

   Copy

   Note: If no current cart exists, this method automatically creates one. If a current cart already exists, items are added to it.

2. Call Get Current Cart to display the cart:

   Copy

   This retrieves the customer's current cart without needing a cart ID. The cart is automatically associated with the customer's session (visitor ID or member ID).

3. To update quantities, call Update Line Items In Current Cart:

   Copy

4. To remove items, call Remove Line Items From Current Cart:

   Copy

5. For checkout, call Calculate Current Cart to get pricing, then retrieve the cart ID from the response and call Place Order with that cart ID.

Handle out-of-stock and partially available items

Products can become unavailable or have reduced stock while they're in a customer's cart. This flow shows how to detect and handle inventory changes.

To handle out-of-stock items:

1. Call Refresh Cart to sync with current inventory:

   Copy

2. Check each line item's status in the response:

   • IN_STOCK: Full requested quantity is available
   • PARTIALLY_IN_STOCK: Some quantity is available (check quantityInfo.confirmedQuantity)
   • OUT_OF_STOCK: No stock available (confirmedQuantity is 0)
   • REMOVED_FROM_CATALOG: Product no longer exists

3. For partially available items, compare confirmedQuantity to requestedQuantity:

   Copy

4. For out-of-stock items, either:

   • Keep them in the cart with confirmedQuantity: 0 (customer can see what's unavailable)
   • Remove them with Remove Line Items.

5. When items are restocked, confirmedQuantity doesn't automatically increase. To allow customers to purchase more after restocking:

   • Call Refresh Cart to update availableQuantity.
   • Check if availableQuantity now exceeds confirmedQuantity.
   • Call Update Line Items to increase the quantity:
   Copy

Add a gift card as payment

Customers may have gift cards they want to apply toward their purchase. This flow shows how to add a gift card and check the remaining balance due.

To add a gift card as payment:

1. Call Add Gift Card with the gift card code:

   Copy

2. The API validates the gift card and adds it to paymentInfo.giftCards if valid.

3. Call Calculate Cart to get the full pricing breakdown including gift card deductions:

   Copy

   Note: Calculate Cart always includes gift cards in the calculation. To selectively include or exclude components like gift cards, use Estimate Cart instead.

4. Check the payment summary in the response:

   • paymentSummary.totalAfterGiftCards: Amount due after applying gift card balance
   • paymentSummary.giftCards[0].amount: Amount deducted from gift card
   • paymentSummary.requiresPaymentAfterGiftCard: Whether additional payment is needed

5. If the gift card fully covers the cart total, totalAfterGiftCards will be 0 and no additional payment is required.

6. During Place Order, the gift card balance is automatically applied before charging the payment method.

Build a cart recovery flow

Cart abandonment is common in e-commerce. This flow shows how to detect abandoned carts and bring customers back to complete their purchase.

To build a cart recovery flow:

1. Set up a webhook or scheduled job to detect abandoned carts (carts not checked out after a certain time).

2. Call Get Cart to retrieve the cart details:

   Copy

3. Check if the cart is still valid:

   • orderPlaced should be false (not yet checked out).
   • Line items should exist.
   • Cart should not be too old (for example, less than 30 days).

4. Send a recovery email to the customer using cart.customerInfo.email with:

   • Link to resume checkout: Include the cart ID in the URL.
   • Cart summary: List products, quantities, and total price.
   • Incentive: Optional discount code to encourage completion.

5. When the customer clicks the link, call Get Cart again to load their cart. The API automatically refreshes it with current prices and inventory.

6. If items are no longer available, use the flow in "Handle out-of-stock items" above to notify the customer.

7. Guide the customer through the checkout process using the flow in "Complete the checkout process" above.