# Commerce Engine Docs: API Reference Storefront API

> Official documentation for Commerce Engine - The modern headless commerce platform for building scalable e-commerce solutions.

## Storefront API

### Introduction

- [Getting Started](https://www.commercengine.io/docs/api-reference/getting-started.md): Learn how to authenticate with the Commerce Engine API and make your first request.

### 🛍️ Commerce

#### Catalog

- [List all products](https://www.commercengine.io/docs/api-reference/catalog/list-all-products.md): list all products
- [List all SKUs](https://www.commercengine.io/docs/api-reference/catalog/list-all-skus.md): List all SKUs
- [Retrieve a product detail](https://www.commercengine.io/docs/api-reference/catalog/retrieve-a-product-detail.md): Retrieves a single `ProductDetail` object by product ID or slug. Product slug is supported in place of product ID in the path. Includes full pricing, variants, images, attributes, and promotion data.
- [Retrieve product variants](https://www.commercengine.io/docs/api-reference/catalog/retrieve-product-variants.md): Retrieves the variants of an existing product. Returns the corresponding variant list. Product slug is supported in place of product ID in the path.
- [Retrieve variant detail](https://www.commercengine.io/docs/api-reference/catalog/retrieve-variant-detail.md): Retrieves the details of a particular variant. Product slug is supported in place of product ID, and variant slug in place of variant ID, in the path.
- [List all categories](https://www.commercengine.io/docs/api-reference/catalog/list-all-categories.md): list all categories
- [List product reviews](https://www.commercengine.io/docs/api-reference/catalog/list-all-product-reviews.md): List product reviews
- [Create product review](https://www.commercengine.io/docs/api-reference/catalog/create-product-review.md)
- [Retrieve similar products](https://www.commercengine.io/docs/api-reference/catalog/retrieve-similar-products.md): Retrieves a list of products similar to a specified product based on their attributes and category. The similar products are returned sorted by relevance, with the most closely matching products appearing first. Useful for providing product recommendations to your customers.
- [Retrieve up-sell products](https://www.commercengine.io/docs/api-reference/catalog/retrieve-up-sell-products.md): Retrieves a list of products specified for upsell. The upsell products are returned based on product ids specified in request param.
- [Retrieve cross-sell products](https://www.commercengine.io/docs/api-reference/catalog/retrieve-cross-sell-products.md): Retrieves a list of products specified for cross selling. The cross-sell products are returned based on product ids specified in request param.
- [Search products](https://www.commercengine.io/docs/api-reference/catalog/search-products.md): Search for products matching a specific words or characters given.

#### Carts

- [Create cart](https://www.commercengine.io/docs/api-reference/carts/create-cart.md): Creates a new cart with an initial set of items. Returns a `Cart` object. Attach optional `metadata` for custom key-value pairs.
- [Retrieve cart detail](https://www.commercengine.io/docs/api-reference/carts/retrieve-cart-detail.md): Retrieves the full `Cart` object for the given cart ID.
- [Delete cart](https://www.commercengine.io/docs/api-reference/carts/delete-cart.md): delete all items from the cart.
- [Retrieve cart by user ID](https://www.commercengine.io/docs/api-reference/carts/retrieve-cart-using-user-id.md): Retrieves the active `Cart` object for a given user. Use the `user_id` returned from auth endpoints.
- [Delete cart using user id](https://www.commercengine.io/docs/api-reference/carts/delete-cart-using-user-id.md): delete all items from the cart using user id.
- [Add, update, or remove a cart item](https://www.commercengine.io/docs/api-reference/carts/adddelete-cart-item.md): Modifies the contents of an existing cart. Returns a fully updated `Cart` object. Set `quantity` to `0` to remove an item.
- [Set cart address](https://www.commercengine.io/docs/api-reference/carts/update-cart-address.md): Sets billing and shipping addresses on a cart. Returns a fully updated `Cart` object. For registered users, pass `billing_address_id` and `shipping_address_id`. For guest checkout, pass inline `billing_address` and `shipping_address` objects.
- [Apply coupon](https://www.commercengine.io/docs/api-reference/carts/apply-coupon.md): Applies a coupon code to the cart. Returns a fully updated `Cart` object with recalculated totals.
- [Remove coupon](https://www.commercengine.io/docs/api-reference/carts/remove-coupon.md): Removes the applied coupon from the cart. Returns a fully updated `Cart` object with recalculated totals.
- [Redeem loyalty points](https://www.commercengine.io/docs/api-reference/carts/redeem-loyalty-points.md): Applies loyalty points to reduce the cart total. Returns a fully updated `Cart` object.
- [Remove loyalty points](https://www.commercengine.io/docs/api-reference/carts/remove-loyalty-points.md): Removes redeemed loyalty points from the cart. Returns a fully updated `Cart` object with recalculated totals.
- [Use credit balance](https://www.commercengine.io/docs/api-reference/carts/use-credit-balance.md): Applies credit balance to reduce the cart total. Returns a fully updated `Cart` object.
- [Remove credit balance](https://www.commercengine.io/docs/api-reference/carts/remove-credit-balance.md): Removes applied credit balance from the cart. Returns a fully updated `Cart` object with recalculated totals.
- [Check fulfillment](https://www.commercengine.io/docs/api-reference/carts/check-fulfillment.md): Checking if fulfillment is available to the entered pincode based on shipping zones and inventories.
- [Update fulfillment preference](https://www.commercengine.io/docs/api-reference/carts/update-fulfillment-preference.md): Sets the fulfillment preference on a cart. Returns a fully updated `Cart` object. Supported types: `delivery`, `collect-in-store`, or `partial-collect-and-delivery`.
- [Retrieve fulfillment options](https://www.commercengine.io/docs/api-reference/carts/retrieve-fulfillment-options.md): Returns available fulfillment options for a cart and delivery pincode. The `summary` object indicates `collect_available`, `deliver_available`, and `recommended_fulfillment_type`. Use the `collect` array for Click & Collect store locations and `deliver` for delivery details.
- [Retrieve wishlist](https://www.commercengine.io/docs/api-reference/carts/retrieve-wishlist.md): Retrieve products in wishlist
- [Add product to wishlist](https://www.commercengine.io/docs/api-reference/carts/add-product-to-wishlist.md): Adds a product to the user's wishlist. Returns the updated wishlist as an array of `Item` objects.
- [Delete product from wishlist](https://www.commercengine.io/docs/api-reference/carts/delete-product-from-wishlist.md): Remove product from wishlist

#### Coupons & Promotions

- [Retrieve all coupons](https://www.commercengine.io/docs/api-reference/carts/retrieve-all-coupons.md): Retrieve active coupons
- [Retrieve all promotions](https://www.commercengine.io/docs/api-reference/carts/retrieve-all-promotions.md): All active promotions
- [Evaluate coupons](https://www.commercengine.io/docs/api-reference/carts/evaluate-coupons.md): Evaluates all coupons against the current cart contents. Returns separate `applicable_coupons` and `inapplicable_coupons` arrays with eligibility reasons.
- [Evaluate promotions](https://www.commercengine.io/docs/api-reference/carts/evaluate-promotions.md): Evaluates all promotions against the current cart contents. Returns separate `applicable_promotions` and `inapplicable_promotions` arrays with eligibility reasons.

#### Orders

- [List all orders](https://www.commercengine.io/docs/api-reference/orders/retrieve-all-orders.md): List all orders
- [Create order](https://www.commercengine.io/docs/api-reference/orders/create-order.md)
- [Retrieve order details](https://www.commercengine.io/docs/api-reference/orders/retrieve-order-detail.md): Retrieve order details
- [Retrieve payment status](https://www.commercengine.io/docs/api-reference/orders/retrieve-payment-status.md): Retrieves the authoritative payment status of an order. After a payment attempt, poll this endpoint from your return URL every 2-3 seconds until `status` is `success` or `failed`. When `is_retry_available` is `true`, the payment can be retried.
- [Retrieve order shipments](https://www.commercengine.io/docs/api-reference/orders/retrieve-order-shipments.md): Retrieve order shipments
- [Retrieve order refunds](https://www.commercengine.io/docs/api-reference/orders/retrieve-order-refunds.md): Retrieve order refunds
- [Retrieve order payments](https://www.commercengine.io/docs/api-reference/orders/retrieve-order-payments.md): Retrieve order payments
- [Create order return](https://www.commercengine.io/docs/api-reference/orders/create-order-return.md)
- [Retrieve order return detail](https://www.commercengine.io/docs/api-reference/orders/retrieve-order-return-detail.md)
- [Cancel an order](https://www.commercengine.io/docs/api-reference/orders/cancel-order.md): Cancels an order and initiates a refund for any captured payment. Returns the updated `OrderDetail` object.
- [Cancel payment request](https://www.commercengine.io/docs/api-reference/orders/cancel-payment-request.md): Use when the express checkout payment flow is used and the user wants to switch payment methods (e.g. started with UPI, then chose another). Without this call, the user must wait until the payment-status API returns `status: failed` and `is_retry_available: true` (typically ~3 minutes). Calling this…
- [Retry payment](https://www.commercengine.io/docs/api-reference/orders/retry-payment.md): To generate new payment request if first payment request is failed or expired. Retry payment request can be made after 15 mins of last request or immediately after last payment request is marked as failed.
- [Retrieve all order returns](https://www.commercengine.io/docs/api-reference/orders/retrieve-all-order-returns.md)

#### Payments

- [List all payment methods](https://www.commercengine.io/docs/api-reference/payments/list-all-payment-methods.md): List all payment methods
- [Verify VPA](https://www.commercengine.io/docs/api-reference/payments/verify-vpa.md): The Virtual Payment Address or VPA is a unique ID given to an individual using the Unified Payment Interface (UPI) service to send or receive money. In the case of UPI collect VPA is the mandatory param and merchants are always advised to check if the VPA is valid or not. Validating the VPA will hel…
- [Authenticate direct OTP](https://www.commercengine.io/docs/api-reference/payments/authenticate-direct-otp.md): Authenticate direct OTP
- [Resend direct OTP](https://www.commercengine.io/docs/api-reference/payments/resend-direct-otp.md): Resend direct OTP
- [Get card information](https://www.commercengine.io/docs/api-reference/payments/get-card-information.md): Retrieve card information based on the initial 9 digits (card BIN) of the card number.

##### PayU (Integration)

- [Generate hash](https://www.commercengine.io/docs/api-reference/payu/generate-hash.md): Generate PayU hash

##### Juspay (Integration)

- [Create order in juspay](https://www.commercengine.io/docs/api-reference/juspay/create-order-in-juspay.md): Creates an order in the Juspay system and fetches the corresponding client_auth_token. To be used for Express Checkout integration.
- [Create customer in juspay](https://www.commercengine.io/docs/api-reference/juspay/create-customer-in-juspay.md): Create customer in juspay.
- [Retrieve customer from juspay](https://www.commercengine.io/docs/api-reference/juspay/retrieve-customer-from-juspay.md)

#### Subscriptions

- [List all subscriptions](https://www.commercengine.io/docs/api-reference/subscriptions/list-all-subscriptions.md): List all subscriptions
- [Create subscription](https://www.commercengine.io/docs/api-reference/subscriptions/create-subscription.md): Creates a new subscription for a customer. Returns the created `SubscriptionDetail` object.
- [Retrieve subscription details](https://www.commercengine.io/docs/api-reference/subscriptions/retrieve-subscription-details.md): Retrieve subscription details
- [Update a specific subscription](https://www.commercengine.io/docs/api-reference/subscriptions/update-a-specific-subscription.md): Update a specific subscription

### 🙋 Customers

#### Auth

- [Create anonymous session](https://www.commercengine.io/docs/api-reference/auth/create-anonymous-session.md): Creates an anonymous user session with a persistent `user_id` for analytics and cart tracking. Returns an `AnonymousUser` object with `access_token` and `refresh_token`. Call this before any other authenticated endpoint for guest users.
- [Login with phone](https://www.commercengine.io/docs/api-reference/auth/login-with-phone.md): Sends an OTP to the user's phone number. Returns an `otp_token` to pass to the verify-otp endpoint. Set `register_if_not_exists` to `true` to auto-register new users on OTP verification.
- [Login with email](https://www.commercengine.io/docs/api-reference/auth/login-with-email.md): Sends an OTP to the user's email address. Returns an `otp_token` to pass to the verify-otp endpoint. Set `register_if_not_exists` to `true` to auto-register new users on OTP verification.
- [Login with WhatsApp](https://www.commercengine.io/docs/api-reference/auth/login-with-whatsapp.md): Sends an OTP to the user's WhatsApp number. Returns an `otp_token` to pass to the verify-otp endpoint. Set `register_if_not_exists` to `true` to auto-register new users on OTP verification.
- [Login with password](https://www.commercengine.io/docs/api-reference/auth/login-with-password.md): Authenticates a user with email/phone and password. Returns a `User` object with `access_token` and `refresh_token`.
- [Verify OTP](https://www.commercengine.io/docs/api-reference/auth/verify-otp.md): Verifies the OTP sent via phone, email, or WhatsApp. On success, returns a `User` object with `access_token` and `refresh_token`. Pass the `otp_token` and `otp_action` received from the login endpoint.
- [Register with phone](https://www.commercengine.io/docs/api-reference/auth/register-with-phone.md): Registers a new user with their phone number. Returns a `User` object with `access_token` and `refresh_token`.
- [Register with email](https://www.commercengine.io/docs/api-reference/auth/register-with-email.md): Registers a new user with their email address. Returns a `User` object with `access_token` and `refresh_token`.
- [Register with WhatsApp](https://www.commercengine.io/docs/api-reference/auth/register-with-whatsapp.md): Registers a new user with their WhatsApp number. Returns a `User` object with `access_token` and `refresh_token`.
- [Register with password](https://www.commercengine.io/docs/api-reference/auth/register-with-password.md): Registers a new user with email/phone and password. Returns a `User` object with `access_token` and `refresh_token`.
- [Retrieve a user](https://www.commercengine.io/docs/api-reference/auth/retrieve-a-user.md): Retrieves the full `User` object for a given user ID.
- [Update a user](https://www.commercengine.io/docs/api-reference/auth/update-a-user.md): Updates user profile details. Returns the updated `User` object.
- [Delete a user](https://www.commercengine.io/docs/api-reference/auth/delete-a-user.md): Deletes a user account. If the user is a primary user, deletes the associated customer and all linked users. If the user is a normal user, deletes only that user without affecting the customer or other users.
- [Retrieve a profile image](https://www.commercengine.io/docs/api-reference/auth/retrieve-a-profile-image.md): Retrieves the `profile_image_url` for the user.
- [Update profile image](https://www.commercengine.io/docs/api-reference/auth/update-profile-image.md): Replaces the existing profile image. Returns the updated `profile_image_url`.
- [Add profile image](https://www.commercengine.io/docs/api-reference/auth/add-profile-image.md): Uploads a profile image for the user. Returns the `profile_image_url`.
- [Delete profile image](https://www.commercengine.io/docs/api-reference/auth/delete-profile-image.md): Removes the profile image from the user account.
- [Deactivate account](https://www.commercengine.io/docs/api-reference/auth/deactivate-account.md): Deactivates the user's account.
- [Refresh access token](https://www.commercengine.io/docs/api-reference/auth/refresh-access-token.md): Exchanges a `refresh_token` for a new `access_token` and `refresh_token` pair. Use this to extend user sessions without re-authentication.
- [Change password](https://www.commercengine.io/docs/api-reference/auth/change-password.md): Changes the authenticated user's password. Requires the current password and the new password.
- [Forgot password](https://www.commercengine.io/docs/api-reference/auth/forgot-password.md): Initiates password recovery by sending an OTP. Returns an `otp_token` to pass to the reset-password endpoint.
- [Reset password](https://www.commercengine.io/docs/api-reference/auth/reset-password.md): Resets the user's password using the `otp_token` from the forgot-password endpoint. Returns new `access_token` and `refresh_token`.
- [Retrieve user notification preferences](https://www.commercengine.io/docs/api-reference/auth/retrieve-user-notification-preferences.md)
- [Update user notification preferences](https://www.commercengine.io/docs/api-reference/auth/update-user-notification-preferences.md)
- [Create user notification preferences](https://www.commercengine.io/docs/api-reference/auth/create-user-notification-preferences.md)
- [Generate OTP](https://www.commercengine.io/docs/api-reference/auth/generate-otp.md): Generates and sends an OTP for authentication or verification. Returns an `otp_token` to pass to the verify-otp endpoint.
- [Logout user](https://www.commercengine.io/docs/api-reference/auth/logout-user.md): Invalidates the current session and logs the user out.
- [Check email/phone verification status](https://www.commercengine.io/docs/api-reference/auth/check-emailphone-verification-status.md): Checks whether the user's email and phone number have been verified.

#### Customers

- [List all saved cards](https://www.commercengine.io/docs/api-reference/customers/list-all-saved-cards.md): Retrieve a list of saved payment cards for a given customer.
- [List all saved payment methods](https://www.commercengine.io/docs/api-reference/customers/list-all-saved-payment-methods.md): This endpoint acts as a proxy for JusPay's Fetch Saved Payment Methods API. It enables to securely retrieve a list of payment methods (such as saved cards, UPI handles, wallets) that have been previously stored for a given customer.
- [Retrieve all addresses](https://www.commercengine.io/docs/api-reference/customers/retrieve-all-addresses.md)
- [Create address](https://www.commercengine.io/docs/api-reference/customers/create-address.md)
- [Retrieve particular address](https://www.commercengine.io/docs/api-reference/customers/retrieve-particular-address.md)
- [Update particular address](https://www.commercengine.io/docs/api-reference/customers/update-particular-address.md)
- [Remove particular address](https://www.commercengine.io/docs/api-reference/customers/remove-particular-address.md)
- [Retrieve loyalty details](https://www.commercengine.io/docs/api-reference/customers/retrieve-loyalty-details.md)
- [List all loyalty points activity](https://www.commercengine.io/docs/api-reference/customers/list-all-loyalty-points-activity.md)
- [Retrieve all reviews](https://www.commercengine.io/docs/api-reference/customers/retrieve-all-reviews.md)

#### KYC

- [List all kyc documents](https://www.commercengine.io/docs/api-reference/kyc/list-all-kyc-documents.md): List all kyc documents
- [List all documents](https://www.commercengine.io/docs/api-reference/kyc/list-all-documents.md): List all documents
- [Create document](https://www.commercengine.io/docs/api-reference/kyc/create-document.md): Create document
- [Retrieve document detail](https://www.commercengine.io/docs/api-reference/kyc/retrieve-document-detail.md): Retrieve document detail
- [Update document detail](https://www.commercengine.io/docs/api-reference/kyc/update-document-detail.md): Update document detail
- [Delete document](https://www.commercengine.io/docs/api-reference/kyc/delete-document.md): Delete document
- [Verify document](https://www.commercengine.io/docs/api-reference/kyc/verify-document.md)

### 🎟️ Engagement & Retention

#### Campaigns

- [Subscribe to newsletter](https://www.commercengine.io/docs/api-reference/campaigns/subscribe-to-newsletter.md): Subscribe to newsletter

#### Analytics

- [Track event](https://www.commercengine.io/docs/api-reference/analytics/track-event.md): Track event

### 🧰 Utilities

#### Common

- [Retrieve all countries](https://www.commercengine.io/docs/api-reference/common/retrieve-all-countries.md): Retrieve all countries
- [Retrieve country wise states](https://www.commercengine.io/docs/api-reference/common/retrieve-country-wise-states.md): Retrieve country wise states
- [Retrieve pincodes](https://www.commercengine.io/docs/api-reference/common/retrieve-pincodes.md): Retrieve pincodes

### Store Config

- [Check store existence](https://www.commercengine.io/docs/api-reference/store/check-store-existence.md): Checks whether a store with the given ID exists. Returns `success: true` if the store exists, `false` otherwise.
- [Retrieve store config](https://www.commercengine.io/docs/api-reference/store/retrieve-store-config.md): Retrieve store config

### Marketplace

#### Catalog

- [List all products](https://www.commercengine.io/docs/api-reference/marketplace/list-all-products.md): list all products
- [List all SKUs](https://www.commercengine.io/docs/api-reference/marketplace/list-all-skus.md): Returns a list of SKUs. The SKUs are returned sorted by creation date, with the most recently created SKUs appearing first.
- [Retrieve a product detail](https://www.commercengine.io/docs/api-reference/marketplace/retrieve-a-product-detail.md)
- [Retrieve product variants](https://www.commercengine.io/docs/api-reference/marketplace/retrieve-product-variants.md): Retrieves the variants of an existing marketplace product. Product slug is supported in place of product ID in the path. Commerce Engine returns the corresponding product variants information.
- [Retrieve variant detail](https://www.commercengine.io/docs/api-reference/marketplace/retrieve-variant-detail.md): Retrieves the details of a particular marketplace variant. Product slug is supported in place of product ID, and variant slug in place of variant ID, in the path.
- [List all categories](https://www.commercengine.io/docs/api-reference/marketplace/list-all-categories.md): Returns a list of your product categories. The categories are returned sorted by creation date, with the most recently created categories appearing first.
- [List product reviews](https://www.commercengine.io/docs/api-reference/marketplace/list-all-product-reviews.md): List product reviews
- [Create product review](https://www.commercengine.io/docs/api-reference/marketplace/create-product-review.md)
- [Retrieve similar products](https://www.commercengine.io/docs/api-reference/marketplace/retrieve-similar-products.md): Retrieves a list of products similar to a specified product based on their attributes and category. The similar products are returned sorted by relevance, with the most closely matching products appearing first. Useful for providing product recommendations to your customers.
- [Retrieve up-sell products](https://www.commercengine.io/docs/api-reference/marketplace/retrieve-up-sell-products.md): Retrieves a list of products specified for upsell. The upsell products are returned based on product ids specified in request param.
- [Retrieve cross-sell products](https://www.commercengine.io/docs/api-reference/marketplace/retrieve-cross-sell-products.md): Retrieves a list of products specified for cross selling. The cross-sell products are returned based on product ids specified in request param.
- [Search products](https://www.commercengine.io/docs/api-reference/marketplace/search-products.md): Search for products matching a specific words or characters given.

#### Seller Management

- [Retrieve seller detail](https://www.commercengine.io/docs/api-reference/store/retrieve-seller-detail.md): Retrieve seller detail by ID
- [List seller reviews](https://www.commercengine.io/docs/api-reference/store/list-seller-reviews.md): List seller reviews by seller ID