Call `cartCreate` with a `CartInput` that includes `lines` (array of `CartLineInput` with `merchandiseId` and `quantity`), `buyerIdentity` with `countryCode` set to the buyer's country (e.g., `DE`), and optionally `email`
Apply the `@inContext(country: DE, language: DE)` directive to the cartCreate mutation for language-localized field responses (titles, descriptions), but be aware that cart pricing resolution comes from `buyerIdentity.countryCode`, not the directive
In the response, read `cart.cost.totalAmount { amount currencyCode }` to confirm the cart is priced in the correct local currency, and check `cart.buyerIdentity.countryCode` to verify country was accepted
To apply discount codes, follow up with `cartDiscountCodesUpdate(cartId: $cartId, discountCodes: ["CODE"])` and inspect `cart.discountCodes { code applicable }` to confirm the code resolved
Retrieve `cart.checkoutUrl` and redirect the buyer to it to complete purchase in Shopify-hosted checkout; the checkout will inherit the cart's buyer identity country for tax and duty calculation
Handle the `cart.userErrors` array on every mutation — errors include invalid variant IDs, out-of-stock items, and mismatched currencies
Known gotchas
Cart mutations (cartLinesAdd, cartLinesUpdate, etc.) ignore the @inContext country directive for pricing — country context for cart pricing must be set via buyerIdentity.countryCode on the cart itself
The Storefront API requires a public access token (not the Admin API access token); embedding an Admin API token in a client-side headless storefront is a critical security error
cart.checkoutUrl is a one-time redirect URL tied to the specific cart state; sharing or caching it across multiple sessions can expose one buyer's cart to another
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