{
  "openapi": "3.1.0",
  "info": {
    "title": "Stella 56 Sales API",
    "version": "1.0.0",
    "summary": "Read a Stella 56 trader's sales flow: the stones sold and their prices, never who bought.",
    "description": "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.",
    "contact": {
      "name": "The trader who gave you the key"
    }
  },
  "servers": [
    {
      "url": "https://stella56.app/api/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Sales",
      "description": "Stone lines the trader sold, one by one or added up."
    }
  ],
  "paths": {
    "/sales": {
      "get": {
        "tags": [
          "Sales"
        ],
        "operationId": "listSaleLines",
        "summary": "List sale lines",
        "description": "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.\n\nRows 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`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/from"
          },
          {
            "$ref": "#/components/parameters/to"
          },
          {
            "$ref": "#/components/parameters/cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "One page of sale lines.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SalesPage"
                },
                "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…"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl -s \"https://stella56.app/api/v1/sales?from=2026-07-01&to=2026-09-30\" \\\n  -H \"Authorization: Bearer $STELLA56_API_KEY\""
          },
          {
            "lang": "JavaScript",
            "label": "JavaScript",
            "source": "const res = await fetch(\"https://stella56.app/api/v1/sales?from=2026-07-01&to=2026-09-30\", {\n  headers: { Authorization: `Bearer ${process.env.STELLA56_API_KEY}` },\n});\nconst body = await res.json();"
          },
          {
            "lang": "Python",
            "label": "Python",
            "source": "import os, requests\n\nres = requests.get(\n    \"https://stella56.app/api/v1/sales\",\n    params={\"from\": \"2026-07-01\", \"to\": \"2026-09-30\"},\n    headers={\"Authorization\": f\"Bearer {os.environ['STELLA56_API_KEY']}\"},\n    timeout=30,\n)\nbody = res.json()"
          }
        ]
      }
    },
    "/sales/summary": {
      "get": {
        "tags": [
          "Sales"
        ],
        "operationId": "getSalesSummary",
        "summary": "Sales summary",
        "description": "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.\n\nRows 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).",
        "parameters": [
          {
            "$ref": "#/components/parameters/from"
          },
          {
            "$ref": "#/components/parameters/to"
          },
          {
            "$ref": "#/components/parameters/groupBy"
          },
          {
            "$ref": "#/components/parameters/period"
          }
        ],
        "responses": {
          "200": {
            "description": "The window's sale lines added up.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Summary"
                },
                "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"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl -s \"https://stella56.app/api/v1/sales/summary?from=2026-01-01&to=2026-09-30&groupBy=shape,clarity,size&period=month\" \\\n  -H \"Authorization: Bearer $STELLA56_API_KEY\""
          },
          {
            "lang": "JavaScript",
            "label": "JavaScript",
            "source": "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\", {\n  headers: { Authorization: `Bearer ${process.env.STELLA56_API_KEY}` },\n});\nconst body = await res.json();"
          },
          {
            "lang": "Python",
            "label": "Python",
            "source": "import os, requests\n\nres = requests.get(\n    \"https://stella56.app/api/v1/sales/summary\",\n    params={\"from\": \"2026-01-01\", \"to\": \"2026-09-30\", \"groupBy\": \"shape,clarity,size\", \"period\": \"month\"},\n    headers={\"Authorization\": f\"Bearer {os.environ['STELLA56_API_KEY']}\"},\n    timeout=30,\n)\nbody = res.json()"
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "s56_…",
        "description": "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."
      }
    },
    "parameters": {
      "from": {
        "name": "from",
        "in": "query",
        "schema": {
          "type": "string",
          "format": "date",
          "examples": [
            "2026-07-01"
          ]
        },
        "description": "First sold day, included (UTC). With neither date, the window is the last 30 days to today."
      },
      "to": {
        "name": "to",
        "in": "query",
        "schema": {
          "type": "string",
          "format": "date",
          "examples": [
            "2026-09-30"
          ]
        },
        "description": "Last sold day, included (UTC). With only `from`, the window runs to today; with only `to`, it covers the 30 days ending then."
      },
      "cursor": {
        "name": "cursor",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "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."
      },
      "groupBy": {
        "name": "groupBy",
        "in": "query",
        "style": "form",
        "explode": false,
        "schema": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "shape",
              "clarity",
              "color",
              "size"
            ]
          },
          "default": [
            "shape",
            "clarity",
            "color",
            "size"
          ]
        },
        "description": "The fields to group by, comma-separated. Rows carry only these."
      },
      "period": {
        "name": "period",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "day",
            "week",
            "month",
            "none"
          ],
          "default": "month"
        },
        "description": "`week` starts on Monday (UTC). With `none`, rows have no `periodStart`."
      }
    },
    "responses": {
      "BadRequest": {
        "description": "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.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "bad_request",
                "message": "`from` is after `to`."
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "No key, a wrong or revoked key, or the trader's API access is off. These all look the same on purpose.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Send a valid API key as `Authorization: Bearer s56_…`."
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "More than 60 requests in a minute, or 10,000 in a UTC day, with this key.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before sending the request again.",
            "schema": {
              "type": "integer",
              "examples": [
                42
              ]
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Too many requests with this key. Try again after `Retry-After` seconds."
              }
            }
          }
        }
      }
    },
    "schemas": {
      "SalesPage": {
        "type": "object",
        "required": [
          "data",
          "nextCursor"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SaleLine"
            }
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Send it back as `cursor` for the next page. `null` after the last."
          }
        }
      },
      "SaleLine": {
        "type": "object",
        "description": "One stone line sold. Store rows by `id`. Rows may gain fields over time: ignore the ones you don't know.",
        "required": [
          "id",
          "soldOn",
          "kind",
          "shape",
          "clarity",
          "color",
          "size",
          "certified",
          "lab",
          "carats",
          "returnedCarats",
          "pricePerCarat",
          "amount",
          "currency"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The line's id. Stable, and meaningless outside this API."
          },
          "soldOn": {
            "type": "string",
            "format": "date",
            "description": "The day it became a sale (UTC): the invoice's sale date, or the day a memo was invoiced."
          },
          "kind": {
            "type": "string",
            "enum": [
              "invoice",
              "memo"
            ],
            "description": "Sold on an invoice, or sent on memo and then invoiced."
          },
          "shape": {
            "type": [
              "string",
              "null"
            ],
            "description": "\"Round\", \"Oval\", \"Princess\" and so on, as the trader names them."
          },
          "clarity": {
            "type": "string",
            "description": "\"VS1\", \"SI2\" and so on."
          },
          "color": {
            "type": [
              "string",
              "null"
            ],
            "description": "A colour or a range, such as \"F\" or \"G-H\"."
          },
          "size": {
            "$ref": "#/components/schemas/Size"
          },
          "certified": {
            "type": "boolean",
            "description": "Whether the stone has a lab certificate."
          },
          "lab": {
            "type": [
              "string",
              "null"
            ],
            "description": "The certificate's lab, such as \"GIA\". Never its number."
          },
          "carats": {
            "type": "number",
            "description": "What the client kept: sold less returned, to 0.001 ct."
          },
          "returnedCarats": {
            "type": "number",
            "description": "Carats the client sent back."
          },
          "pricePerCarat": {
            "type": "number",
            "description": "The line's own price. A discount on the whole sale and shipping are not included."
          },
          "amount": {
            "type": "number",
            "description": "`carats` × `pricePerCarat`, to the cent."
          },
          "currency": {
            "type": "string",
            "const": "USD",
            "description": "Always USD today. Read it anyway: more currencies may come."
          }
        }
      },
      "Size": {
        "type": "object",
        "description": "The trader's size bracket.",
        "required": [
          "name",
          "type"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "For `MM`, the smallest diameter (\"0.70\"); for `FRACTION`, a carat fraction (\"1/2\"); for `CARAT`, carats (\"1.5\")."
          },
          "type": {
            "type": "string",
            "enum": [
              "MM",
              "FRACTION",
              "CARAT"
            ]
          }
        }
      },
      "Summary": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SummaryRow"
            }
          }
        }
      },
      "SummaryRow": {
        "type": "object",
        "description": "One period and grade. Only the fields you group by are present.",
        "required": [
          "lines",
          "carats",
          "amount",
          "averagePricePerCarat",
          "currency"
        ],
        "properties": {
          "periodStart": {
            "type": "string",
            "format": "date",
            "description": "The period's first day. Absent with `period=none`."
          },
          "shape": {
            "type": [
              "string",
              "null"
            ]
          },
          "clarity": {
            "type": "string"
          },
          "color": {
            "type": [
              "string",
              "null"
            ]
          },
          "size": {
            "$ref": "#/components/schemas/Size"
          },
          "lines": {
            "type": "integer",
            "description": "Sale lines added up."
          },
          "carats": {
            "type": "number",
            "description": "Their carats."
          },
          "amount": {
            "type": "number",
            "description": "Their amount."
          },
          "averagePricePerCarat": {
            "type": "number",
            "description": "`amount` ÷ `carats`, to the cent."
          },
          "currency": {
            "type": "string",
            "const": "USD"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "bad_request",
                  "unauthorized",
                  "not_found",
                  "method_not_allowed",
                  "rate_limited"
                ]
              },
              "message": {
                "type": "string",
                "description": "What went wrong and how to fix it."
              }
            }
          }
        }
      }
    }
  }
}
