# Commerce Engine Docs: API Reference

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

## API Reference

- [API Reference / Storefront API (128 pages)](https://www.commercengine.io/docs/_llms/api-reference/storefront-api.md): Everything a storefront calls — catalog, cart, checkout, auth, orders.
- [API Reference / Webhooks (118 pages)](https://www.commercengine.io/docs/_llms/api-reference/webhooks.md): Events Commerce Engine delivers to your endpoints — orders, payments, shipments, catalog, customers, store and marketplace.
- [API Reference / Admin API (372 pages)](https://www.commercengine.io/docs/_llms/api-reference/admin-api.md): Back-office operations — catalog management, customers, fulfilment, store settings.

### POS API

#### Introduction

- [POS API](https://www.commercengine.io/docs/api-reference/pos/overview.md): The point-of-sale surface — staff login, device pairing, carts, catalog, order capture and the back-office lookups a till needs, all on the storefront base URL.

#### 🧾 Point of Sale

##### Authentication

- [Login with email](https://www.commercengine.io/docs/api-reference/pos/login-with-email.md): Login to POS device using email. Login to POS device using phone.  The endpoint requires authentication with an API key that has the scope set to 'storefront' for a particular store, ensuring secure access for user login operation.
- [Login with phone](https://www.commercengine.io/docs/api-reference/pos/login-with-phone.md): Login to POS device using phone.  The endpoint requires authentication with an API key that has the scope set to 'storefront' for a particular store, ensuring secure access for user login operation.
- [Login with whatsapp](https://www.commercengine.io/docs/api-reference/pos/login-with-whatsapp.md): Login to POS device using whatsapp. Login to POS device using phone.  The endpoint requires authentication with an API key that has the scope set to 'storefront' for a particular store, ensuring secure access for user login operation.
- [Verify OTP](https://www.commercengine.io/docs/api-reference/pos/verify-otp.md): Verify POS login otp. Login to POS device using phone.  The endpoint requires authentication with an API key that has the scope set to 'storefront' for a particular store.
- [Logout](https://www.commercengine.io/docs/api-reference/pos/logout.md): This endpoint ends the current loggedin session for the POS device. This action immediately invalidates the previously issued access token(s), preventing any further use. A new login is required to regain access.
- [Get POS User](https://www.commercengine.io/docs/api-reference/pos/get-pos-user.md): Get POS User

##### Devices

- [Pair POS device](https://www.commercengine.io/docs/api-reference/pos/pair-pos-device.md): This endpoint allows a POS device to be activated by submitting a valid pairing code received via phone or email. The endpoint requires authentication with an API key that has the scope set to 'storefront' for a particular store, ensuring secure access for device activation operation.
- [Refresh POS access token](https://www.commercengine.io/docs/api-reference/pos/refresh-pos-access-token.md): Refresh POS access token
- [List all available devices](https://www.commercengine.io/docs/api-reference/pos/list-all-available-devices.md): List all available devices.
- [Claim device](https://www.commercengine.io/docs/api-reference/pos/claim-device.md): Claim device
- [Unclaim device](https://www.commercengine.io/docs/api-reference/pos/unclaim-device.md): Unclaim device

##### Carts

- [Create cart](https://www.commercengine.io/docs/api-reference/pos/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 by user ID](https://www.commercengine.io/docs/api-reference/pos/retrieve-cart-by-user-id.md): Retrieves the active `Cart` object for a given user. Use the `user_id` returned from auth endpoints.
- [Retrieve cart detail](https://www.commercengine.io/docs/api-reference/pos/retrieve-cart-detail.md): Retrieves the full `Cart` object for the given cart ID.
- [Delete cart](https://www.commercengine.io/docs/api-reference/pos/delete-cart.md): delete all items from the cart.
- [Add, update, or remove a cart item](https://www.commercengine.io/docs/api-reference/pos/add-update-or-remove-a-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/pos/set-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.
- [Update cart customer](https://www.commercengine.io/docs/api-reference/pos/update-cart-customer.md): Link customer to the specified cart.

##### Coupons & Promotions

- [Retrieve all coupons](https://www.commercengine.io/docs/api-reference/pos/retrieve-all-coupons.md): Retrieve active coupons
- [Retrieve all promotions](https://www.commercengine.io/docs/api-reference/pos/retrieve-all-promotions.md): All active promotions
- [Apply coupon](https://www.commercengine.io/docs/api-reference/pos/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/pos/remove-coupon.md): Removes the applied coupon from the cart. Returns a fully updated `Cart` object with recalculated totals.
- [Evaluate coupons](https://www.commercengine.io/docs/api-reference/pos/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/pos/evaluate-promotions.md): Evaluates all promotions against the current cart contents. Returns separate `applicable_promotions` and `inapplicable_promotions` arrays with eligibility reasons.

##### Loyalty & Credits

- [Redeem loyalty points](https://www.commercengine.io/docs/api-reference/pos/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/pos/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/pos/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/pos/remove-credit-balance.md): Removes applied credit balance from the cart. Returns a fully updated `Cart` object with recalculated totals.

##### Catalog

- [List all categories](https://www.commercengine.io/docs/api-reference/pos/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 all products](https://www.commercengine.io/docs/api-reference/pos/list-all-products.md): Returns a paginated list of `Product` objects sorted by creation date (newest first). Pass `x-customer-group-id` header to retrieve group-specific pricing.
- [Search products](https://www.commercengine.io/docs/api-reference/pos/search-products.md): Search for products matching a specific words or characters given.
- [Retrieve a product detail](https://www.commercengine.io/docs/api-reference/pos/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/pos/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/pos/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 SKUs](https://www.commercengine.io/docs/api-reference/pos/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.

##### Product Recommendations

- [Retrieve similar products](https://www.commercengine.io/docs/api-reference/pos/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/pos/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/pos/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.

##### Fulfillment & Shipping

- [Retrieve fulfillment options](https://www.commercengine.io/docs/api-reference/pos/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.
- [Update fulfillment preference](https://www.commercengine.io/docs/api-reference/pos/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`.
- [List all locations](https://www.commercengine.io/docs/api-reference/pos/list-all-locations.md): List all locations.

##### Orders & Payments

- [Create POS order](https://www.commercengine.io/docs/api-reference/pos/create-pos-order.md): Creates an order from a POS cart. Returns an `Order` with `payment_required` and `payment_info`. Include `payment_method` to create an initial payment request.
- [Retrieve payment status](https://www.commercengine.io/docs/api-reference/pos/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.
- [Create POS order payment](https://www.commercengine.io/docs/api-reference/pos/create-pos-order-payment.md): Creates a payment request for a POS order. Use this when the order was created without `payment_method` or when collecting the remaining `to_be_paid` amount with another method.
- [Retry payment](https://www.commercengine.io/docs/api-reference/pos/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.

##### Payment Methods

- [List all payment methods](https://www.commercengine.io/docs/api-reference/pos/list-all-payment-methods.md): List all payment methods
- [Verify VPA](https://www.commercengine.io/docs/api-reference/pos/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…
- [Get card information](https://www.commercengine.io/docs/api-reference/pos/get-card-information.md): Retrieve card information based on the initial 9 digits (card BIN) of the card number.
- [Authenticate direct OTP](https://www.commercengine.io/docs/api-reference/pos/authenticate-direct-otp.md): Authenticate direct OTP
- [Resend direct OTP](https://www.commercengine.io/docs/api-reference/pos/resend-direct-otp.md): Resend direct OTP

##### Common

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

#### 🗄️ Back office (proxied to Admin)

##### Orders

- [List all orders](https://www.commercengine.io/docs/api-reference/posadmin/list-all-orders.md): List all orders
- [Retrieve order details](https://www.commercengine.io/docs/api-reference/posadmin/retrieve-order-details.md): Retrieve order details
- [List all order activity](https://www.commercengine.io/docs/api-reference/posadmin/list-all-order-activity.md): List all order activity
- [Retrieve order shipments](https://www.commercengine.io/docs/api-reference/posadmin/retrieve-order-shipments.md): Retrieve order shipments
- [Check inventory](https://www.commercengine.io/docs/api-reference/posadmin/check-inventory.md): Verifies stock availability for an order's unscheduled or store_rejected shipment before it is scheduled.
- [Retrieve order invoice](https://www.commercengine.io/docs/api-reference/posadmin/retrieve-order-invoice.md): Retrieve order invoice
- [Retrieve order receipt](https://www.commercengine.io/docs/api-reference/posadmin/retrieve-order-receipt.md): Retrieves a printable receipt for a specific order using the order number. This endpoint returns either structured JSON data or a formatted PDF, suitable for customer presentation. Response format (JSON or PDF) is determined by an optional query parameter (e.g. format=pdf or format=json).

##### Shipments

- [List all shipments](https://www.commercengine.io/docs/api-reference/posadmin/list-all-shipments.md): List all shipments
- [Retrieve shipment detail](https://www.commercengine.io/docs/api-reference/posadmin/retrieve-shipment-detail.md): Retrieve shipment detail
- [Retrieve shipment activities](https://www.commercengine.io/docs/api-reference/posadmin/retrieve-shipment-activities.md): Retrieve shipment activities
- [Retrieve shipment invoice](https://www.commercengine.io/docs/api-reference/posadmin/retrieve-shipment-invoice.md): Retrieve shipment invoice
- [Update shipment detail](https://www.commercengine.io/docs/api-reference/posadmin/update-shipment-detail.md): Update shipment detail
- [Create a replacement shipment](https://www.commercengine.io/docs/api-reference/posadmin/create-a-replacement-shipment.md): Creates a replacement shipment against an existing shipment. Use the `manual` payload to dispatch outside an integrated carrier, or the `auto` payload to fulfill through an integrated carrier with system-managed packing and rates.
- [Refund shortfall](https://www.commercengine.io/docs/api-reference/posadmin/refund-shortfall.md): Refund shortfall

##### Customers

- [List all customers](https://www.commercengine.io/docs/api-reference/posadmin/list-all-customers.md): List all customers
- [Retrieve customer detail](https://www.commercengine.io/docs/api-reference/posadmin/retrieve-customer-detail.md): Retrieves the full `CustomerDetail` object, including `business`, `segments`, `addresses`, `banking`, `loyalty`, `notification_preferences`, and the assigned `customer_group_id`.
- [List all addresses](https://www.commercengine.io/docs/api-reference/posadmin/list-all-addresses.md): List all addresses
- [Create address](https://www.commercengine.io/docs/api-reference/posadmin/create-address.md): Create address
- [Update address detail](https://www.commercengine.io/docs/api-reference/posadmin/update-address-detail.md): Update address detail
- [Delete address](https://www.commercengine.io/docs/api-reference/posadmin/delete-address.md): Delete address

##### Inventory

- [List all inventories](https://www.commercengine.io/docs/api-reference/posadmin/list-all-inventories.md): List all inventories
- [Retrieve inventory detail](https://www.commercengine.io/docs/api-reference/posadmin/retrieve-inventory-detail.md): Retrieves inventory details for a specific product, product variant, or lot/batch based on the parameters provided.
- [List all inventories activities](https://www.commercengine.io/docs/api-reference/posadmin/list-all-inventories-activities.md): Lists all inventory related activities of stock movements. This provides a comprehensive audit trail of inventory operations such as receiving, reservations, adjustments, transfers, and sales.

## OpenAPI Specs

- [ce-pos](https://openapi.commercengine.io/ce-pos.json)
- [ce-webhooks](https://openapi.commercengine.io/ce-webhooks.json)
- [ce-admin](https://openapi.commercengine.io/ce-admin.json)