API reference
The QwikStone API lets you build apps for stone, tile and machinery sellers — sync stock from an ERP, manage prices, read orders, run ads and reports, apply for QwikStone Merchandising and more.
The API is organised around REST. It has predictable resource URLs, accepts JSON request bodies, returns JSON responses and uses standard HTTP status codes and authentication.
There are two ways in: a seller uses their own API key for their own systems, or you register as a developer, create an app and sellers connect it with OAuth.
http://seller.qwikstone.com/api
# Any HTTP client works. Examples on this page:
cURL · Python (requests) · Node.js (fetch) · PHP (cURL)Authentication
Send a Bearer token in the Authorization header with every request. Requests without it fail with 401. All calls must use HTTPS.
| Token | Who uses it | Where to get it |
|---|---|---|
qs_live_… | A seller's own systems (ERP, stock app) | Seller Hub → Settings → Developer tools |
qs_at_… | Your app, acting for a seller who connected it | OAuth token endpoint (expires after 1 hour) |
Scopes
Every key and token carries scopes. Ask only for what your app needs.
listings:read | See your listings and stock |
listings:write | Create, change and archive listings |
inventory:write | Update stock and prices |
orders:read | See orders for your listings |
orders:write | Confirm stock is ready and record loading |
pricing:read | See the price build-up (fees and tax) |
ads:read | See campaigns, keywords and ad reports |
ads:write | Create and change campaigns, bids and budgets |
reports:read | Run business reports |
merch:read | See QwikStone Merchandising requests and bids |
merch:write | Apply for Merchandising and accept offers |
payments:read | See payouts, statements, invoices and charges |
brands:read | See your Brand Shield brands |
brands:write | Report brand violations |
webhooks:write | Create and delete webhook endpoints |
curl http://seller.qwikstone.com/api/v1/listings \ -H "Authorization: Bearer qs_live_YOUR_KEY"
Errors
Codes in the 2xx range mean success, 4xx means something about the request (a field, a missing scope, a plan limit) and 5xx means something went wrong at QwikStone — retry with backoff.
| Status | code | Meaning |
|---|---|---|
200 | — | OK |
201 | — | Created |
400 | invalid | A field is missing or wrong — the message says which (same wording as Seller Hub). |
401 | unauthorized | No key, or the key/token is unknown, revoked or expired. |
402 | plan_required | The seller's plan doesn't include the API or this feature (International and up). |
403 | forbidden | The key or token doesn't have the scope. |
404 | not_found | No such SKU, order or route. |
409 | conflict | The change isn't allowed right now, e.g. stock is booked by an order or sealed by Merchandising. |
429 | rate_limited | Too many requests — see rate limits. |
500 | — | Something went wrong at QwikStone. |
{
"error": {
"code": "invalid",
"message": "Thickness must be between 6 and 80 mm.",
"param": "thickness_mm",
"doc_url": "https://seller.qwikstone.com/docs/api#errors"
}
}Pagination
List calls return object: "list" with items, page, page_size (1–100, default 50), total and has_more. Ask for the next page until has_more is false.
{
"object": "list",
"items": [ … ],
"page": 2,
"page_size": 50,
"total": 132,
"has_more": true
}Rate limits & pricing
The API is included in the seller's plan from International upwards — there is no per-call charge for sellers, and registering as a developer and building apps is free. Limits apply per key or per connected app:
| Seller's plan | Per minute | Per day |
|---|---|---|
| Local, Local Plus | Not included — 402 plan_required | |
| International | 60 | 10,000 |
| Premium · Machinery · Brand membership | 300 | 100,000 |
Every response has X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time). Over the limit you get 429 — wait until the reset time. Need more? Write to developers@qwikstone.com.
X-RateLimit-Limit: 60 X-RateLimit-Remaining: 57 X-RateLimit-Reset: 1792857660 QwikStone-Version: 2026-10-01
Versioning
The current version is 2026-10-01, returned in the QwikStone-Version header. We add fields and endpoints without notice — your code should ignore fields it doesn't know. Anything that would break an integration ships as a new dated version, announced 90 days ahead.
Webhooks
Instead of polling, register an HTTPS endpoint and QwikStone sends you an event when an order changes. Add endpoints in Seller Hub → Developer tools, or with the webhook endpoints API.
Each delivery is a POST with a JSON event and a QS-Signature header: t=<unix time>,v1=<HMAC-SHA256> of "<t>.<raw body>" using the endpoint's secret (whsec_…). Check it, reject events older than 5 minutes, and reply 2xx quickly. Failed deliveries are retried 3 times.
import hmac, hashlib, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
if abs(time.time() - int(parts["t"])) > 300:
return False
signed = f'{parts["t"]}.'.encode() + raw_body
want = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(want, parts["v1"]){
"id": "evt_8812",
"type": "order.verified",
"created": 1792857600,
"data": { "object": { "object": "order", "number": "QS-2610-09CBA1", … } }
}Apps & OAuth
Building for many sellers? Register as a developer, create an app in the developer console and you get a client_id and client_secret. Sellers connect your app in Seller Hub — they see your app's name and exactly which scopes it asks for.
1 · Send the seller to the consent screen
GET http://seller.qwikstone.com/oauth/authorize?client_id=…&redirect_uri=…&scope=listings:read orders:read&state=…
2 · Exchange the code
QwikStone redirects to your redirect_uri with ?code=…&state=…. Exchange it on your server within 10 minutes.
3 · Call the API, refresh hourly
Access tokens last 1 hour; refresh tokens 90 days. If the seller disconnects your app (Seller Hub → Developer tools → Connected apps), calls return 401.
curl -X POST http://seller.qwikstone.com/oauth/token \ -d grant_type=authorization_code \ -d code=qs_code_… \ -d redirect_uri=https://yourapp.com/qs/callback \ -d client_id=qs_app_… \ -d client_secret=qs_sk_…
{
"access_token": "qs_at_…",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "qs_rt_…",
"scope": "listings:read orders:read",
"seller_id": "QS-S-000001"
}The listing object
A lot of stock a seller has for sale. Prices are what the seller receives; buyers see the listing price (3% marketplace fee added) plus tax for their country.
Your own item code. Listings are addressed by it. If you don't use SKUs, use the QwikStone ID, e.g. QS-001042.
Stone name + material + thickness + finish, e.g. “Black Galaxy Granite 2 cm Polished”. No phone numbers, links or “best/cheapest”.
stone · tile · machine · tool · article
marble, granite, quartzite, quartz, sandstone, limestone, slate, travertine, onyx, porcelain, ceramic …
Slab size and count. For slab-by-slab stock send slab_sheet instead.
What you receive per unit, in your currency. QwikStone adds the 3% marketplace fee and tax for the buyer.
sqft · sqm · unit · box
Total stock. available_sqft = total − sold − reserved.
in_stock. Stock in transit or at a port is only sold through QwikStone Merchandising.
HSN / HS code. GST (India) is set from it — you never send a tax rate.
HTTPS image URLs — photos of the actual stock. The first is the cover.
false keeps it as a draft.
{
"object": "listing",
"sku": "BG-20-07",
"id": 1042,
"title": "Black Galaxy Granite 2 cm Polished",
"kind": "stone",
"material": "granite",
"stone_name": "Black Galaxy",
"colour": "black",
"finish": "Polished",
"thickness_mm": 20,
"slab_l_cm": 300,
"slab_w_cm": 190,
"slabs": 42,
"price": {
"amount": 235.0,
"listing_amount": 242.27,
"currency": "INR",
"per": "sqft",
"note": "amount = what you receive; listing_amount = what buyers see before tax (3% fee added)"
},
"inventory": {
"total_sqft": 2580.0,
"sold_sqft": 0,
"reserved_sqft": 320.0,
"available_sqft": 2260.0,
"units": null
},
"availability": {
"status": "in_stock",
"port": null,
"vessel": null,
"eta": null
},
"hsn": "68022390",
"made_in": "IN",
"images": [
"https://cdn.qwikstone.com/media/l/1042/a.webp"
],
"active": true,
"review_status": "approved",
"updated_at": 1792857600
}List all listings
Returns your listings, newest last. Paged with page and page_size.
Parameters
Page number, starting at 1.
1–100, default 50.
Returns
A list of listings.
curl -X GET "http://seller.qwikstone.com/api/v1/listings?page=1&page_size=50" \ -H "Authorization: Bearer qs_live_YOUR_KEY"
import requests
r = requests.get(
"http://seller.qwikstone.com/api/v1/listings?page=1&page_size=50",
headers={"Authorization": "Bearer qs_live_YOUR_KEY"},
)
print(r.status_code, r.json())const res = await fetch("http://seller.qwikstone.com/api/v1/listings?page=1&page_size=50", {
method: "GET",
headers: {
Authorization: "Bearer qs_live_YOUR_KEY",
},
});
console.log(res.status, await res.json());<?php
$ch = curl_init("http://seller.qwikstone.com/api/v1/listings?page=1&page_size=50");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer qs_live_YOUR_KEY",
],
]);
$out = json_decode(curl_exec($ch), true);
print_r($out);{
"object": "list",
"items": [
{
"object": "listing",
"sku": "BG-20-07",
"id": 1042,
"title": "Black Galaxy Granite 2 cm Polished",
"kind": "stone",
"material": "granite",
"stone_name": "Black Galaxy",
"colour": "black",
"finish": "Polished",
"thickness_mm": 20,
"slab_l_cm": 300,
"slab_w_cm": 190,
"slabs": 42,
"price": {
"amount": 235.0,
"listing_amount": 242.27,
"currency": "INR",
"per": "sqft",
"note": "amount = what you receive; listing_amount = what buyers see before tax (3% fee added)"
},
"inventory": {
"total_sqft": 2580.0,
"sold_sqft": 0,
"reserved_sqft": 320.0,
"available_sqft": 2260.0,
"units": null
},
"availability": {
"status": "in_stock",
"port": null,
"vessel": null,
"eta": null
},
"hsn": "68022390",
"made_in": "IN",
"images": [
"https://cdn.qwikstone.com/media/l/1042/a.webp"
],
"active": true,
"review_status": "approved",
"updated_at": 1792857600
}
],
"page": 1,
"page_size": 50,
"total": 1,
"has_more": false
}Retrieve a listing
Retrieves one listing by your SKU (or the QS- ID).
Parameters
Your SKU or QS-000123.
Returns
The listing object, or an error.
curl -X GET "http://seller.qwikstone.com/api/v1/listings/BG-20-07" \ -H "Authorization: Bearer qs_live_YOUR_KEY"
import requests
r = requests.get(
"http://seller.qwikstone.com/api/v1/listings/BG-20-07",
headers={"Authorization": "Bearer qs_live_YOUR_KEY"},
)
print(r.status_code, r.json())const res = await fetch("http://seller.qwikstone.com/api/v1/listings/BG-20-07", {
method: "GET",
headers: {
Authorization: "Bearer qs_live_YOUR_KEY",
},
});
console.log(res.status, await res.json());<?php
$ch = curl_init("http://seller.qwikstone.com/api/v1/listings/BG-20-07");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer qs_live_YOUR_KEY",
],
]);
$out = json_decode(curl_exec($ch), true);
print_r($out);{
"object": "listing",
"sku": "BG-20-07",
"id": 1042,
"title": "Black Galaxy Granite 2 cm Polished",
"kind": "stone",
"material": "granite",
"stone_name": "Black Galaxy",
"colour": "black",
"finish": "Polished",
"thickness_mm": 20,
"slab_l_cm": 300,
"slab_w_cm": 190,
"slabs": 42,
"price": {
"amount": 235.0,
"listing_amount": 242.27,
"currency": "INR",
"per": "sqft",
"note": "amount = what you receive; listing_amount = what buyers see before tax (3% fee added)"
},
"inventory": {
"total_sqft": 2580.0,
"sold_sqft": 0,
"reserved_sqft": 320.0,
"available_sqft": 2260.0,
"units": null
},
"availability": {
"status": "in_stock",
"port": null,
"vessel": null,
"eta": null
},
"hsn": "68022390",
"made_in": "IN",
"images": [
"https://cdn.qwikstone.com/media/l/1042/a.webp"
],
"active": true,
"review_status": "approved",
"updated_at": 1792857600
}Create or replace a listing
Creates the listing if the SKU is new (201) or replaces it (200). The same automatic review, Brand Shield, country rules and price checks as Seller Hub apply.
Parameters
See the listing object.
What you receive per unit.
Sets GST in India.
HTTPS URLs.
Up to 20 search keywords — reviewed by QwikStone.
Returns
The listing object, or an error.
curl -X PUT "http://seller.qwikstone.com/api/v1/listings/BG-20-07" \
-H "Authorization: Bearer qs_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Black Galaxy Granite 2 cm Polished",
"material": "granite",
"stone_name": "Black Galaxy",
"finish": "Polished",
"thickness_mm": 20,
"slab_l_cm": 300,
"slab_w_cm": 190,
"slabs": 42,
"hsn": "68022390",
"price": {
"amount": 235,
"per": "sqft"
},
"inventory": {
"total_sqft": 2580
},
"images": [
"https://example.com/bg-07-1.jpg"
],
"keywords": [
"black galaxy",
"granite countertop"
]
}'import requests
payload = {
"title": "Black Galaxy Granite 2 cm Polished",
"material": "granite",
"stone_name": "Black Galaxy",
"finish": "Polished",
"thickness_mm": 20,
"slab_l_cm": 300,
"slab_w_cm": 190,
"slabs": 42,
"hsn": "68022390",
"price": {
"amount": 235,
"per": "sqft"
},
"inventory": {
"total_sqft": 2580
},
"images": [
"https://example.com/bg-07-1.jpg"
],
"keywords": [
"black galaxy",
"granite countertop"
]
}
r = requests.put(
"http://seller.qwikstone.com/api/v1/listings/BG-20-07",
headers={"Authorization": "Bearer qs_live_YOUR_KEY"},
json=payload,
)
print(r.status_code, r.json())const res = await fetch("http://seller.qwikstone.com/api/v1/listings/BG-20-07", {
method: "PUT",
headers: {
Authorization: "Bearer qs_live_YOUR_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
"title": "Black Galaxy Granite 2 cm Polished",
"material": "granite",
"stone_name": "Black Galaxy",
"finish": "Polished",
"thickness_mm": 20,
"slab_l_cm": 300,
"slab_w_cm": 190,
"slabs": 42,
"hsn": "68022390",
"price": {
"amount": 235,
"per": "sqft"
},
"inventory": {
"total_sqft": 2580
},
"images": [
"https://example.com/bg-07-1.jpg"
],
"keywords": [
"black galaxy",
"granite countertop"
]
}),
});
console.log(res.status, await res.json());<?php
$ch = curl_init("http://seller.qwikstone.com/api/v1/listings/BG-20-07");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer qs_live_YOUR_KEY",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => '{"title": "Black Galaxy Granite 2 cm Polished", "material": "granite", "stone_name": "Black Galaxy", "finish": "Polished", "thickness_mm": 20, "slab_l_cm": 300, "slab_w_cm": 190, "slabs": 42, "hsn": "68022390", "price": {"amount": 235, "per": "sqft"}, "inventory": {"total_sqft": 2580}, "images": ["https://example.com/bg-07-1.jpg"], "keywords": ["black galaxy", "granite countertop"]}',
]);
$out = json_decode(curl_exec($ch), true);
print_r($out);{
"object": "listing",
"sku": "BG-20-07",
"id": 1042,
"title": "Black Galaxy Granite 2 cm Polished",
"kind": "stone",
"material": "granite",
"stone_name": "Black Galaxy",
"colour": "black",
"finish": "Polished",
"thickness_mm": 20,
"slab_l_cm": 300,
"slab_w_cm": 190,
"slabs": 42,
"price": {
"amount": 235.0,
"listing_amount": 242.27,
"currency": "INR",
"per": "sqft",
"note": "amount = what you receive; listing_amount = what buyers see before tax (3% fee added)"
},
"inventory": {
"total_sqft": 2580.0,
"sold_sqft": 0,
"reserved_sqft": 320.0,
"available_sqft": 2260.0,
"units": null
},
"availability": {
"status": "in_stock",
"port": null,
"vessel": null,
"eta": null
},
"hsn": "68022390",
"made_in": "IN",
"images": [
"https://cdn.qwikstone.com/media/l/1042/a.webp"
],
"active": true,
"review_status": "approved",
"updated_at": 1792857600
}Update stock and price
The call to make from your ERP whenever stock moves. Send either or both fields. Stock sealed by QwikStone Merchandising can't be changed.
Parameters
New available stock.
New price you receive per unit.
Returns
The listing object, or an error.
curl -X PATCH "http://seller.qwikstone.com/api/v1/listings/BG-20-07/inventory" \
-H "Authorization: Bearer qs_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"available_sqft": 1250,
"price": 229
}'import requests
payload = {
"available_sqft": 1250,
"price": 229
}
r = requests.patch(
"http://seller.qwikstone.com/api/v1/listings/BG-20-07/inventory",
headers={"Authorization": "Bearer qs_live_YOUR_KEY"},
json=payload,
)
print(r.status_code, r.json())const res = await fetch("http://seller.qwikstone.com/api/v1/listings/BG-20-07/inventory", {
method: "PATCH",
headers: {
Authorization: "Bearer qs_live_YOUR_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
"available_sqft": 1250,
"price": 229
}),
});
console.log(res.status, await res.json());<?php
$ch = curl_init("http://seller.qwikstone.com/api/v1/listings/BG-20-07/inventory");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer qs_live_YOUR_KEY",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => '{"available_sqft": 1250, "price": 229}',
]);
$out = json_decode(curl_exec($ch), true);
print_r($out);{
"object": "listing",
"sku": "BG-20-07",
"id": 1042,
"title": "Black Galaxy Granite 2 cm Polished",
"kind": "stone",
"material": "granite",
"stone_name": "Black Galaxy",
"colour": "black",
"finish": "Polished",
"thickness_mm": 20,
"slab_l_cm": 300,
"slab_w_cm": 190,
"slabs": 42,
"price": {
"amount": 229.0,
"listing_amount": 236.08,
"currency": "INR",
"per": "sqft",
"note": "amount = what you receive; listing_amount = what buyers see before tax (3% fee added)"
},
"inventory": {
"total_sqft": 2580.0,
"sold_sqft": 0,
"reserved_sqft": 320.0,
"available_sqft": 1250.0,
"units": null
},
"availability": {
"status": "in_stock",
"port": null,
"vessel": null,
"eta": null
},
"hsn": "68022390",
"made_in": "IN",
"images": [
"https://cdn.qwikstone.com/media/l/1042/a.webp"
],
"active": true,
"review_status": "approved",
"updated_at": 1792857600
}Archive a listing
Hides the listing from buyers. Not allowed while stock is booked by an order (409).
Parameters
Returns
The result object, or an error.
curl -X DELETE "http://seller.qwikstone.com/api/v1/listings/BG-20-07" \ -H "Authorization: Bearer qs_live_YOUR_KEY"
import requests
r = requests.delete(
"http://seller.qwikstone.com/api/v1/listings/BG-20-07",
headers={"Authorization": "Bearer qs_live_YOUR_KEY"},
)
print(r.status_code, r.json())const res = await fetch("http://seller.qwikstone.com/api/v1/listings/BG-20-07", {
method: "DELETE",
headers: {
Authorization: "Bearer qs_live_YOUR_KEY",
},
});
console.log(res.status, await res.json());<?php
$ch = curl_init("http://seller.qwikstone.com/api/v1/listings/BG-20-07");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer qs_live_YOUR_KEY",
],
]);
$out = json_decode(curl_exec($ch), true);
print_r($out);{
"ok": true
}The order object
An order that includes the seller's listings. You only see the seller's own lines.
Order number, e.g. QS-2610-09CBA1.
awaiting_deposit · deposit_paid · inspecting · discrepancy · verified · consolidating · shipped · at_port · delivered · cancelled · refunded
Only your lines of the order: sku, sqft or units, unit_price, amount.
When the truck arrived at your yard and when loading finished (free loading time: 2 h truck, 4 h container).
{
"object": "order",
"number": "QS-2610-09CBA1",
"status": "verified",
"created": 1792771200,
"updated": 1792857600,
"currency": "INR",
"mode": "LOCAL",
"destination": {
"country": "IN",
"port": null
},
"lines": [
{
"sku": "BG-20-07",
"title": "Black Galaxy Granite 2 cm Polished",
"sqft": 320.0,
"units": 0,
"unit_price": 242.27,
"amount": 77526.4,
"status": "reserved"
}
],
"amount": 77526.4,
"loading": {
"truck_arrived": null,
"loaded": null
}
}List orders
Orders that include your listings, newest first. Each order only shows your lines.
Parameters
Filter by status.
Unix time.
Returns
A list of orders.
curl -X GET "http://seller.qwikstone.com/api/v1/orders?status=verified" \ -H "Authorization: Bearer qs_live_YOUR_KEY"
import requests
r = requests.get(
"http://seller.qwikstone.com/api/v1/orders?status=verified",
headers={"Authorization": "Bearer qs_live_YOUR_KEY"},
)
print(r.status_code, r.json())const res = await fetch("http://seller.qwikstone.com/api/v1/orders?status=verified", {
method: "GET",
headers: {
Authorization: "Bearer qs_live_YOUR_KEY",
},
});
console.log(res.status, await res.json());<?php
$ch = curl_init("http://seller.qwikstone.com/api/v1/orders?status=verified");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer qs_live_YOUR_KEY",
],
]);
$out = json_decode(curl_exec($ch), true);
print_r($out);{
"object": "list",
"items": [
{
"object": "order",
"number": "QS-2610-09CBA1",
"status": "verified",
"created": 1792771200,
"updated": 1792857600,
"currency": "INR",
"mode": "LOCAL",
"destination": {
"country": "IN",
"port": null
},
"lines": [
{
"sku": "BG-20-07",
"title": "Black Galaxy Granite 2 cm Polished",
"sqft": 320.0,
"units": 0,
"unit_price": 242.27,
"amount": 77526.4,
"status": "reserved"
}
],
"amount": 77526.4,
"loading": {
"truck_arrived": null,
"loaded": null
}
}
],
"page": 1,
"page_size": 50,
"total": 1,
"has_more": false
}Retrieve an order
One order by its number.
Parameters
Returns
The order object, or an error.
curl -X GET "http://seller.qwikstone.com/api/v1/orders/QS-2610-09CBA1" \ -H "Authorization: Bearer qs_live_YOUR_KEY"
import requests
r = requests.get(
"http://seller.qwikstone.com/api/v1/orders/QS-2610-09CBA1",
headers={"Authorization": "Bearer qs_live_YOUR_KEY"},
)
print(r.status_code, r.json())const res = await fetch("http://seller.qwikstone.com/api/v1/orders/QS-2610-09CBA1", {
method: "GET",
headers: {
Authorization: "Bearer qs_live_YOUR_KEY",
},
});
console.log(res.status, await res.json());<?php
$ch = curl_init("http://seller.qwikstone.com/api/v1/orders/QS-2610-09CBA1");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer qs_live_YOUR_KEY",
],
]);
$out = json_decode(curl_exec($ch), true);
print_r($out);{
"object": "order",
"number": "QS-2610-09CBA1",
"status": "verified",
"created": 1792771200,
"updated": 1792857600,
"currency": "INR",
"mode": "LOCAL",
"destination": {
"country": "IN",
"port": null
},
"lines": [
{
"sku": "BG-20-07",
"title": "Black Galaxy Granite 2 cm Polished",
"sqft": 320.0,
"units": 0,
"unit_price": 242.27,
"amount": 77526.4,
"status": "reserved"
}
],
"amount": 77526.4,
"loading": {
"truck_arrived": null,
"loaded": null
}
}Pricing
The full price build-up for a listing: what the seller receives, the 3% marketplace fee, the listing price, and tax for each buyer country.
Price build-up for a price you're considering. Body: your_price, regular_price, kind, hsn.
Every listing with its build-up and the tax rate for each market.
curl -X POST "http://seller.qwikstone.com/api/v1/pricing/preview" \
-H "Authorization: Bearer qs_live_YOUR_KEY" \
-H "Content-Type: application/json" -d '{"your_price": 235, "hsn": "6802"}'Advertising
Sponsored Products and Sponsored Brands campaigns, keywords, bids, budgets and performance. Requires a plan with ads.
All campaigns with spend, clicks, orders and ACoS.
Create a campaign: name, kind (sp | sb), daily_budget, lot_ids, keywords [{keyword, match, bid}].
Pause or resume: {"status": "paused" | "active"}.
Turn automatic bidding on or off.
Changes made to a campaign, by person or app.
Performance by day, campaign and keyword. Query: days, campaign_id.
Ads wallet: balance, auto top-up settings and history (top-ups and daily click spend). Query: days.
Keywords buyers search for your stone. Query: q, lot_id.
Suggested bid and range for a keyword. Query: keyword, match.
Home-page banners and fixed placements you can bid for.
Bid for a placement.
curl "http://seller.qwikstone.com/api/v1/campaigns" \ -H "Authorization: Bearer qs_live_YOUR_KEY"
Reports
The same datasets as Seller Hub → Reports: orders, listings, payments, ads and buyer search terms, with grouping.
Run a report. Body: dataset (orders | listings | payments | ads | searches), days or from/to, columns, group.
Business report data: sales, views and conversion by listing and day. Query: days or from/to.
curl -X POST "http://seller.qwikstone.com/api/v1/reports/run" \
-H "Authorization: Bearer qs_live_YOUR_KEY" \
-H "Content-Type: application/json" -d '{"dataset": "orders", "days": 30, "group": "month"}'Merchandising
Send listed stock to QwikStone Merchandising: we offer a price, collect, ship and sell it by bid. Price and quantity are sealed once collected.
Your Merchandising requests with status, offer, bids and deposits.
Apply with one or more listings. Body: lot_ids, ready_from, pickup_note.
Accept QwikStone's price offer (also: decline, cancel).
curl "http://seller.qwikstone.com/api/v1/merchandising" \ -H "Authorization: Bearer qs_live_YOUR_KEY"
Payouts & billing
What the seller earned and what QwikStone charged.
Order statement (sales, marketplace fee, broker check, detention, net), payouts and plan invoices. Query: days.
Plan, renewal, usage, this month's and 12 months' charges, and invoices.
One invoice with lines and tax, e.g. SUB-000123 or FEE-2026-10.
curl "http://seller.qwikstone.com/api/v1/payments" \ -H "Authorization: Bearer qs_live_YOUR_KEY"
Brand Shield
Brands the seller owns or is authorised to sell.
Brands, status, authorised sellers and open reports.
Report a listing that copies or misuses a brand.
curl "http://seller.qwikstone.com/api/v1/brands" \ -H "Authorization: Bearer qs_live_YOUR_KEY"
Webhook endpoints
Manage where QwikStone sends events.
Create an endpoint. Returns its signing secret once.
List endpoints with the last delivery status.
Delete an endpoint.
curl -X POST "http://seller.qwikstone.com/api/v1/webhook_endpoints" \
-H "Authorization: Bearer qs_live_YOUR_KEY" \
-H "Content-Type: application/json" -d '{"url": "https://yourapp.com/qs/webhooks", "events": ["order.created", "order.verified"]}'Webhook events
Subscribe an endpoint to any of these. The event's data.object is the order as returned by Retrieve an order.
order.created | A buyer placed an order with your listings. |
order.deposit_paid | The 50% deposit is paid — confirm your stock is ready. |
order.ready_requested | QwikStone asked you to confirm the stock. |
order.verified | The broker checked your stock and it matches. |
order.discrepancy | The broker found a difference — offer an adjustment. |
order.loaded | The truck arrived / loading finished. |
order.shipped | The container left. |
order.delivered | Delivered to the buyer. |
order.cancelled | The order was cancelled. |
order.refunded | The buyer was refunded. |