# Stella 56 Sales API

Version 1.0.0 · OpenAPI 3.1: https://stella56.app/developers/openapi.json · People read this at https://stella56.app/developers

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 URL:** `https://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.

## 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.

## 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.

Send it on every request 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.

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.

```js
// 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);
}
```

```python
# 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.

| Status | Code | When |
| --- | --- | --- |
| 400 | `bad_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. |
| 401 | `unauthorized` | No key, a wrong or revoked key, or the trader's API access is off. These all look the same on purpose. |
| 429 | `rate_limited` | More than 60 requests in a minute, or 10,000 in a UTC day, with this key. |
| 404 | `not_found` | Any other path under `/api/v1/`. |
| 405 | `method_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.

## List sale lines: `GET https://stella56.app/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`.

### Query parameters (all optional)

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `from` | string (date) | no | First sold day, included (UTC). With neither date, the window is the last 30 days to today. Example: `2026-07-01`. |
| `to` | string (date) | no | Last sold day, included (UTC). With only `from`, the window runs to today; with only `to`, it covers the 30 days ending then. Example: `2026-09-30`. |
| `cursor` | string | no | 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

**200**: One page of sale lines. Body: `SalesPage`.

**400**: 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. Body: `Error`.

**401**: No key, a wrong or revoked key, or the trader's API access is off. These all look the same on purpose. Body: `Error`.

**429**: More than 60 requests in a minute, or 10,000 in a UTC day, with this key. Header: `Retry-After: 42`. Body: `Error`.

### Request samples

```bash
curl -s "https://stella56.app/api/v1/sales?from=2026-07-01&to=2026-09-30" \
  -H "Authorization: Bearer $STELLA56_API_KEY"
```

```js
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();
```

```python
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()
```

### Response sample (200)

```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 summary: `GET https://stella56.app/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).

### Query parameters (all optional)

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `from` | string (date) | no | First sold day, included (UTC). With neither date, the window is the last 30 days to today. Example: `2026-07-01`. |
| `to` | string (date) | no | Last sold day, included (UTC). With only `from`, the window runs to today; with only `to`, it covers the 30 days ending then. Example: `2026-09-30`. |
| `groupBy` | array of strings | no | The fields to group by, comma-separated. Rows carry only these. Any of: `shape`, `clarity`, `color`, `size`. Default: `shape,clarity,color,size`. |
| `period` | string | no | `week` starts on Monday (UTC). With `none`, rows have no `periodStart`. One of: `day`, `week`, `month`, `none`. Default: `month`. |

### Responses

**200**: The window's sale lines added up. Body: `Summary`.

**400**: 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. Body: `Error`.

**401**: No key, a wrong or revoked key, or the trader's API access is off. These all look the same on purpose. Body: `Error`.

**429**: More than 60 requests in a minute, or 10,000 in a UTC day, with this key. Header: `Retry-After: 42`. Body: `Error`.

### Request samples

```bash
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"
```

```js
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();
```

```python
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()
```

### Response sample (200)

```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"
    }
  ]
}
```

## Schemas

### SaleLine

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

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `id` | string | yes | The line's id. Stable, and meaningless outside this API. |
| `soldOn` | string (date) | yes | The day it became a sale (UTC): the invoice's sale date, or the day a memo was invoiced. |
| `kind` | string | yes | Sold on an invoice, or sent on memo and then invoiced. One of: `invoice`, `memo`. |
| `shape` | string or null | yes | "Round", "Oval", "Princess" and so on, as the trader names them. |
| `clarity` | string | yes | "VS1", "SI2" and so on. |
| `color` | string or null | yes | A colour or a range, such as "F" or "G-H". |
| `size` | Size object | yes | The trader's size bracket. |
| `size.name` | string | yes | For `MM`, the smallest diameter ("0.70"); for `FRACTION`, a carat fraction ("1/2"); for `CARAT`, carats ("1.5"). |
| `size.type` | string | yes | One of: `MM`, `FRACTION`, `CARAT`. |
| `certified` | boolean | yes | Whether the stone has a lab certificate. |
| `lab` | string or null | yes | The certificate's lab, such as "GIA". Never its number. |
| `carats` | number | yes | What the client kept: sold less returned, to 0.001 ct. |
| `returnedCarats` | number | yes | Carats the client sent back. |
| `pricePerCarat` | number | yes | The line's own price. A discount on the whole sale and shipping are not included. |
| `amount` | number | yes | `carats` × `pricePerCarat`, to the cent. |
| `currency` | string | yes | Always USD today. Read it anyway: more currencies may come. Always: `USD`. |

### Size

The trader's size bracket.

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `name` | string | yes | For `MM`, the smallest diameter ("0.70"); for `FRACTION`, a carat fraction ("1/2"); for `CARAT`, carats ("1.5"). |
| `type` | string | yes | One of: `MM`, `FRACTION`, `CARAT`. |

### SalesPage

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `data` | array of SaleLine | yes |  |
| `data[].id` | string | yes | The line's id. Stable, and meaningless outside this API. |
| `data[].soldOn` | string (date) | yes | The day it became a sale (UTC): the invoice's sale date, or the day a memo was invoiced. |
| `data[].kind` | string | yes | Sold on an invoice, or sent on memo and then invoiced. One of: `invoice`, `memo`. |
| `data[].shape` | string or null | yes | "Round", "Oval", "Princess" and so on, as the trader names them. |
| `data[].clarity` | string | yes | "VS1", "SI2" and so on. |
| `data[].color` | string or null | yes | A colour or a range, such as "F" or "G-H". |
| `data[].size` | Size object | yes | The trader's size bracket. |
| `data[].size.name` | string | yes | For `MM`, the smallest diameter ("0.70"); for `FRACTION`, a carat fraction ("1/2"); for `CARAT`, carats ("1.5"). |
| `data[].size.type` | string | yes | One of: `MM`, `FRACTION`, `CARAT`. |
| `data[].certified` | boolean | yes | Whether the stone has a lab certificate. |
| `data[].lab` | string or null | yes | The certificate's lab, such as "GIA". Never its number. |
| `data[].carats` | number | yes | What the client kept: sold less returned, to 0.001 ct. |
| `data[].returnedCarats` | number | yes | Carats the client sent back. |
| `data[].pricePerCarat` | number | yes | The line's own price. A discount on the whole sale and shipping are not included. |
| `data[].amount` | number | yes | `carats` × `pricePerCarat`, to the cent. |
| `data[].currency` | string | yes | Always USD today. Read it anyway: more currencies may come. Always: `USD`. |
| `nextCursor` | string or null | yes | Send it back as `cursor` for the next page. `null` after the last. |

### SummaryRow

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

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `periodStart` | string (date) | no | The period's first day. Absent with `period=none`. |
| `shape` | string or null | no |  |
| `clarity` | string | no |  |
| `color` | string or null | no |  |
| `size` | Size object | no | The trader's size bracket. |
| `size.name` | string | yes | For `MM`, the smallest diameter ("0.70"); for `FRACTION`, a carat fraction ("1/2"); for `CARAT`, carats ("1.5"). |
| `size.type` | string | yes | One of: `MM`, `FRACTION`, `CARAT`. |
| `lines` | integer | yes | Sale lines added up. |
| `carats` | number | yes | Their carats. |
| `amount` | number | yes | Their amount. |
| `averagePricePerCarat` | number | yes | `amount` ÷ `carats`, to the cent. |
| `currency` | string | yes | Always: `USD`. |

### Summary

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `data` | array of SummaryRow | yes |  |
| `data[].periodStart` | string (date) | no | The period's first day. Absent with `period=none`. |
| `data[].shape` | string or null | no |  |
| `data[].clarity` | string | no |  |
| `data[].color` | string or null | no |  |
| `data[].size` | Size object | no | The trader's size bracket. |
| `data[].size.name` | string | yes | For `MM`, the smallest diameter ("0.70"); for `FRACTION`, a carat fraction ("1/2"); for `CARAT`, carats ("1.5"). |
| `data[].size.type` | string | yes | One of: `MM`, `FRACTION`, `CARAT`. |
| `data[].lines` | integer | yes | Sale lines added up. |
| `data[].carats` | number | yes | Their carats. |
| `data[].amount` | number | yes | Their amount. |
| `data[].averagePricePerCarat` | number | yes | `amount` ÷ `carats`, to the cent. |
| `data[].currency` | string | yes | Always: `USD`. |

### Error

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `error` | object | yes |  |
| `error.code` | string | yes | One of: `bad_request`, `unauthorized`, `not_found`, `method_not_allowed`, `rate_limited`. |
| `error.message` | string | yes | What went wrong and how to fix it. |
