Skip to main content
Stella 56Sales API
API referencev1.0.0

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.

Base URLhttps://stella56.app/api/v1

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.

Never in any answer
  • 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.

Quick start
curl -s "https://stella56.app/api/v1/sales?from=2026-07-01&to=2026-09-30" \
  -H "Authorization: Bearer $STELLA56_API_KEY"
Answer
application/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…"
}
Guide

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.

Type
HTTP bearer
Header
Authorization: Bearer s56_…
Reads
One business's sales, read-only
Every request
GET /api/v1/sales HTTP/1.1
Host: stella56.app
Authorization: Bearer s56_…
A missing, wrong or revoked key
application/json
{
  "error": {
    "code": "unauthorized",
    "message": "Send a valid API key as `Authorization: Bearer s56_…`."
  }
}
Guide

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.

  1. Load the history once.Read from the business's first sale to today. Sale lines have no longest window.
  2. On every sync, read the last 90 days again.Replace the rows you hold with a soldOn in 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.
  3. Pace yourself.Each page is one request. On a 429, wait Retry-After seconds and send it again.
A sync
// 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);
}
Guide

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.

Rate limits

60 requests a minute and 10,000 a UTC day, per key. Past either, the answer is 429 with a Retry-After header.

Error answers
application/json
{
  "error": {
    "code": "bad_request",
    "message": "`from` is after `to`."
  }
}
Sales

List sale lines

GET/api/v1/sales

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.

AuthorizationbearerAuth
Query parametersAll optional
from
string <date>
Example: 2026-07-01
First sold day, included (UTC). With neither date, the window is the last 30 days to today.
to
string <date>
Example: 2026-09-30
Last sold day, included (UTC). With only from, the window runs to today; with only to, it covers the 30 days ending then.
cursor
string
The nextCursor from the page before. It works only with the same key and dates: send the same from and to, or leave them out.
Responses
200One page of sale lines.
Response schema · application/json · SalesPage
datarequired
array of SaleLine
SaleLine · 14 fields
idrequired
string
The line's id. Stable, and meaningless outside this API.
soldOnrequired
string <date>
The day it became a sale (UTC): the invoice's sale date, or the day a memo was invoiced.
kindrequired
string
One of: invoicememo
Sold on an invoice, or sent on memo and then invoiced.
shaperequired
string or null
"Round", "Oval", "Princess" and so on, as the trader names them.
clarityrequired
string
"VS1", "SI2" and so on.
colorrequired
string or null
A colour or a range, such as "F" or "G-H".
sizerequired
Size object
The trader's size bracket.
Size · 2 fields
namerequired
string
For MM, the smallest diameter ("0.70"); for FRACTION, a carat fraction ("1/2"); for CARAT, carats ("1.5").
typerequired
string
One of: MMFRACTIONCARAT
certifiedrequired
boolean
Whether the stone has a lab certificate.
labrequired
string or null
The certificate's lab, such as "GIA". Never its number.
caratsrequired
number
What the client kept: sold less returned, to 0.001 ct.
returnedCaratsrequired
number
Carats the client sent back.
pricePerCaratrequired
number
The line's own price. A discount on the whole sale and shipping are not included.
amountrequired
number
carats × pricePerCarat, to the cent.
currencyrequired
string
Always: USD
Always USD today. Read it anyway: more currencies may come.
nextCursorrequired
string or null
Send it back as cursor 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.
Response schema · application/json · Error
errorrequired
object
object · 2 fields
coderequired
string
One of: bad_requestunauthorizednot_foundmethod_not_allowedrate_limited
messagerequired
string
What went wrong and how to fix it.
401No key, a wrong or revoked key, or the trader's API access is off. These all look the same on purpose.
Response schema · application/json · Error
errorrequired
object
object · 2 fields
coderequired
string
One of: bad_requestunauthorizednot_foundmethod_not_allowedrate_limited
messagerequired
string
What went wrong and how to fix it.
429More than 60 requests in a minute, or 10,000 in a UTC day, with this key.
Response schema · application/json · Error
Headers
Retry-Afterrequired
integer
Example: 42
Seconds to wait before sending the request again.
errorrequired
object
object · 2 fields
coderequired
string
One of: bad_requestunauthorizednot_foundmethod_not_allowedrate_limited
messagerequired
string
What went wrong and how to fix it.
GETstella56.app/api/v1/sales
Request samples
curl -s "https://stella56.app/api/v1/sales?from=2026-07-01&to=2026-09-30" \
  -H "Authorization: Bearer $STELLA56_API_KEY"
Response samples
application/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…"
}
Sales

Sales summary

GET/api/v1/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).

AuthorizationbearerAuth
Query parametersAll optional
from
string <date>
Example: 2026-07-01
First sold day, included (UTC). With neither date, the window is the last 30 days to today.
to
string <date>
Example: 2026-09-30
Last sold day, included (UTC). With only from, the window runs to today; with only to, it covers the 30 days ending then.
groupBy
array of strings
Any of: shapeclaritycolorsizeDefault: shape,clarity,color,size
The fields to group by, comma-separated. Rows carry only these.
period
string
One of: dayweekmonthnoneDefault: month
week starts on Monday (UTC). With none, rows have no periodStart.
Responses
200The window's sale lines added up.
Response schema · application/json · Summary
datarequired
array of SummaryRow
SummaryRow · 10 fields
periodStart
string <date>
The period's first day. Absent with period=none.
shape
string or null
clarity
string
color
string or null
size
Size object
The trader's size bracket.
Size · 2 fields
namerequired
string
For MM, the smallest diameter ("0.70"); for FRACTION, a carat fraction ("1/2"); for CARAT, carats ("1.5").
typerequired
string
One of: MMFRACTIONCARAT
linesrequired
integer
Sale lines added up.
caratsrequired
number
Their carats.
amountrequired
number
Their amount.
averagePricePerCaratrequired
number
amount ÷ carats, to the cent.
currencyrequired
string
Always: USD
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.
Response schema · application/json · Error
errorrequired
object
object · 2 fields
coderequired
string
One of: bad_requestunauthorizednot_foundmethod_not_allowedrate_limited
messagerequired
string
What went wrong and how to fix it.
401No key, a wrong or revoked key, or the trader's API access is off. These all look the same on purpose.
Response schema · application/json · Error
errorrequired
object
object · 2 fields
coderequired
string
One of: bad_requestunauthorizednot_foundmethod_not_allowedrate_limited
messagerequired
string
What went wrong and how to fix it.
429More than 60 requests in a minute, or 10,000 in a UTC day, with this key.
Response schema · application/json · Error
Headers
Retry-Afterrequired
integer
Example: 42
Seconds to wait before sending the request again.
errorrequired
object
object · 2 fields
coderequired
string
One of: bad_requestunauthorizednot_foundmethod_not_allowedrate_limited
messagerequired
string
What went wrong and how to fix it.
GETstella56.app/api/v1/sales/summary
Request samples
curl -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"
Response samples
application/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"
    }
  ]
}
Schema

SaleLine

One stone line sold. Store rows by id. Rows may gain fields over time: ignore the ones you don't know.

idrequired
string
The line's id. Stable, and meaningless outside this API.
soldOnrequired
string <date>
The day it became a sale (UTC): the invoice's sale date, or the day a memo was invoiced.
kindrequired
string
One of: invoicememo
Sold on an invoice, or sent on memo and then invoiced.
shaperequired
string or null
"Round", "Oval", "Princess" and so on, as the trader names them.
clarityrequired
string
"VS1", "SI2" and so on.
colorrequired
string or null
A colour or a range, such as "F" or "G-H".
sizerequired
Size object
The trader's size bracket.
Size · 2 fields
namerequired
string
For MM, the smallest diameter ("0.70"); for FRACTION, a carat fraction ("1/2"); for CARAT, carats ("1.5").
typerequired
string
One of: MMFRACTIONCARAT
certifiedrequired
boolean
Whether the stone has a lab certificate.
labrequired
string or null
The certificate's lab, such as "GIA". Never its number.
caratsrequired
number
What the client kept: sold less returned, to 0.001 ct.
returnedCaratsrequired
number
Carats the client sent back.
pricePerCaratrequired
number
The line's own price. A discount on the whole sale and shipping are not included.
amountrequired
number
carats × pricePerCarat, to the cent.
currencyrequired
string
Always: USD
Always USD today. Read it anyway: more currencies may come.
Example
{
  "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"
}
Schema

Size

The trader's size bracket.

namerequired
string
For MM, the smallest diameter ("0.70"); for FRACTION, a carat fraction ("1/2"); for CARAT, carats ("1.5").
typerequired
string
One of: MMFRACTIONCARAT
Example
{
  "name": "0.70",
  "type": "MM"
}
Schema

SalesPage

datarequired
array of SaleLine
SaleLine · 14 fields
idrequired
string
The line's id. Stable, and meaningless outside this API.
soldOnrequired
string <date>
The day it became a sale (UTC): the invoice's sale date, or the day a memo was invoiced.
kindrequired
string
One of: invoicememo
Sold on an invoice, or sent on memo and then invoiced.
shaperequired
string or null
"Round", "Oval", "Princess" and so on, as the trader names them.
clarityrequired
string
"VS1", "SI2" and so on.
colorrequired
string or null
A colour or a range, such as "F" or "G-H".
sizerequired
Size object
The trader's size bracket.
Size · 2 fields
namerequired
string
For MM, the smallest diameter ("0.70"); for FRACTION, a carat fraction ("1/2"); for CARAT, carats ("1.5").
typerequired
string
One of: MMFRACTIONCARAT
certifiedrequired
boolean
Whether the stone has a lab certificate.
labrequired
string or null
The certificate's lab, such as "GIA". Never its number.
caratsrequired
number
What the client kept: sold less returned, to 0.001 ct.
returnedCaratsrequired
number
Carats the client sent back.
pricePerCaratrequired
number
The line's own price. A discount on the whole sale and shipping are not included.
amountrequired
number
carats × pricePerCarat, to the cent.
currencyrequired
string
Always: USD
Always USD today. Read it anyway: more currencies may come.
nextCursorrequired
string or null
Send it back as cursor for the next page. null after the last.
Example
{
  "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…"
}
Schema

SummaryRow

One period and grade. Only the fields you group by are present.

periodStart
string <date>
The period's first day. Absent with period=none.
shape
string or null
clarity
string
color
string or null
size
Size object
The trader's size bracket.
Size · 2 fields
namerequired
string
For MM, the smallest diameter ("0.70"); for FRACTION, a carat fraction ("1/2"); for CARAT, carats ("1.5").
typerequired
string
One of: MMFRACTIONCARAT
linesrequired
integer
Sale lines added up.
caratsrequired
number
Their carats.
amountrequired
number
Their amount.
averagePricePerCaratrequired
number
amount ÷ carats, to the cent.
currencyrequired
string
Always: USD
Example
{
  "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"
}
Schema

Summary

datarequired
array of SummaryRow
SummaryRow · 10 fields
periodStart
string <date>
The period's first day. Absent with period=none.
shape
string or null
clarity
string
color
string or null
size
Size object
The trader's size bracket.
Size · 2 fields
namerequired
string
For MM, the smallest diameter ("0.70"); for FRACTION, a carat fraction ("1/2"); for CARAT, carats ("1.5").
typerequired
string
One of: MMFRACTIONCARAT
linesrequired
integer
Sale lines added up.
caratsrequired
number
Their carats.
amountrequired
number
Their amount.
averagePricePerCaratrequired
number
amount ÷ carats, to the cent.
currencyrequired
string
Always: USD
Example
{
  "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"
    }
  ]
}
Schema

Error

errorrequired
object
object · 2 fields
coderequired
string
One of: bad_requestunauthorizednot_foundmethod_not_allowedrate_limited
messagerequired
string
What went wrong and how to fix it.
Example
{
  "error": {
    "code": "unauthorized",
    "message": "Send a valid API key as `Authorization: Bearer s56_…`."
  }
}