Skip to content
Progare

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

POST/storefront/{storeSlug}/cart/itemsCart session / optional auth
Add an item, or set its quantity if it’s already in the cart. Send quantity: 0 to remove it.
bash
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.

GET/storefront/{storeSlug}/cartCart session / optional auth
DELETE/storefront/{storeSlug}/cartCart session / optional auth
Empty the cart.
POST/storefront/{storeSlug}/cart/couponOptional auth
Check a coupon before checkout. Body: { "code": "DIWALI10" }.

2. Get shipping options

GET/storefront/{storeSlug}/shipping-methods?country=IN&state=Maharashtra&postalCode=400001Cart session / optional auth
Rates that apply to the address and current cart. Each has an id, name and price.
GET/storefront/{storeSlug}/checkout/optionsOptional auth
Which payment methods, delivery slots, gift wrap and other checkout features the store has turned on.
POST/storefront/{storeSlug}/checkout/validate-addressPublic
Optional — validate an address against the store’s rules before placing the order.

3. Place the order

POST/storefront/{storeSlug}/checkoutCart session / optional auth
Creates the order from the cart (or from items, if you pass them).
Request body
{
  "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"
}
FieldNotes
shippingAddressRequired. addressLine2 is optional.
shippingMethodIdRequired — an id from shipping-methods.
paymentMethodcod, razorpay, upi, card, emi, bnpl, wallet or store_credit — only what checkout/options allows.
itemsOptional — [{ productId, variantId?, quantity }]. Defaults to the cart.
billingAddressOptional — same shape as shippingAddress.
couponCode, referralCode, loyaltyPointsOptional discounts.
giftWrap, giftMessageOptional, when gift wrap is enabled.
deliveryDate, deliverySlotIdOptional, when delivery slots are enabled.
shippingAddressId, saveAddressSigned-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:

json
{ "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:

json
{
  "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.

Browser
<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>
POST/storefront/{storeSlug}/checkout/verifyCart session / optional auth
Confirms the payment. Body: orderId, razorpay_order_id, razorpay_payment_id, razorpay_signature.

5. After checkout

GET/storefront/{storeSlug}/checkout/payment-status/{orderId}Optional auth
Poll the payment status, e.g. on a “confirming your payment” screen.
GET/storefront/{storeSlug}/checkout/retry/{orderId}Optional auth
Get fresh Razorpay details to retry a failed or abandoned payment on the same order.
POST/storefront/{storeSlug}/checkout/cancelOptional auth
Cancel an unpaid order. Body: { "orderId": "…", "reason": "…" }.
GET/storefront/{storeSlug}/orders/{orderId}Public
Order confirmation details.

For 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