This guide walks you through the process of converting a customer’s shopping cart into a placed order, including address validation, shipping checks, payment processing, and handling payment retries. It utilizes endpoints primarily from the Carts, Orders, Payments, Shipping, and Common modules.
cart_id
representing the customer’s cart with items added.access_token
), which can be for an anonymous or logged-in user.GET /carts/{cart_id}
or GET /carts/users/{user_id}
cart_items
, pricing breakdown (subtotal
, tax
, shipping
, grand_total
), applied discounts (coupon_code
, loyalty_points_redeemed
, etc.), and the final to_be_paid
amount.GET /customers/{user_id}/addresses
.
POST /customers/{user_id}/addresses
).
POST /carts/{id}/address
:
GET /common/countries
, GET /common/countries/{country_iso_code}/states
, and GET /common/countries/{country_iso_code}/pincodes
(with query pincode=...&limit=1
) to potentially provide dropdowns or validate inputs for Country, State, and City based on Pincode.
POST /carts/{id}/address
:
POST /carts/{id}/address
call returns the updated Cart
object, which will now include potentially recalculated shipping_amount_including_tax
and grand_total
based on the destination. Re-render the cart summary if these values changed.GET /shipment/pincode-serviceability/{pincode}
pincode
(from the shipping address).200 OK
with success: true
: Delivery is available.4xx
Error (e.g., 404 or specific error code if defined): Delivery is not available. Display an appropriate message to the user, preventing them from proceeding with this address.Pincode Serviceability Check Flow
POST /carts/{id}/...
endpoints described in the Carts module documentation. Remember to handle potential errors (e.g., coupon requires login). Update the cart summary after each successful application.POST /orders
cart_id
: Required. The ID of the finalized cart.payment_gateway
: Required. "JUSPAY"
or "PAYU"
. (Juspay recommended).payment_gateway_params
: Required. An object containing parameters specific to the chosen gateway.JuspayPaymentGatewayParams
and PayuPaymentGatewayParams
schemas and potentially use helper endpoints like POST /payments/juspay/create-order
or POST /payments/generate-hash
(PayU) before this step if required by your chosen integration pattern. Hyper-Checkout simplifies this significantly.200 OK
):
message
, success
content
:
order
: The newly created OrderDetail
object (initial status likely ‘draft’ or similar, payment_status: 'pending'
). Contains the order_number
.payment_required
: Boolean (usually true
).payment_info
: An object containing instructions for the payment gateway. The structure depends on the chosen gateway (PayuPaymentInfo
or JuspayPaymentInfo
).payment_info
for Juspay Hyper-Checkout:
payment_info
for PayU:
payment_info
received:payment_info.payment_links.web
URL. Juspay handles the payment method selection and processing.payment_info
as a form POST to the PayU payment URL.payment_info
(e.g., sdk_payload
for mobile SDKs).return_url
(for Juspay Hyper-Checkout) or surl
/furl
(for PayU) that you provided during order creation.return_url
), the crucial step is to poll the Commerce Engine API to get the authoritative payment status for the order.GET /orders/{order_number}/payment-status
order_number
(obtained in Step 5 response).
return_url
.content.status
in the response.status
is success
: Payment is confirmed. Proceed to Step 9 (Confirmation).status
is failed
: Payment failed. Check content.is_retry_available
. Proceed to Step 9 (Failure/Retry).status
is pending
or partially_paid
: The payment outcome is not yet final. Wait for a short interval (e.g., 5 seconds) and repeat the API call (poll again). Continue polling until the status becomes success
or failed
, or until a reasonable timeout (e.g., 1-2 minutes) is reached.200 OK
):
GET /orders/{order_number}/payment-status
ensures you get the confirmed status directly from Commerce Engine, which manages gateway webhooks and status updates reliably on the backend.status
== success
:
GET /orders/{order_number}
).status
== failed
:
is_retry_available
:
true
: Display a “Payment Failed” message and offer a “Retry Payment” button. See “Handling Payment Retries” below.false
: Display an “Order Failed” message, explaining that payment could not be processed and potentially advising the customer to try again later or contact support. Do not offer an immediate retry.pending
): Display a message indicating the payment is still processing and advise the customer to check their order history later or contact support. Avoid confirming the order prematurely.is_retry_available
was true:POST /orders/{order_number}/retry-payment
.
order_number
.
POST /orders
, requires payment_gateway_params
to potentially re-initiate the gateway flow (e.g., providing return_url
again for Juspay).
POST /orders
, provides new payment_info
(e.g., a new Juspay payment_links.web
URL).
Checkout & Retry Flow (Juspay Hyper-Checkout)