Gallery Platform API
Reference

List sales

Lists the gallery's sales (newest first) with cursor pagination. Filter by `status`, or search with `q` — matches the buyer contact's name (minimum 3 characters).

GET
/gallery/sales

Lists the gallery's sales (newest first) with cursor pagination. Filter by status, or search with q — matches the buyer contact's name (minimum 3 characters).

Authorization

bearerAuth sales:read, contacts:read
AuthorizationBearer <token>

A gallery API key, sent as Authorization: Bearer gpk_… (or the x-api-key header).

In: header

Scope: sales:read, contacts:read

Query Parameters

limit?integer

Page size. Defaults to 20; the maximum is 100.

Range1 <= value <= 100
Default20
cursor?string

Opaque cursor from the previous page's next_cursor. Omit for the first page.

status?string

Filter to the given status; the schema's enum lists the values.

Value in

  • "draft"
  • "confirmed"
  • "completed"
  • "canceled"
  • "refunded"
q?string

Free-text search over the resource's searchable fields.

Length3 <= length <= 200
buyer_contact_id?string

Filter to the given buyer contact id.

tag_id?array<string>

Filter to the given tag id.

Items1 <= items <= 10
sort?string

Sort by one of: created, sold, value (default created).

Value in

  • "created"
  • "sold"
  • "value"
dir?string

Sort direction (default desc).

Value in

  • "asc"
  • "desc"

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

{  "data": [    {      "id": "string",      "buyer_contact_id": "string",      "sold_by": "string",      "status": "draft",      "currency": "string",      "sale_date": "string",      "gross_cents": -9007199254740991,      "discount_cents": -9007199254740991,      "net_cents": -9007199254740991,      "fx_as_of": "string",      "fx_usd_per_unit": 0,      "fx_base_currency": "string",      "fx_base_usd_per_unit": 0,      "base_amount_cents": -9007199254740991,      "notes": "string",      "metadata": {        "property1": "string",        "property2": "string"      },      "created_at": "string",      "updated_at": "string",      "items": [        {          "id": "string",          "artwork_id": "string",          "list_price_cents": -9007199254740991,          "discount_cents": -9007199254740991,          "sold_price_cents": -9007199254740991,          "consignor_share_bps": 0,          "consignee_share_bps": 0,          "third_party_share_bps": 0,          "consignor_net_price_cents": 0,          "metadata": {            "property1": "string",            "property2": "string"          },          "created_at": "string"        }      ]    }  ],  "next_cursor": "string"}

Remove a sale line item DELETE

Removes a work from a sale. Header totals refresh automatically.

Get a sale's cost basis and margin GET

Returns the cost basis and margin of a sale, per line and in total: the consignor and third-party takes (from the payables) plus the gallery's borne production-cost share, subtracted from the sold price. A missing or unauthorized sale is a 404.