Create Cart
Endpoint: POST /carts
Purpose
This endpoint creates a new cart session by adding a product with customer and address information. It calculates totals, taxes, discounts, and handles product configurations and coupons.
Path Parameters
This endpoint does not require any path parameters.
Query Parameters
This endpoint does not require any query parameters.
Use Case
This is used when a customer adds a product to their cart, either from the frontend store or backend system. The API calculates cart totals, applies coupon discounts if valid, and prepares the cart for checkout or further modifications.
Request Body
| Parameter | Type | Description |
|---|---|---|
| customer_id | string | Unique identifier of the customer adding items to the cart. |
| product_id | string | Unique identifier of the product being added to the cart. |
| config | object / JSON | Configuration details (e.g., selected options, variants, customizations). |
| quantity | integer | Number of units of the product to add to the cart. |
{
"customer_id": CUSTOMER_ID,
"billing_address": {
"first_name": "FIRST_NAME",
"last_name": "LAST_NAME",
"address_line_1": "ADDRESS_LINE_1",
"address_line_2": "ADDRESS_LINE_2",
"city": "CITY",
"post_code": "POST_CODE",
"country_id": "COUNTRY_ID",
"state_id": STATE_ID,
"email": "EMAIL"
},
"shipping_address": {
"first_name": "FIRST_NAME",
"last_name": "LAST_NAME",
"address_line_1": "ADDRESS_LINE_1",
"address_line_2": "ADDRESS_LINE_2",
"city": "CITY",
"post_code": "POST_CODE",
"country_id": "COUNTRY_ID",
"state_id": STATE_ID,
"email": "EMAIL",
"ip_address": "IP_ADDRESS"
},
"session_id": "SESSION_ID",
"product_id": "PRODUCT_ID",
"config": {
"variation": VARIATION_ID
},
"coupon_code": "COUPON_CODE",
"quantity": "QUANTITY"
}
Response
The response includes a fully populated cart object with totals, items, discount breakdowns, shipping info, and error messages (if any, e.g., invalid coupon). This helps the client application display cart status and guide the customer through checkout.
{
"cart": {
"customer_id": CUSTOMER_ID,
"session_id": "SESSION_ID",
"currency_code": "CURRENCY_CODE",
"currency_symbol": "CURRENCY_SYMBOL",
"delivery_type": "DELIVERY_TYPE",
"totals": {
"subtotal": SUBTOTAL_AMOUNT,
"discount": DISCOUNT_AMOUNT,
"shipping_discount": SHIPPING_DISCOUNT,
"tax": TAX_AMOUNT,
"total": TOTAL_AMOUNT,
"grand_total": GRAND_TOTAL,
"paid": PAID_AMOUNT
},
"shipping": {
"cost": SHIPPING_COST,
"handling_fee": HANDLING_FEE,
"handling_tax": HANDLING_TAX,
"shipping_tax": SHIPPING_TAX,
"total_tax": TOTAL_SHIPPING_TAX
},
"items": [
{
"id": CART_ITEM_ID,
"quantity": ITEM_QUANTITY,
"variations": [
"VARIATION_DESCRIPTION_1",
"VARIATION_DESCRIPTION_2"
],
"taxable": IS_TAXABLE,
"shippable": IS_SHIPPABLE,
"pricing": {
"unit_price": UNIT_PRICE,
"display_unit_price": DISPLAY_PRICE,
"total": ITEM_TOTAL,
"discount": ITEM_DISCOUNT,
"discount_tax": DISCOUNT_TAX,
"tax": TAX
},
"product": {
"id": PRODUCT_ID,
"sku": "PRODUCT_SKU",
"base_price": BASE_PRICE,
"available_stock": AVAILABLE_STOCK,
"on_sale": ON_SALE,
"cost_price": COST_PRICE,
"sale_price": SALE_PRICE,
"url": "PRODUCT_URL",
"name": "PRODUCT_NAME",
"product_type": "PRODUCT_TYPE",
"image_link": "PRODUCT_IMAGE_URL"
}
}
],
"discount": {
"discount": DISCOUNT_AMOUNT,
"order_discount": ORDER_DISCOUNT,
"shipping_discount": SHIPPING_DISCOUNT,
"discount_on_tax": TAX_DISCOUNT,
"discount_on_shipping_tax": SHIPPING_TAX_DISCOUNT
},
"messages": {
"discount": {
"message": "DISCOUNT_MESSAGE",
"status": "DISCOUNT_STATUS"
}
}
}
}
Preview Gift Card Application to Cart
Endpoint: POST /carts/{session_id}/gift-cards/preview
Purpose
This endpoint allows you to preview the application of a gift card to a specific cart session before finalizing it. It checks whether the gift card is valid and calculates the amount that can be redeemed against the cart total.
Path Parameters
| Field | Type | Description |
|---|---|---|
| session_id | string | The unique session identifier of the cart |
Query Parameters
This endpoint does not require any query parameters.
Use Case
A customer enters a gift card code during checkout, and the system previews whether it is valid and how much of the cart total it will cover. This provides user feedback before confirming the use of the gift card.
Request Body
| Parameter | Type | Description |
|---|---|---|
| customer_id | string | Unique identifier of the customer previewing the gift card. |
| gift_card_code | string | Code of the gift card to be applied or previewed. |
| payment_gateway | string | Payment gateway selected for processing the gift card transaction. |
{
"customer_id": CUSTOMER_ID,
"gift_card_code": "GIFT_CARD_CODE",
"payment_gateway": "GIFT_CARD_GATEWAY"
}
Response
The response confirms the status of the gift card (valid or invalid), includes a message for the customer, and displays the amount that can be applied to the cart. This helps determine how much the gift card will reduce the cart total.
{
"gift_card": {
"redeem_status": "REDEEM_STATUS", // e.g., success, failed
"redeem_message": "REDEEM_MESSAGE", // e.g., Gift Card Successfully Applied
"applicable_amount": REDEEMABLE_AMOUNT // e.g., 375.0
}
}
Create Order from Cart
Endpoint: POST /orders/carts/{session_id}
Purpose
This endpoint creates an order from a cart session, applying any selected gift card and payment gateway. It finalizes the cart into an order, ready for payment processing or fulfillment.
Path Parameters
|
Field |
Type |
Description |
|---|---|---|
|
session_id |
string |
The unique identifier of the cart session being converted into an order |
Query Parameters
This endpoint does not require any query parameters
Use Case
A customer proceeds to checkout using a cart session, optionally applying a gift card. This API is used to finalize the order, generate an order record, and prepare for payment completion or shipping.
Request Body
| Parameter | Type | Description |
|---|---|---|
| customer_id | string | Unique identifier of the customer previewing the gift card. |
| gift_card_code | string | Code of the gift card to be applied or previewed. |
| payment_gateway | string | Payment gateway selected for processing the gift card transaction. |
{
"customer_id": CUSTOMER_ID,
"gift_card": "GIFT_CARD_CODE",
"payment_gateway": "GATEWAY_CODE"
}Response
The response returns a success status along with the newly created order object. It includes all order-related details like totals, customer summary, items, and payment status. The applied gift card and payment gateway are reflected in the payment section of the order.
{
"status": "success",
"order": {
"order_id": ORDER_ID,
"order_status": "ORDER_STATUS",
"sub_total": SUBTOTAL,
"shipping_cost": SHIPPING_COST,
"shipping_tax": SHIPPING_TAX,
"handling_cost": HANDLING_COST,
"total_surcharge": TOTAL_SURCHARGE,
"total_discount": TOTAL_DISCOUNT,
"total_tax": TOTAL_TAX,
"grand_total": GRAND_TOTAL,
"paid": PAID_AMOUNT,
"due": DUE_AMOUNT,
"items_total": TOTAL_ITEMS,
"payment_status": "PAYMENT_STATUS",
"ip_address": "CUSTOMER_IP",
"customer_summary": {
"first_name": "FIRST_NAME",
"last_name": "LAST_NAME",
"customer_group": "CUSTOMER_GROUP",
"gender": "GENDER",
"customer_id": CUSTOMER_ID,
"email": "EMAIL",
"address_line_1": "ADDRESS_LINE_1",
"address_line_2": "ADDRESS_LINE_2",
"city": "CITY",
"country": {
"id": COUNTRY_ID,
"name": "COUNTRY_NAME",
"code": "COUNTRY_CODE"
},
"state": {
"id": STATE_ID,
"name": "STATE_NAME",
"code": "STATE_CODE"
},
"post_code": "POST_CODE",
"phone": "PHONE",
"mobile": "MOBILE",
"fax": "FAX",
"company_name": "COMPANY_NAME"
},
"order_line_details": [
{
"item_id": ITEM_ID,
"product_name": "PRODUCT_NAME",
"product_id": PRODUCT_ID,
"quantity": QUANTITY,
"price": UNIT_PRICE,
"total_amount": TOTAL_AMOUNT,
"tax": TAX,
"discount": DISCOUNT,
"tax_discount": TAX_DISCOUNT,
"is_taxable": IS_TAXABLE,
"is_shippable": IS_SHIPPABLE
}
],
"payments": [
{
"id": PAYMENT_ID,
"status": "PAYMENT_STATUS",
"amount": PAYMENT_AMOUNT,
"track_info": "TRACKING_INFO",
"gateway_name": "GATEWAY_NAME",
"gateway_code": "GATEWAY_CODE",
"gateway_response": "GATEWAY_RESPONSE",
"payer_info": "PAYER_INFO",
"paying_date": "PAYMENT_DATE"
}
]
}
}
