Storefront API
Cart & checkout
From an empty cart to a paid order. Every call below sends X-Cart-Session for guests and, if the shopper is signed in, their Bearer token too (see Authentication).
1. Build the cart
/storefront/{storeSlug}/cart/itemsCart session / optional authquantity: 0 to remove it.curl -X POST "https://api.progare.com/storefront/mahi-studio/cart/items" \
-H "Content-Type: application/json" \
-H "X-Cart-Session: 6f1c2a…" \
-d '{ "productId": "c1f0…", "variantId": "9ab3…", "quantity": 2 }'variantId is required for products with variants. The response is the full cart.
/storefront/{storeSlug}/cartCart session / optional auth/storefront/{storeSlug}/cartCart session / optional auth/storefront/{storeSlug}/cart/couponOptional auth{ "code": "DIWALI10" }.2. Get shipping options
/storefront/{storeSlug}/shipping-methods?country=IN&state=Maharashtra&postalCode=400001Cart session / optional authid, name and price./storefront/{storeSlug}/checkout/optionsOptional auth/storefront/{storeSlug}/checkout/validate-addressPublic3. Place the order
/storefront/{storeSlug}/checkoutCart session / optional authitems, if you pass them).{
"shippingAddress": {
"firstName": "Asha",
"lastName": "Rao",
"email": "asha@example.com",
"phone": "9876543210",
"addressLine1": "12 MG Road",
"addressLine2": "Flat 4B",
"city": "Pune",
"state": "Maharashtra",
"zipCode": "411001",
"country": "IN"
},
"shippingMethodId": "standard",
"paymentMethod": "razorpay",
"couponCode": "DIWALI10",
"notes": "Please call before delivery"
}| Field | Notes |
|---|---|
shippingAddress | Required. addressLine2 is optional. |
shippingMethodId | Required — an id from shipping-methods. |
paymentMethod | cod, razorpay, upi, card, emi, bnpl, wallet or store_credit — only what checkout/options allows. |
items | Optional — [{ productId, variantId?, quantity }]. Defaults to the cart. |
billingAddress | Optional — same shape as shippingAddress. |
couponCode, referralCode, loyaltyPoints | Optional discounts. |
giftWrap, giftMessage | Optional, when gift wrap is enabled. |
deliveryDate, deliverySlotId | Optional, when delivery slots are enabled. |
shippingAddressId, saveAddress | Signed-in shoppers: use or save an address book entry. |
Cash on Delivery response
For COD (and orders fully covered by credit or points), the order is placed immediately and requiresPayment is false:
{ "requiresPayment": false, "orderId": "5d2e…", "orderNumber": "…", "status": "pending", "subtotal": 2598, … }Online payment response
For online payment, the order waits in awaiting_payment and you get what’s needed to open Razorpay Checkout:
{
"requiresPayment": true,
"provider": "razorpay",
"orderId": "5d2e…",
"orderNumber": "…",
"status": "awaiting_payment",
"keyId": "rzp_live_…",
"razorpayOrderId": "order_P1x…",
"amount": 259800,
"currency": "INR"
}4. Collect payment
Open Razorpay Checkout with the store’s keyId and razorpayOrderId, then send Razorpay’s result to checkout/verify. The server checks the signature before marking the order paid.
<script src="https://checkout.razorpay.com/v1/checkout.js"></script>
<script>
const rzp = new Razorpay({
key: res.keyId,
order_id: res.razorpayOrderId,
amount: res.amount,
currency: res.currency,
handler: async (payment) => {
await fetch(`${API}/storefront/${slug}/checkout/verify`, {
method: "POST",
headers: { "Content-Type": "application/json", "X-Cart-Session": cartSession() },
body: JSON.stringify({
orderId: res.orderId,
razorpay_order_id: payment.razorpay_order_id,
razorpay_payment_id: payment.razorpay_payment_id,
razorpay_signature: payment.razorpay_signature,
}),
});
location.href = `/order/${res.orderId}`;
},
});
rzp.open();
</script>/storefront/{storeSlug}/checkout/verifyCart session / optional authorderId, razorpay_order_id, razorpay_payment_id, razorpay_signature.5. After checkout
/storefront/{storeSlug}/checkout/payment-status/{orderId}Optional auth/storefront/{storeSlug}/checkout/retry/{orderId}Optional auth/storefront/{storeSlug}/checkout/cancelOptional auth{ "orderId": "…", "reason": "…" }./storefront/{storeSlug}/orders/{orderId}PublicFor Cash on Delivery (and fully prepaid orders) the cart is emptied automatically when the order is placed. After a successful online payment, call DELETE /storefront/{storeSlug}/cart yourself. Order confirmation and shipping emails are sent by Progare — you don’t need to send your own.
Something unclear or out of date? Tell us