POST /api/cart/sync/

The Urban Store frontend manages cart state locally using a Zustand store persisted in localStorage. After every mutation — adding an item, changing a quantity, removing an item, or clearing the cart — the Zustand cartStore calls this endpoint to push the current local state to MongoDB. The server replaces the stored cart wholesale with whatever the frontend sends, ensuring both layers always reflect the same data. This is a full replace operation. The entire existing cart in MongoDB is discarded and rewritten from the items array in the request body. To clear the cart server-side, send an empty array. Authentication required:

Authorization: Bearer <token>

Replace the authenticated user’s server-side cart with the provided items. If no cart exists yet for the user, one is created.

Request Body

items

array

required

The complete array of cart item objects representing the frontend’s current cart state. Send an empty array [] to clear the cart on the server.

Each item object in the array must follow this shape:

items[].product_slug

string

required

Slug of the product.

items[].product_name

string

Display name of the product. Stored as-is for cart rendering.

items[].quantity

integer

Number of units. Defaults to 1 if not provided.

items[].selected_size

string

Size variant. Defaults to an empty string if not provided.

items[].selected_color

string

Color variant. Defaults to an empty string if not provided.

items[].price_at_time

number

Unit price at the time the item was added to the local cart. Defaults to 0 if not provided.

items[].image

string

Cloudinary image URL for the item. Defaults to an empty string if not provided.

Response Fields

status

string

Always "ok" on a successful sync.

total

number

Recalculated sum of price_at_time × quantity for all synced items.

item_count

integer

Recalculated sum of all item quantities after the sync.

Example — Sync after adding an item

curl -X POST https://urban-store-api.example.com/api/cart/sync/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "product_slug": "urban-classic-tee",
        "product_name": "Urban Classic Tee",
        "quantity": 2,
        "selected_size": "M",
        "selected_color": "negro",
        "price_at_time": 49.99,
        "image": "https://res.cloudinary.com/urban-store/image/upload/v1/products/classic-tee-1.jpg"
      },
      {
        "product_slug": "urban-cargo-pant",
        "product_name": "Urban Cargo Pant",
        "quantity": 1,
        "selected_size": "L",
        "selected_color": "blanco",
        "price_at_time": 79.99,
        "image": "https://res.cloudinary.com/urban-store/image/upload/v1/products/cargo-pant-1.jpg"
      }
    ]
  }'

200 OK:

{
  "status": "ok",
  "total": 179.97,
  "item_count": 3
}

To clear the cart server-side, POST with an empty items array. This is the canonical way to wipe a user’s MongoDB cart — for example, after a successful checkout.

curl -X POST https://urban-store-api.example.com/api/cart/sync/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "items": [] }'

Response:

{
  "status": "ok",
  "total": 0,
  "item_count": 0
}

The frontend calls this endpoint fire-and-forget. Sync failures are caught and logged as warnings rather than surfaced to the user as errors. The local Zustand store is always treated as the source of truth; the server-side cart is a durable backup for cross-device consistency. If a sync call fails, the user’s next action will trigger another sync attempt automatically.

Users

Products & Cart

Orders & Payments

Analytics

POST /api/cart/sync/ — Replace Cart with Frontend State