Sign in
Cart V2

Add item to cart

Add item to cart with variant selection

Adds a variant-specific item to the user's cart by:

  1. Validating listing exists and is active
  2. Validating variant exists and belongs to listing
  3. Checking variant availability (sufficient stock)
  4. Snapshotting current variant price
  5. Creating or updating cart item (upsert on user_id + listing_id + variant_id)

If the same variant already exists in cart, the quantities are added together. Price is updated to current price on each add operation.

Requirements:

  • 30.1: POST /api/v2/cart/add endpoint
  • 30.2: Accept listing_id, variant_id, and quantity
  • 30.3: Validate listing exists and is active
  • 30.4: Validate variant exists and belongs to listing
  • 30.5: Check variant availability before adding
  • 30.6: Snapshot variant price at add-to-cart time
  • 30.7: Create cart_items_v2 entry with variant_id
  • 30.8: Support upsert (update if already in cart)
  • 30.9: Validate quantity is positive integer
  • 30.10: Return cart_item_id on success
  • 30.11: Prevent adding unavailable variants with descriptive error
  • 30.12: Log cart additions to audit trail
post/cart/add

Request

  • Base URL: /api/v2 (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/v2/cart/add
  • Auth: loggedin (a scheme the document does not define)

Request body

listing_idstring required

UUID of the listing

variant_idstring required

UUID of the specific variant to add

quantitynumber double required

Quantity to add (must be > 0)

Response

Cart item ID and success message

cart_item_idstring required

UUID of the created cart item

messagestring required

Success message

Changes

No recorded changes to this operation across all 50 revisions of this API.