Cart2

Evaluates a cart for loyalty: spendable balance, redemption constraints, estimated points, and (when mutating) coupon effects.

Kind	Write API call
Method	POST
URL	https://app.bubblehouse.com/api/v2023061/<shop>/Cart2
Authentication	Customer TokenShop Token

Send the current cart as an Order2. Bubblehouse returns the customer's balance and redemption constraints as if no pending provisional redemption existed, plus an estimate of points after checkout.

preset selects a Cart2 configuration. Unknown values return unknown_preset.

Mutating Cart2 uses provisional coupons. desired_redemption_pts is the total to have redeemed after this call, including any Bubblehouse coupon already on the cart. It is not how many extra points to add. Send 0 to clear.

After you apply cart_changes_to_apply.add_coupons, call Cart2 again with the same desired_redemption_pts and those coupon codes on the cart. cart_changes_to_apply is empty: same pending, same code. Do not add the new coupon's points on top of the total.

Example at the default 1 point = 10 cents: cart $20, no codes, desired_redemption_pts 50 returns a $5 coupon. Apply that code. The cart remaining to pay is $15. Call again with desired_redemption_pts 50 (not 100) and that code on discount_codes, sending $15 as amount_subtotal and amount_spent. No coupon changes.

Input

• preset string required

  Cart2 preset name.

  Public presets: cart (custom checkout; mutates when desired_redemption_pts is set or can_apply_cart_effects is true), pdp (product-page estimate, never mutates), and readonly (estimate only, never mutates).

  Bubblehouse may add specific per-client presets.

• customer CustomerIdentity1 optional

  Customer to evaluate. Omitted or unknown customers are treated as empty.

• context CartContext2 optional

  Market and locale context when not provided on the cart.

• cart Order2 required

  The current cart, using the same Order2 shape as UpdateOrders4.

• desired_redemption_pts integer optional

  Total points that should be redeemed against this cart after the call, including any Bubblehouse coupon already applied.

  This is the whole redemption, not an increment. If 50 points are already pending and you still want 50, send 50 again with the coupon code on the cart. Cart2 returns no add/remove coupon effects.

  Send 0 to clear the pending coupon.

• can_apply_cart_effects boolean optional

  True when the caller is ready to apply returned cart changes.

Output

• widget RedemptionWidgetInfo1 optional

  Undocumented. Omitted for public presets.

• cart_changes_to_apply CartChanges2 required

  Coupon and line-item effects for the caller to apply to their cart.

• balance_before BriefCustomerBalance4 required

  Customer balance as if no pending provisional redemption existed.

• pts_redemption_constraints_before PtsRedemptionConstraints1 optional

  Redemption min/max/buckets for the whole pending total.

• pending_redemption Redemption1 optional

  Current provisional pending redemption after this call.

• after_checkout OrderEffect2 required

  Estimated order points and balance after checkout.

Specific Errors

Status	Error	Reason & Examples
400	unknown_preset	The preset name is missing or is not a known builtin or configured preset.
422	cart_not_mutating	desired_redemption_pts does not match the current pending redemption, and this Cart2 preset cannot change redemptions.
422	invalid_request_data	The request is missing a required field or contains invalid values.
422	insufficient_points	Attempting to redeem more points than the customer has.
422	points_disabled	You have not enabled points in the admin portal.