Stella 56 Sales API
A diamond trader who runs their business on Stella 56 can let your system read what they sell: each stone's shape, clarity, colour, size, carats and price. The API is read-only, answers JSON that is never cached, and is called from your server with a key the trader gives you.
Call the address in the instructions the trader sent with your key, which is normally this one, exactly as given: most HTTP clients drop the key when they follow a redirect, and the answer is then a 401.
Import the OpenAPI file into Postman, Insomnia or a code generator to get a ready client. AI agents can read /developers.md, or this page itself when they ask for text/markdown. Every endpoint is a read-only GET.
- Who bought
- The supplier
- Cost and margin
- Profit and markup
- Invoice, memo and certificate numbers
- The trader's own stock codes
- Which lines were one purchase
- Notes and stock location
- Payments and balances
Questions about the data go to the trader who gave you the key.
curl -s "https://stella56.app/api/v1/sales?from=2026-07-01&to=2026-09-30" \ -H "Authorization: Bearer $STELLA56_API_KEY"
{
"data": [
{
"id": "k5791ty3mh0b6j4z2c8x7v1r5n7c0a2p",
"soldOn": "2026-09-14",
"kind": "invoice",
"shape": "Round",
"clarity": "VS1",
"color": "G-H",
"size": {
"name": "0.70",
"type": "MM"
},
"certified": false,
"lab": null,
"carats": 2.345,
"returnedCarats": 0,
"pricePerCarat": 1250,
"amount": 2931.25,
"currency": "USD"
},
{
"id": "k57a4wq0e2c7ph9n3dz6v8r1t5y2m4bx",
"soldOn": "2026-09-20",
"kind": "memo",
"shape": "Oval",
"clarity": "VVS2",
"color": "F",
"size": {
"name": "1.5",
"type": "CARAT"
},
"certified": true,
"lab": "GIA",
"carats": 1.52,
"returnedCarats": 0,
"pricePerCarat": 6400,
"amount": 9728,
"currency": "USD"
}
],
"nextCursor": "eyJ2IjoxLCJwaGFzZSI6Imludm9pY2VzIn0…"
}Authentication
The trader makes a key in Stella 56 (Settings → API access) and sends it to you. It starts with s56_ and reads one business's sales. Keep it on your server: the API answers no browser requests. The trader can revoke it at any time, and a revoked key never works again: if yours starts answering 401, ask them for a new one.
TypeHeaderReadsGET /api/v1/sales HTTP/1.1 Host: stella56.app Authorization: Bearer s56_…
{
"error": {
"code": "unauthorized",
"message": "Send a valid API key as `Authorization: Bearer s56_…`."
}
}Pagination and syncing
Sale lines come a page at a time. Send each answer's nextCursor back as cursor until it is null. Past rows change: when a client returns stones, that line's carats drop, and a line returned in full disappears.
- Load the history once.Read from the business's first sale to today. Sale lines have no longest window.
- On every sync, read the last 90 days again.Replace the rows you hold with a
soldOnin that window by what came back. A row that didn't come back was returned in full or cancelled. Go further back if late returns matter to you. - Pace yourself.Each page is one request. On a
429, waitRetry-Afterseconds and send it again.
// The last 90 days, page by page. Replace what you hold for them. const day = (ms) => new Date(ms).toISOString().slice(0, 10); const params = new URLSearchParams({ from: day(Date.now() - 89 * 86_400_000), to: day(Date.now()) }); const rows = []; for (;;) { const res = await fetch(`https://stella56.app/api/v1/sales?${params}`, { headers: { Authorization: `Bearer ${process.env.STELLA56_API_KEY}` } }); if (res.status === 429) { await new Promise((r) => setTimeout(r, Number(res.headers.get("Retry-After") ?? 60) * 1000)); continue; } if (!res.ok) { const { error } = await res.json(); throw new Error(`${res.status} ${error.code}: ${error.message}`); } const page = await res.json(); rows.push(...page.data); if (page.nextCursor === null) break; params.set("cursor", page.nextCursor); }
# The last 90 days, page by page. Replace what you hold for them. import os, time, requests from datetime import datetime, timedelta, timezone today = datetime.now(timezone.utc).date() # the API's days are UTC params = {"from": (today - timedelta(days=89)).isoformat(), "to": today.isoformat()} rows = [] while True: res = requests.get("https://stella56.app/api/v1/sales", params=params, timeout=30, headers={"Authorization": f"Bearer {os.environ['STELLA56_API_KEY']}"}) if res.status_code == 429: time.sleep(int(res.headers.get("Retry-After", "60"))) continue if not res.ok: error = res.json()["error"] raise RuntimeError(f"{res.status_code} {error['code']}: {error['message']}") page = res.json() rows += page["data"] if page["nextCursor"] is None: break params["cursor"] = page["nextCursor"]
Errors and limits
Every answer is JSON with Cache-Control: no-store. An error carries a code to branch on and a message that says how to fix it.
400bad_request
A date not written YYYY-MM-DD, from after to, an unknown groupBy or period, a summary window too long or too big, or a cursor from another key or other dates.
401unauthorized
No key, a wrong or revoked key, or the trader's API access is off. These all look the same on purpose.
429rate_limited
More than 60 requests in a minute, or 10,000 in a UTC day, with this key.
404not_found
Any other path under /api/v1/.
405method_not_allowed
Anything but GET. The answer carries Allow: GET.
60 requests a minute and 10,000 a UTC day, per key. Past either, the answer is 429 with a Retry-After header.
{
"error": {
"code": "bad_request",
"message": "`from` is after `to`."
}
}{
"error": {
"code": "unauthorized",
"message": "Send a valid API key as `Authorization: Bearer s56_…`."
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests with this key. Try again after `Retry-After` seconds."
}
}List sale lines
One row per stone line sold, a page at a time. A sale is what the trader's profit and loss counts: an invoice, dated by its sale date, and a memo (stones sent on approval) once it is invoiced, dated by that day. A memo still out with a client is not a sale yet.
Rows come invoices first, then memos, not in date order. A line returned in full, and every line of a cancelled sale, is left out. A page can be empty and still have a nextCursor: follow it until it is null.
from2026-07-01to2026-09-30from, the window runs to today; with only to, it covers the 30 days ending then.cursornextCursor from the page before. It works only with the same key and dates: send the same from and to, or leave them out.200One page of sale lines.
datarequiredSaleLine · 14 fields
idrequiredsoldOnrequiredkindrequiredinvoicememoshaperequiredclarityrequiredcolorrequiredsizerequiredSize · 2 fields
namerequiredMM, the smallest diameter ("0.70"); for FRACTION, a carat fraction ("1/2"); for CARAT, carats ("1.5").typerequiredMMFRACTIONCARATcertifiedrequiredlabrequiredcaratsrequiredreturnedCaratsrequiredpricePerCaratrequiredamountrequiredcarats × pricePerCarat, to the cent.currencyrequiredUSDnextCursorrequiredcursor for the next page. null after the last.400A date not written YYYY-MM-DD, from after to, an unknown groupBy or period, a summary window too long or too big, or a cursor from another key or other dates.
errorrequiredobject · 2 fields
coderequiredbad_requestunauthorizednot_foundmethod_not_allowedrate_limitedmessagerequired401No key, a wrong or revoked key, or the trader's API access is off. These all look the same on purpose.
errorrequiredobject · 2 fields
coderequiredbad_requestunauthorizednot_foundmethod_not_allowedrate_limitedmessagerequired429More than 60 requests in a minute, or 10,000 in a UTC day, with this key.
Retry-Afterrequired42errorrequiredobject · 2 fields
coderequiredbad_requestunauthorizednot_foundmethod_not_allowedrate_limitedmessagerequiredcurl -s "https://stella56.app/api/v1/sales?from=2026-07-01&to=2026-09-30" \ -H "Authorization: Bearer $STELLA56_API_KEY"
const res = await fetch("https://stella56.app/api/v1/sales?from=2026-07-01&to=2026-09-30", { headers: { Authorization: `Bearer ${process.env.STELLA56_API_KEY}` }, }); const body = await res.json();
import os, requests
res = requests.get(
"https://stella56.app/api/v1/sales",
params={"from": "2026-07-01", "to": "2026-09-30"},
headers={"Authorization": f"Bearer {os.environ['STELLA56_API_KEY']}"},
timeout=30,
)
body = res.json(){
"data": [
{
"id": "k5791ty3mh0b6j4z2c8x7v1r5n7c0a2p",
"soldOn": "2026-09-14",
"kind": "invoice",
"shape": "Round",
"clarity": "VS1",
"color": "G-H",
"size": {
"name": "0.70",
"type": "MM"
},
"certified": false,
"lab": null,
"carats": 2.345,
"returnedCarats": 0,
"pricePerCarat": 1250,
"amount": 2931.25,
"currency": "USD"
},
{
"id": "k57a4wq0e2c7ph9n3dz6v8r1t5y2m4bx",
"soldOn": "2026-09-20",
"kind": "memo",
"shape": "Oval",
"clarity": "VVS2",
"color": "F",
"size": {
"name": "1.5",
"type": "CARAT"
},
"certified": true,
"lab": "GIA",
"carats": 1.52,
"returnedCarats": 0,
"pricePerCarat": 6400,
"amount": 9728,
"currency": "USD"
}
],
"nextCursor": "eyJ2IjoxLCJwaGFzZSI6Imludm9pY2VzIn0…"
}{
"error": {
"code": "bad_request",
"message": "`from` is after `to`."
}
}{
"error": {
"code": "unauthorized",
"message": "Send a valid API key as `Authorization: Bearer s56_…`."
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests with this key. Try again after `Retry-After` seconds."
}
}Sales summary
The same lines added up by period and grade, in one answer with no pages. It is built from the sale lines, so the two always agree. A window is at most 366 days, with at most 10,000 sales.
Rows are sorted by period, then by the grouped fields as text, not in grade order (clarity reads IF, SI1, VS1, and a missing shape or colour comes last).
from2026-07-01to2026-09-30from, the window runs to today; with only to, it covers the 30 days ending then.groupByshapeclaritycolorsizeDefault: shape,clarity,color,sizeperioddayweekmonthnoneDefault: monthweek starts on Monday (UTC). With none, rows have no periodStart.200The window's sale lines added up.
datarequiredSummaryRow · 10 fields
periodStartperiod=none.shapeclaritycolorsizeSize · 2 fields
namerequiredMM, the smallest diameter ("0.70"); for FRACTION, a carat fraction ("1/2"); for CARAT, carats ("1.5").typerequiredMMFRACTIONCARATlinesrequiredcaratsrequiredamountrequiredaveragePricePerCaratrequiredamount ÷ carats, to the cent.currencyrequiredUSD400A date not written YYYY-MM-DD, from after to, an unknown groupBy or period, a summary window too long or too big, or a cursor from another key or other dates.
errorrequiredobject · 2 fields
coderequiredbad_requestunauthorizednot_foundmethod_not_allowedrate_limitedmessagerequired401No key, a wrong or revoked key, or the trader's API access is off. These all look the same on purpose.
errorrequiredobject · 2 fields
coderequiredbad_requestunauthorizednot_foundmethod_not_allowedrate_limitedmessagerequired429More than 60 requests in a minute, or 10,000 in a UTC day, with this key.
Retry-Afterrequired42errorrequiredobject · 2 fields
coderequiredbad_requestunauthorizednot_foundmethod_not_allowedrate_limitedmessagerequiredcurl -s "https://stella56.app/api/v1/sales/summary?from=2026-01-01&to=2026-09-30&groupBy=shape,clarity,size&period=month" \ -H "Authorization: Bearer $STELLA56_API_KEY"
const res = await fetch("https://stella56.app/api/v1/sales/summary?from=2026-01-01&to=2026-09-30&groupBy=shape,clarity,size&period=month", { headers: { Authorization: `Bearer ${process.env.STELLA56_API_KEY}` }, }); const body = await res.json();
import os, requests
res = requests.get(
"https://stella56.app/api/v1/sales/summary",
params={"from": "2026-01-01", "to": "2026-09-30", "groupBy": "shape,clarity,size", "period": "month"},
headers={"Authorization": f"Bearer {os.environ['STELLA56_API_KEY']}"},
timeout=30,
)
body = res.json(){
"data": [
{
"periodStart": "2026-09-01",
"shape": "Round",
"clarity": "VS1",
"size": {
"name": "0.70",
"type": "MM"
},
"lines": 12,
"carats": 34.567,
"amount": 43208.75,
"averagePricePerCarat": 1250,
"currency": "USD"
}
]
}{
"error": {
"code": "bad_request",
"message": "`from` is after `to`."
}
}{
"error": {
"code": "unauthorized",
"message": "Send a valid API key as `Authorization: Bearer s56_…`."
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests with this key. Try again after `Retry-After` seconds."
}
}SaleLine
One stone line sold. Store rows by id. Rows may gain fields over time: ignore the ones you don't know.
idrequiredsoldOnrequiredkindrequiredinvoicememoshaperequiredclarityrequiredcolorrequiredsizerequiredSize · 2 fields
namerequiredMM, the smallest diameter ("0.70"); for FRACTION, a carat fraction ("1/2"); for CARAT, carats ("1.5").typerequiredMMFRACTIONCARATcertifiedrequiredlabrequiredcaratsrequiredreturnedCaratsrequiredpricePerCaratrequiredamountrequiredcarats × pricePerCarat, to the cent.currencyrequiredUSD{
"id": "k5791ty3mh0b6j4z2c8x7v1r5n7c0a2p",
"soldOn": "2026-09-14",
"kind": "invoice",
"shape": "Round",
"clarity": "VS1",
"color": "G-H",
"size": {
"name": "0.70",
"type": "MM"
},
"certified": false,
"lab": null,
"carats": 2.345,
"returnedCarats": 0,
"pricePerCarat": 1250,
"amount": 2931.25,
"currency": "USD"
}Size
The trader's size bracket.
namerequiredMM, the smallest diameter ("0.70"); for FRACTION, a carat fraction ("1/2"); for CARAT, carats ("1.5").typerequiredMMFRACTIONCARAT{
"name": "0.70",
"type": "MM"
}SalesPage
datarequiredSaleLine · 14 fields
idrequiredsoldOnrequiredkindrequiredinvoicememoshaperequiredclarityrequiredcolorrequiredsizerequiredSize · 2 fields
namerequiredMM, the smallest diameter ("0.70"); for FRACTION, a carat fraction ("1/2"); for CARAT, carats ("1.5").typerequiredMMFRACTIONCARATcertifiedrequiredlabrequiredcaratsrequiredreturnedCaratsrequiredpricePerCaratrequiredamountrequiredcarats × pricePerCarat, to the cent.currencyrequiredUSDnextCursorrequiredcursor for the next page. null after the last.{
"data": [
{
"id": "k5791ty3mh0b6j4z2c8x7v1r5n7c0a2p",
"soldOn": "2026-09-14",
"kind": "invoice",
"shape": "Round",
"clarity": "VS1",
"color": "G-H",
"size": {
"name": "0.70",
"type": "MM"
},
"certified": false,
"lab": null,
"carats": 2.345,
"returnedCarats": 0,
"pricePerCarat": 1250,
"amount": 2931.25,
"currency": "USD"
},
{
"id": "k57a4wq0e2c7ph9n3dz6v8r1t5y2m4bx",
"soldOn": "2026-09-20",
"kind": "memo",
"shape": "Oval",
"clarity": "VVS2",
"color": "F",
"size": {
"name": "1.5",
"type": "CARAT"
},
"certified": true,
"lab": "GIA",
"carats": 1.52,
"returnedCarats": 0,
"pricePerCarat": 6400,
"amount": 9728,
"currency": "USD"
}
],
"nextCursor": "eyJ2IjoxLCJwaGFzZSI6Imludm9pY2VzIn0…"
}SummaryRow
One period and grade. Only the fields you group by are present.
periodStartperiod=none.shapeclaritycolorsizeSize · 2 fields
namerequiredMM, the smallest diameter ("0.70"); for FRACTION, a carat fraction ("1/2"); for CARAT, carats ("1.5").typerequiredMMFRACTIONCARATlinesrequiredcaratsrequiredamountrequiredaveragePricePerCaratrequiredamount ÷ carats, to the cent.currencyrequiredUSD{
"periodStart": "2026-09-01",
"shape": "Round",
"clarity": "VS1",
"size": {
"name": "0.70",
"type": "MM"
},
"lines": 12,
"carats": 34.567,
"amount": 43208.75,
"averagePricePerCarat": 1250,
"currency": "USD"
}Summary
datarequiredSummaryRow · 10 fields
periodStartperiod=none.shapeclaritycolorsizeSize · 2 fields
namerequiredMM, the smallest diameter ("0.70"); for FRACTION, a carat fraction ("1/2"); for CARAT, carats ("1.5").typerequiredMMFRACTIONCARATlinesrequiredcaratsrequiredamountrequiredaveragePricePerCaratrequiredamount ÷ carats, to the cent.currencyrequiredUSD{
"data": [
{
"periodStart": "2026-09-01",
"shape": "Round",
"clarity": "VS1",
"size": {
"name": "0.70",
"type": "MM"
},
"lines": 12,
"carats": 34.567,
"amount": 43208.75,
"averagePricePerCarat": 1250,
"currency": "USD"
}
]
}Error
errorrequiredobject · 2 fields
coderequiredbad_requestunauthorizednot_foundmethod_not_allowedrate_limitedmessagerequired{
"error": {
"code": "unauthorized",
"message": "Send a valid API key as `Authorization: Bearer s56_…`."
}
}