Gallery Platform API

Invoicing & payments

Create invoices through the API and collect payment on the gallery's Stripe — get a hosted checkout link in the create response and settle via webhooks.

You can issue invoices and get paid entirely through /api/v1. Buyers pay on a Stripe-hosted checkout page on the gallery's own connected account, so the gallery is the merchant of record and your integration never touches card data. This is the Shopify-style pattern: you orchestrate, the platform is the system of record and the payment rail.

The flow

  1. Create a sale — an invoice always belongs to a sale (POST /gallery/sales).
  2. Issue an invoice for that sale with create_checkout_link: true (POST /gallery/invoices). The response includes a hosted checkout_url.
  3. Send the buyer to checkout_url to pay.
  4. Receive webhooks — payment.recorded when a payment settles and invoice.paid once the invoice is fully paid (see Webhooks).

Issue and collect in one call

curl -X POST https://app.example.com/api/v1/gallery/invoices \
  -H "Authorization: Bearer $GALLERY_API_KEY" \
  -H "X-Gallery-Slug: $GALLERY_SLUG" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "sale_id": "…",
    "currency": "USD",
    "total_cents": 250000,
    "create_checkout_link": true
  }'

The response is the invoice plus a checkout_url:

{
  "id": "…",
  "invoice_number": "INV-0007",
  "total_cents": 250000,
  "amount_paid_cents": 0,
  "currency": "USD",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_…"
}

Redirect the buyer to checkout_url. When they pay, the platform records the payment against the invoice and fires your webhooks — no polling required.

When checkout_url is null

The link is minted only when the gallery can actually collect. checkout_url is null if:

  • the gallery hasn't connected Stripe (or charges aren't enabled yet), or
  • the invoice has no outstanding balance (e.g. you created a header and will add line items in later calls, so the total is still 0).

In that second case, build up the invoice with POST /gallery/invoices/{id}/line-items, then mint a link on demand with POST /gallery/invoices/{id}/payment-sessions — the same hosted checkout, minted whenever you're ready.

Payment plans (installments)

Collect an invoice in stages — a deposit plus scheduled installments. Plan the installments in one call; the plan's total may not exceed the invoice total, and each installment is collected on its own hosted checkout.

# Plan a deposit + two installments
curl -X POST https://app.example.com/api/v1/gallery/invoices/$INVOICE_ID/payment-schedule \
  -H "Authorization: Bearer $GALLERY_API_KEY" \
  -H "X-Gallery-Slug: $GALLERY_SLUG" \
  -H "Content-Type: application/json" \
  -d '{
    "installments": [
      { "label": "Deposit",        "amount_cents": 100000, "due_date": "2026-08-01" },
      { "label": "Installment 1",  "amount_cents":  75000, "due_date": "2026-09-01" },
      { "label": "Installment 2",  "amount_cents":  75000, "due_date": "2026-10-01" }
    ]
  }'

Each installment comes back with an id, a sequence (0 = deposit), and a status (scheduled → paid when it settles). To collect one, mint a checkout link for it:

curl -X POST \
  https://app.example.com/api/v1/gallery/invoices/$INVOICE_ID/payment-schedule/$SCHEDULE_ID/collect \
  -H "Authorization: Bearer $GALLERY_API_KEY" \
  -H "X-Gallery-Slug: $GALLERY_SLUG" \
  -H "Idempotency-Key: $(uuidgen)"

Send the buyer to the returned url. When they pay, the platform records the payment against the invoice, marks that installment paid, and fires your payment.recorded webhook — the same settlement path as a one-shot checkout.

GET …/payment-schedule lists the plan; DELETE …/payment-schedule/{scheduleId} cancels an unpaid installment. Re-planning is refused once any installment has been paid.

Scopes

Issuing invoices needs the sales:write scope; minting payment links and reading payment state need payments:write / payments:read. Grant a key only the scopes your integration uses (see Authentication).

Webhooks

Register one endpoint per gallery and receive a signed JSON event whenever the gallery's content changes.

Invoke an action POST

Runs one declared action by key, with its input checked against the schema `GET /gallery/ontology/actions` lists. The action runs exactly as its named route runs it: the same handler, access rules and change log. A key needs every scope the action's named route requires: `artworks:create` for `create_artwork`, `artworks:update` for `update_artwork`, `artworks:delete` with `artworks:update` for `delete_artwork`, `contacts:create` with `gallery:read` for `create_party`, `contacts:update` with `gallery:read` for `update_party`, `contacts:delete` with `contacts:update` for `delete_party`, `contacts:delete` with `contacts:update` and `gallery:read` for `merge_parties`, `artists:create` for `create_artist`, `artists:update` for `update_artist`, `artists:delete` for `delete_artist`, `shows:update` with `artworks:read` for `add_to_show`, `shows:update` for `update_show_work` and `remove_from_show`, and `shows:update` with `shows:delete` and `artworks:read` for `convert_show_type`; without them the answer is 403. A gated or outward action, and any destructive one, needs `confirm: true`; without it the answer is 400 with `details.reason` `approval_required` and nothing changes. An action with no binding answers 400 with `details.reason` `not_invocable`, and input that fails the action's schema answers 400 with `details.reason` `invalid_input`. `draft` places a record write as the named PATCH places it: the working draft for `true`, the record for `false`, the principal's default when omitted. `update_artist` answers `applied_to` as `PATCH /gallery/artists/{id}` does, and delivers `artist.updated` only for an edit that lands on the record. `update_party` answers `applied_to` as `PATCH /gallery/parties/{id}` does, and refuses a key's or app's `null` sub-profile with 403. `merge_parties` takes the survivor as `target` and `merged_id` in `input`, answers the survivor as `POST /gallery/parties/{id}/merge` does, refuses a party merged into itself with 400 and `details.field` `merged_id`, and delivers the survivor's `contact.updated` (webhook action `contact.merged`), then the merged party's `contact.deleted`. The Show actions take the show as `target` (`artwork_id` in `input` names the work), answer as their `/gallery/shows/{showId}/…` routes do, and deliver one `show.updated` when the call changed the show. `dry_run=true` returns the effect the action would have and commits nothing: it runs the same scope, target and input checks and refuses a caller the write would refuse, but needs no `confirm`, which the real call still does.

On this page