Headless store

Andrea opens your frontend, picks a T-shirt, and pays for it. This guide builds that flow with the Storefront API: catalog, product page, cart, and checkout.

Requirements

• The store slug or one of its domains, in x-Store-Domain. No token needed.
• Products published in the store.

List products

GET /v1/products returns a page of the published catalog and its filters. Send x-Store-Domain on every call.

curl "https://storefront.ecomiq.pe/v1/products?page=1&pageSize=24" \
  -H "x-Store-Domain: mi-tienda"

Each product has name, slug, price, and imageUrl. Increase page up to totalPages. If the view shows no filters, add includeFilters=false. More in Pagination.

Show a product

GET /v1/products/{slug} returns the full product page: variants, images, specifications, and stock. The slug is the one in the store URL.

curl https://storefront.ecomiq.pe/v1/products/polo-de-algodon \
  -H "x-Store-Domain: mi-tienda"

Each variant has id, sku, price, isAvailable, and options. Keep the id of the selected variant.

Create a cart

POST /v1/carts creates the cart. The response has token, which identifies the cart in the next calls.

curl -X POST https://storefront.ecomiq.pe/v1/carts \
  -H "x-Store-Domain: mi-tienda" \
  -H "Content-Type: application/json" \
  -d '{ "email": "andrea@example.com" }'

Add items

Send the variant id and the quantity. The response returns the cart with items and totals.

curl -X POST https://storefront.ecomiq.pe/v1/carts/<cart-token>/items \
  -H "x-Store-Domain: mi-tienda" \
  -H "Content-Type: application/json" \
  -d '{ "variantId": "7204558912004325377", "quantity": 2 }'

Prepare the checkout

Add the purchase details with these operations:

Then GET /v1/carts/{cartToken}/checkout returns the cart and the enabled payment methods in paymentMethods.methods.

curl https://storefront.ecomiq.pe/v1/carts/<cart-token>/checkout \
  -H "x-Store-Domain: mi-tienda"

Show paymentMethods.methods to the buyer. Store the selected code in paymentMethodCode.

Create the order

Send the payment method code. The checkout creates the orders for the cart.

curl -X POST https://storefront.ecomiq.pe/v1/carts/<cart-token>/checkout \
  -H "x-Store-Domain: mi-tienda" \
  -H "Content-Type: application/json" \
  -d '{ "paymentMethodCode": "<payment-method-code>" }'

The response has orderId, orderNumber, and the payment state in payment. A cart with several sellers can create several orders: they are in orderIds.

Next steps

• Catalog: search, filters, and variants.
• Cart: codes, addresses, and shipping.
• Checkout and payment: redirects, manual payments, and order status.
• Organization, store, and seller: how each call selects the store.