Storefront and Orders API

Livepin sells trackers and accessories through a built-in storefront. Use these endpoints to build a purchase flow into your own portal — browse the catalogue, build a cart, place an order, and track fulfilment.

Product, category, and review read endpoints are public. Everything that touches a cart, an order, or a coupon requires credentials:

x-api-key: <YOUR_API_KEY>
Authorization: Bearer <JWT_TOKEN>

Carts and orders are scoped to the authenticated account, so when you call these with an API key they belong to the API key owner.

Product model

Name
id
Type
integer
Description
Internal product ID.
Name
title
Type
string
Description
Product name.
Name
slug
Type
string
Description
Required, unique. URL-safe identifier.
Name
gallery
Type
array
Description
Product images and videos.
Name
basePrice
Type
integer
Description
Base price before option modifiers.
Name
tags
Type
text
Description
Free-text search tags.
Name
hsn_code
Type
string
Description
HSN classification. Defaults to 8526.
Name
features
Type
object
Description
Structured feature list.
Name
description
Type
richtext
Description
Long description.
Name
ecom_category
Type
object
Description
Category the product belongs to.
Name
ecom_product_attributes
Type
array
Description
Configurable attributes. Each has a name and repeatable options, where each option carries label, priceModifier, and isDefault.

Products

Name
GET /api/ecom-products
Description
List products. Public. Supports search, filtering, and sorting.
Name
GET /api/ecom-products/:id
Description
Get one product. Public.
Name
GET /api/ecom-products/slug/:slug
Description
Get one product by slug, with a rating summary. Public.
Name
GET /api/ecom-products/:id/related
Description
Related products from the same category. Public.
Name
GET /api/ecom-products/price-range
Description
Minimum and maximum base price across the catalogue. Public.
Name
POST /api/ecom-products/calculate-price
Description
Price for a product with a set of options selected. Public.

List query parameters

Name
query
Type
string
Description
Search title and tags.
Name
category
Type
integer
Description
Filter by category ID.
Name
min_price
Type
integer
Description
Minimum basePrice.
Name
max_price
Type
integer
Description
Maximum basePrice.
Name
sort
Type
string
Description
price_asc (default) or price_desc.
Name
page
Type
integer
Description
Default 1.
Name
limit
Type
integer
Description
Default 10.

List products

GET

/api/ecom-products

curl -G "$LIVEPIN_API_BASE_URL/api/ecom-products" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d query=truck \
  -d category=2 \
  -d min_price=100000 \
  -d max_price=500000 \
  -d sort=price_desc \
  -d page=1 \
  -d limit=10

selected_options is keyed by attribute ID. Each value is either an option ID or an object containing option_id.

Calculate price

POST

/api/ecom-products/calculate-price

curl -X POST "$LIVEPIN_API_BASE_URL/api/ecom-products/calculate-price" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 8,
    "selected_options": { "3": 11, "4": { "option_id": 15 } }
  }'

Price range

GET

/api/ecom-products/price-range

curl "$LIVEPIN_API_BASE_URL/api/ecom-products/price-range" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Cart

A cart holds line items for the authenticated account. Each line is a product plus a selected option set, so the same product can appear twice with different configurations.

Name
GET /api/ecom-carts/my-cart
Description
Read the cart without line items, with total_items.
Name
GET /api/ecom-carts/my-cart/items
Description
Read the cart with line items and any applied coupon.
Name
GET /api/ecom-carts/summary
Description
Read totals for the cart.
Name
POST /api/ecom-carts
Description
Add a line item.
Name
PUT /api/ecom-carts/:id
Description
Set the quantity of a line.
Name
DELETE /api/ecom-carts/:id
Description
Remove a line.

On PUT and DELETE /api/ecom-carts/:id the path parameter is the product ID, not the cart ID. There is no endpoint to apply a coupon to a cart.

Add a line item

Name
product_id
Type
integer
Description
Required.
Name
quantity
Type
integer
Description
Minimum 1. Defaults to 1.
Name
selected_options
Type
object
Description
Keyed by attribute ID. Defaults to {}.

Adding a product that is already in the cart with the same options increments its quantity.

Add to cart

POST

/api/ecom-carts

curl -X POST "$LIVEPIN_API_BASE_URL/api/ecom-carts" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"product_id":8,"quantity":2,"selected_options":{"3":11}}'

Cart summary

GET

/api/ecom-carts/summary

curl "$LIVEPIN_API_BASE_URL/api/ecom-carts/summary" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Totals are computed server-side: GST is 18% of the subtotal, and shipping is free above a subtotal of 5,000.

Set quantity

PUT

/api/ecom-carts/:id

curl -X PUT "$LIVEPIN_API_BASE_URL/api/ecom-carts/8" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quantity":3,"selected_options":{"3":11}}'

Remove a line

DELETE

/api/ecom-carts/:id

curl -X DELETE "$LIVEPIN_API_BASE_URL/api/ecom-carts/8" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Orders

Name
GET /api/ecom-orders
Description
List your orders.
Name
GET /api/ecom-orders/:id
Description
Get one order.
Name
POST /api/ecom-orders
Description
Create an order from a cart or a single product.
Name
PUT /api/ecom-orders/:id/cancel
Description
Cancel an order.
Name
PUT /api/ecom-orders/:id/return
Description
Return a delivered order.

Create fields

Name
cart_id
Type
integer
Description
Order everything in this cart. Send instead of product_id.
Name
product_id
Type
integer
Description
Order a single product. Requires quantity.
Name
quantity
Type
integer
Description
Used with product_id.
Name
selected_options
Type
object
Description
Used with product_id.
Name
payment_method
Type
enum
Description
COD or ONLINE. Anything other than COD is treated as ONLINE.
Name
customer_email
Type
string
Description
Optional contact email.
Name
billing_address
Type
object
Description
Address component.
Name
shipping_address
Type
object
Description
Address component.

Order model

Name
items
Type
array
Description
Line items.
Name
gross_amount
Type
integer
Description
Subtotal.
Name
tax_amount
Type
integer
Description
GST.
Name
shipping_amount
Type
integer
Description
Shipping. Defaults to 0.
Name
paymentStatus
Type
enum
Description
PENDING, COMPLETED, FAILED. Defaults to PENDING.
Name
shippingStatus
Type
enum
Description
PENDING_FULFILLMENT, PROCESSING, FULFILLED, SHIPPED, DELIVERED, CANCELED, RETURNED_TO_SENDER.
Name
paymentMethod
Type
enum
Description
COD or ONLINE.
Name
awb_code
Type
string
Description
Shiprocket AWB number once dispatched.
Name
invoice_pdf
Type
media
Description
Generated invoice.
Name
note
Type
text
Description
Cancellation or return note.

The body is flat — unlike the collection endpoints, do not wrap it in data.

Create order from cart

POST

/api/ecom-orders

curl -X POST "$LIVEPIN_API_BASE_URL/api/ecom-orders" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cart_id": 61,
    "payment_method": "ONLINE",
    "customer_email": "ops@example.com",
    "billing_address": {
      "first_name": "Jane",
      "last_name": "Doe",
      "address_line_1": "1 Main Street",
      "city": "Mumbai",
      "pin_code": "400001",
      "state": "Maharashtra",
      "country": "India"
    },
    "shipping_address": {
      "first_name": "Jane",
      "last_name": "Doe",
      "address_line_1": "1 Main Street",
      "city": "Mumbai",
      "pin_code": "400001",
      "state": "Maharashtra",
      "country": "India"
    }
  }'

List orders

GET

/api/ecom-orders

curl -G "$LIVEPIN_API_BASE_URL/api/ecom-orders" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d page=1 \
  -d limit=10

Cancel order

PUT

/api/ecom-orders/:id/cancel

curl -X PUT "$LIVEPIN_API_BASE_URL/api/ecom-orders/214/cancel" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"note":"Ordered by mistake"}'

Only orders in DELIVERED status can be returned.

Return order

PUT

/api/ecom-orders/:id/return

curl -X PUT "$LIVEPIN_API_BASE_URL/api/ecom-orders/214/return" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Device faulty on arrival"}'

Payment and tracking

Name
POST /api/ecom-orders/:id/initiate-payment
Description
Create a Razorpay order for an existing order.
Name
POST /api/ecom-orders/payment-webhook
Description
Razorpay callback. Public, protected by an HMAC signature.
Name
GET /api/ecom-orders/:id/track
Description
Shipment tracking for a dispatched order.

POST /api/ecom-orders/payment-webhook is called by Razorpay, not by your application. The signature header is x-razorpay-signature, verified against your webhook secret. It marks orders COMPLETED or FAILED based on the payment.captured and payment.failed events.

Initiate payment

POST

/api/ecom-orders/:id/initiate-payment

curl -X POST "$LIVEPIN_API_BASE_URL/api/ecom-orders/214/initiate-payment" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cart_id":61}'

amount is in the smallest currency unit. Always take the amount from this response rather than recalculating it on the client.

Track order

GET

/api/ecom-orders/:id/track

curl "$LIVEPIN_API_BASE_URL/api/ecom-orders/214/track" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Reviews

Name
GET /api/ecom-reviews/product/:productId
Description
Approved reviews for a product. Public.
Name
GET /api/ecom-reviews/product/:productId/summary
Description
Aggregate rating and distribution. Public.
Name
POST /api/ecom-reviews
Description
Create a review.
Name
PUT /api/ecom-reviews/:id
Description
Edit your own review.
Name
DELETE /api/ecom-reviews/:id
Description
Delete your own review.

A new review is published immediately. Editing a review returns it to moderation. Reviewer email addresses are never returned — the response includes a Gravatar URL derived from the email hash instead.

Rating summary

GET

/api/ecom-reviews/product/:productId/summary

curl "$LIVEPIN_API_BASE_URL/api/ecom-reviews/product/8/summary" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Create review

POST

/api/ecom-reviews

curl -X POST "$LIVEPIN_API_BASE_URL/api/ecom-reviews" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"product_id":8,"rating":5,"comment":"Reliable unit, easy install."}'

List reviews

GET

/api/ecom-reviews/product/:productId

curl -G "$LIVEPIN_API_BASE_URL/api/ecom-reviews/product/8" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d page=1 \
  -d limit=10

Coupons

Name
GET /api/ecom-coupons
Description
List coupons.
Name
GET /api/ecom-coupons/:id
Description
Look up an active coupon by code, for example SAVE10.

Coupon fields

Name
code
Type
string
Description
Coupon code.
Name
description
Type
text
Description
Customer-facing description.
Name
active
Type
boolean
Description
Defaults to true.
Name
discountType
Type
enum
Description
AMOUNT or PERCENTAGE.
Name
discountAmount
Type
integer
Description
Discount value.
Name
remainingCoupons
Type
integer
Description
Redemption budget. Defaults to 100.
Name
minOrderAmount
Type
integer
Description
Minimum subtotal. Defaults to 1000.

Look up a coupon by code

curl "$LIVEPIN_API_BASE_URL/api/ecom-coupons/SAVE10" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Response

{
  "id": 4,
  "code": "SAVE10",
  "description": "10% off",
  "active": true,
  "discountType": "PERCENTAGE",
  "discountAmount": 10,
  "remainingCoupons": 42,
  "minOrderAmount": 1000
}

Storefront and Orders API

Product model

Products

List query parameters

List products

Calculate price

Price range

Categories

Category fields

List categories

Response (trimmed)

Cart

Add a line item

Add to cart

Cart summary

Set quantity

Remove a line

Orders

Create fields

Order model

Create order from cart

List orders

Cancel order

Return order

Payment and tracking

Initiate payment

Track order

Reviews

Rating summary

Create review

List reviews

Coupons

Coupon fields

Look up a coupon by code

Response