Use the Medusa Store API POST /store/carts to create a cart; optionally include region_id, sales_channel_id, and currency_code in the request body.
Add line items via POST /store/carts/{cartId}/line-items with variant_id and quantity; Medusa resolves price from the variant's price set for the cart's region and currency.
Update line item quantities via POST /store/carts/{cartId}/line-items/{lineItemId} with a new quantity, or delete via DELETE for removal.
Apply a promotion code via POST /store/carts/{cartId}/promotions with the code string; consult current docs for Medusa v2's promotions API shape.
Retrieve the cart via GET /store/carts/{cartId} to read items, total, subtotal, and applied promotions before proceeding to checkout.
Medusa v2 uses a workflow engine; many operations are implemented as composable workflows—consult current Medusa v2 docs for how to customize or extend cart workflows via custom steps.
Known gotchas
Medusa v2 (2.x) has significant API and architecture differences from Medusa v1; ensure you are referencing docs for the correct major version, as endpoint paths and request shapes differ substantially.
Price resolution in Medusa v2 depends on the variant having a price set with a rule matching the cart's region and currency; missing price rules result in variants not being addable to the cart.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp