• Docs
  • Developer
  • Api
  • Cart

Cart API

Customer-facing REST API for shopping cart state, line items, coupons, and guest session hydration.

Overview

The WooNooW Cart API provides customer-facing endpoints for managing the shopping cart. It operates directly against WooCommerce's session and cart engine, enabling seamless synchronization between Single Page Applications (SPAs) and server-side WooCommerce plugins.

  • Controller: WooNooW\Frontend\CartController
  • Namespace: woonoow/v1
  • Base URL: https://your-store.com/wp-json/woonoow/v1

Session Architecture & Cookies

1. Guest Authentication Bypass

The WordPress REST API enforces nonce verification for cookie-authenticated sessions by default. To allow guest visitors to manage a cart without receiving rest_cookie_invalid_nonce errors, WooNooW registers a filter on rest_authentication_errors:

php
// Automatically bypassed for /woonoow/v1/cart*
if (strpos($request_uri, '/woonoow/v1/cart') !== false) {
    return true; // Allow guest access
}

2. Authoritative Cart Hydration

In standard WordPress REST API requests, WC()->cart is not automatically initialized. Every Cart API endpoint calls CartController::ensure_cart_initialized():

  1. Checks if WC()->session exists; if not, calls WC()->initialize_session().
  2. Checks if WC()->cart exists; if not, initializes WC()->cart and loads contents via WC()->cart->get_cart_from_session().
  3. If the cart is empty but a session key exists in the database, re-hydrates items from the session.
  4. If no session cookie exists yet, calls WC()->session->set_customer_session_cookie(true).

3. Multi-Currency Context

When the multi-currency module is active, the cart response automatically contextualizes monetary formatting based on CurrencyContext::get_context(), including active currency code, symbol, formatting decimal places, and exchange rate ID.

Response Envelope & Error Format

Unlike internal order submission endpoints, the Cart API adheres to standard WordPress REST API conventions:

  • Read Operations (GET /cart): Return HTTP 200 OK with the authoritative Cart Object directly at the root.
  • Mutation Operations (POST /cart/*): Return HTTP 200 OK with JSON payloads containing a descriptive message string and the updated cart object (as well as cart_item_key for /cart/add).
  • Failure Responses: Return WP_Error objects mapped to standard HTTP 4xx and 5xx status codes:
json
{
  "code": "invalid_product",
  "message": "Product not found",
  "data": {
    "status": 404
  }
}

Authoritative Cart Object Schema

All cart endpoints return the authoritative cart structure:

json
{
  "currency": "USD",
  "currency_symbol": "$",
  "decimals": 2,
  "rate_id": "base",
  "items": [
    {
      "key": "b9ece27d6fb4184db95da459864a6103",
      "product_id": 42,
      "variation_id": 0,
      "quantity": 2,
      "name": "WooNooW Pro License",
      "price": "99.00",
      "subtotal": 198.0,
      "total": 198.0,
      "image": "https://your-store.com/wp-content/uploads/pro.png",
      "permalink": "https://your-store.com/product/pro-license",
      "attributes": {}
    }
  ],
  "subtotal": "198.00",
  "subtotal_tax": "0.00",
  "discount_total": "0.00",
  "discount_tax": "0.00",
  "shipping_total": "0.00",
  "shipping_tax": "0.00",
  "cart_contents_tax": "0.00",
  "fee_total": "0.00",
  "fee_tax": "0.00",
  "total": "198.00",
  "total_tax": "0.00",
  "coupons": [],
  "needs_shipping": false,
  "needs_payment": true
}

Endpoints

1. Get Cart

Retrieves current cart contents, calculates totals, and returns the authoritative cart state.

http
GET /wp-json/woonoow/v1/cart

Permission

  • Public (Anonymous or Authenticated)

Response (HTTP 200)

Returns the Authoritative Cart Object directly.

2. Add to Cart

Adds a simple product or variation to the cart.

http
POST /wp-json/woonoow/v1/cart/add
Content-Type: application/json

Parameters

FieldTypeRequiredDefaultDescription
product_idintegerYes—ID of the product or parent variable product.
quantityintegerNo1Number of units to add (must be $\ge 1$).
variation_idintegerNo0ID of the specific variation (for variable products).
variationobjectNo{}Key-value pairs for variation attributes (e.g. {"attribute_size": "Large"}).
attribute_*stringNo—Request parameter attributes matching product variation definitions.

Example Request

json
{
  "product_id": 42,
  "quantity": 1,
  "variation_id": 43,
  "variation": {
    "attribute_tier": "Enterprise"
  }
}

Response (HTTP 200)

json
{
  "message": "Product added to cart",
  "cart_item_key": "c4ca4238a0b923820dcc509a6f75849b",
  "cart": { ... }
}

Errors

  • 404 invalid_product: The specified product_id does not exist.
  • 404 invalid_variation: The specified variation_id does not exist.
  • 400 invalid_variation: Variation does not belong to the specified parent product.
  • 400 variation_not_available: The requested variation is out of stock.
  • 400 add_to_cart_failed: WooCommerce validation rejected addition (includes flattened error notices, e.g. stock limits).

3. Update Cart Item

Modifies the quantity of an existing line item in the cart.

http
POST /wp-json/woonoow/v1/cart/update
Content-Type: application/json

Parameters

FieldTypeRequiredDescription
cart_item_keystringYesUnique hash key identifying the line item.
quantityintegerYesNew quantity. Setting to 0 removes the item.

Example Request

json
{
  "cart_item_key": "c4ca4238a0b923820dcc509a6f75849b",
  "quantity": 3
}

Response (HTTP 200)

json
{
  "message": "Cart updated",
  "cart": { ... }
}

Errors

  • 400 update_failed: Failed to update quantity (e.g. invalid key or stock limit exceeded).

4. Remove Item from Cart

Removes a single line item from the active cart.

http
POST /wp-json/woonoow/v1/cart/remove
Content-Type: application/json

Parameters

FieldTypeRequiredDescription
cart_item_keystringYesUnique hash key identifying the line item to remove.

Example Request

json
{
  "cart_item_key": "c4ca4238a0b923820dcc509a6f75849b"
}

Response (HTTP 200)

json
{
  "message": "Item removed from cart",
  "cart": { ... }
}

Errors

  • 404 item_not_found: The specified cart item key does not exist in the active cart.
  • 400 remove_failed: WooCommerce failed to remove the line item.

5. Clear Cart

Removes all items, packages, and applied coupons from the cart.

http
POST /wp-json/woonoow/v1/cart/clear

Response (HTTP 200)

json
{
  "message": "Cart cleared",
  "cart": {
    "currency": "USD",
    "items": [],
    "total": "0.00",
    "coupons": [],
    ...
  }
}

6. Apply Coupon

Applies a discount code to the cart session.

http
POST /wp-json/woonoow/v1/cart/apply-coupon
Content-Type: application/json

Parameters

FieldTypeRequiredDescription
coupon_codestringYesCase-insensitive coupon code to apply.

Example Request

json
{
  "coupon_code": "SUMMERSALE"
}

Response (HTTP 200)

json
{
  "message": "Coupon applied",
  "cart": { ... }
}

Errors

  • 400 coupon_code_required: An empty or whitespace coupon code was submitted.
  • 400 coupons_disabled: Store has disabled coupon usage.
  • 500 cart_error: Cart session could not be initialized.
  • 400 empty_cart: Cart contains no products to discount.
  • 400 coupon_currency_mismatch: Coupon is restricted to a currency different from the active currency context.
  • 400 coupon_failed: WooCommerce coupon validation failed (e.g. usage limit reached, minimum spend unmet, or expired).

7. Remove Coupon

Removes an applied discount code from the cart.

http
POST /wp-json/woonoow/v1/cart/remove-coupon
Content-Type: application/json

Parameters

FieldTypeRequiredDescription
coupon_codestringYesThe coupon code to remove.

Example Request

json
{
  "coupon_code": "SUMMERSALE"
}

Response (HTTP 200)

json
{
  "message": "Coupon removed",
  "cart": { ... }
}

Errors

  • 400 coupon_code_required: The coupon code parameter was missing or empty.
  • 500 cart_error: Cart session could not be initialized.
  • 400 coupon_not_applied: The specified coupon code is not currently applied to the cart.
  • 400 remove_coupon_failed: Failed to remove coupon from the session.

Last updated Sep 11, 2026