Commission

Track platform commission owed and settle it via Stripe checkout

GET /admin/api/commission/summary

Return the merchant's current outstanding commission balance, the number of eligible-unpaid orders contributing to it, the fixed rate, the minimum payable threshold, and whether a payment can be started (can_pay is true when the balance meets the threshold).

GET /admin/api/commission/orders

List the eligible-unpaid order lines that make up the outstanding balance, newest first. Each line shows the commission base (subtotal minus discount) and the commission owed, both in minor units.

GET /admin/api/commission/payments

List the commission payment history, newest first. Each payment is one Stripe Checkout attempt with a frozen snapshot of the orders and total it covers.

GET /admin/api/commission/payments/{public_id}

Fetch a single commission payment by its public id, together with the snapshotted order lines it covers.

POST /admin/api/commission/payments

Start a commission payment. Snapshots the currently eligible-unpaid orders into a pending payment and creates a Stripe Checkout Session, returning the hosted checkout URL to redirect the merchant to. Idempotent: if a pending payment already exists, it is reused and its snapshot is not refreshed. Takes no request body.

POST /admin/api/commission/payments/{public_id}/reconcile

Fast-path confirmation after the merchant returns from Stripe Checkout. Retrieves the Checkout Session from Stripe and marks the payment paid or expired, returning the resulting status. The Stripe webhook remains the source of truth; this call is idempotent with it. Already-settled payments return their current status unchanged, and Stripe-retrieval failures are non-fatal (the payment stays pending for the webhook to settle). Takes no request body.

GET /admin/api/commission/summary

Response 200

{
  "outstanding_minor": 4275,
  "order_count": 12,
  "currency_code": "GBP",
  "threshold_minor": 1000,
  "rate_bps": 95,
  "can_pay": true
}

Example

curl "https://yourshop.zeroshop.io/admin/api/commission/summary" \
  -H "Authorization: Bearer zspat_..."

import requests

resp = requests.get(
    "https://yourshop.zeroshop.io/admin/api/commission/summary",
    headers={"Authorization": "Bearer zspat_..."}
)
summary = resp.json()

const resp = await fetch("https://yourshop.zeroshop.io/admin/api/commission/summary", {
  headers: { "Authorization": "Bearer zspat_..." }
});
const summary = await resp.json();

require "net/http"
require "json"

uri = URI("https://yourshop.zeroshop.io/admin/api/commission/summary")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer zspat_..."
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
summary = JSON.parse(resp.body)

GET /admin/api/commission/orders

List the eligible-unpaid order lines that make up the outstanding balance, newest first. Each line shows the commission base (subtotal minus discount) and the commission owed, both in minor units.

Response 200

[
  {
    "order_id": 482,
    "public_id": "A1B2C3D4E5F60718",
    "created_at": "2026-05-28T14:05:00Z",
    "commission_base": 25000,
    "commission_amount": 237
  },
  {
    "order_id": 479,
    "public_id": "0F1E2D3C4B5A6978",
    "created_at": "2026-05-27T09:30:00Z",
    "commission_base": 4000,
    "commission_amount": 38
  }
]

Example

curl "https://yourshop.zeroshop.io/admin/api/commission/orders" \
  -H "Authorization: Bearer zspat_..."

import requests

resp = requests.get(
    "https://yourshop.zeroshop.io/admin/api/commission/orders",
    headers={"Authorization": "Bearer zspat_..."}
)
orders = resp.json()

const resp = await fetch("https://yourshop.zeroshop.io/admin/api/commission/orders", {
  headers: { "Authorization": "Bearer zspat_..." }
});
const orders = await resp.json();

require "net/http"
require "json"

uri = URI("https://yourshop.zeroshop.io/admin/api/commission/orders")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer zspat_..."
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
orders = JSON.parse(resp.body)

GET /admin/api/commission/payments

List the commission payment history, newest first. Each payment is one Stripe Checkout attempt with a frozen snapshot of the orders and total it covers.

Response 200

[
  {
    "id": 7,
    "public_id": "9A8B7C6D5E4F3021",
    "status": "paid",
    "currency_code": "GBP",
    "rate_bps": 95,
    "total_amount": 4275,
    "stripe_session_id": "cs_test_a1b2c3",
    "stripe_payment_intent_id": "pi_3Nxyz",
    "created_at": "2026-05-20T10:00:00Z",
    "paid_at": "2026-05-20T10:02:11Z",
    "updated_at": "2026-05-20T10:02:11Z"
  },
  {
    "id": 6,
    "public_id": "1122334455667788",
    "status": "expired",
    "currency_code": "GBP",
    "rate_bps": 95,
    "total_amount": 1900,
    "stripe_session_id": "cs_test_zzz999",
    "stripe_payment_intent_id": null,
    "created_at": "2026-05-10T08:00:00Z",
    "paid_at": null,
    "updated_at": "2026-05-11T08:00:00Z"
  }
]

Example

curl "https://yourshop.zeroshop.io/admin/api/commission/payments" \
  -H "Authorization: Bearer zspat_..."

import requests

resp = requests.get(
    "https://yourshop.zeroshop.io/admin/api/commission/payments",
    headers={"Authorization": "Bearer zspat_..."}
)
payments = resp.json()

const resp = await fetch("https://yourshop.zeroshop.io/admin/api/commission/payments", {
  headers: { "Authorization": "Bearer zspat_..." }
});
const payments = await resp.json();

require "net/http"
require "json"

uri = URI("https://yourshop.zeroshop.io/admin/api/commission/payments")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer zspat_..."
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
payments = JSON.parse(resp.body)

GET /admin/api/commission/payments/{public_id}

Fetch a single commission payment by its public id, together with the snapshotted order lines it covers.

Response 200

{
  "payment": {
    "id": 7,
    "public_id": "9A8B7C6D5E4F3021",
    "status": "paid",
    "currency_code": "GBP",
    "rate_bps": 95,
    "total_amount": 4275,
    "stripe_session_id": "cs_test_a1b2c3",
    "stripe_payment_intent_id": "pi_3Nxyz",
    "created_at": "2026-05-20T10:00:00Z",
    "paid_at": "2026-05-20T10:02:11Z",
    "updated_at": "2026-05-20T10:02:11Z"
  },
  "orders": [
    {
      "order_id": 482,
      "public_id": "A1B2C3D4E5F60718",
      "created_at": "2026-05-28T14:05:00Z",
      "commission_base": 25000,
      "commission_amount": 237
    },
    {
      "order_id": 479,
      "public_id": "0F1E2D3C4B5A6978",
      "created_at": "2026-05-27T09:30:00Z",
      "commission_base": 4000,
      "commission_amount": 38
    }
  ]
}

Example

curl "https://yourshop.zeroshop.io/admin/api/commission/payments/9A8B7C6D5E4F3021" \
  -H "Authorization: Bearer zspat_..."

import requests

resp = requests.get(
    "https://yourshop.zeroshop.io/admin/api/commission/payments/9A8B7C6D5E4F3021",
    headers={"Authorization": "Bearer zspat_..."}
)
detail = resp.json()

const resp = await fetch("https://yourshop.zeroshop.io/admin/api/commission/payments/9A8B7C6D5E4F3021", {
  headers: { "Authorization": "Bearer zspat_..." }
});
const detail = await resp.json();

require "net/http"
require "json"

uri = URI("https://yourshop.zeroshop.io/admin/api/commission/payments/9A8B7C6D5E4F3021")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer zspat_..."
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
detail = JSON.parse(resp.body)

POST /admin/api/commission/payments

Response 200

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3",
  "public_id": "9A8B7C6D5E4F3021"
}

Example

curl -X POST "https://yourshop.zeroshop.io/admin/api/commission/payments" \
  -H "Authorization: Bearer zspat_..."

import requests

resp = requests.post(
    "https://yourshop.zeroshop.io/admin/api/commission/payments",
    headers={"Authorization": "Bearer zspat_..."}
)
result = resp.json()
checkout_url = result["checkout_url"]

const resp = await fetch("https://yourshop.zeroshop.io/admin/api/commission/payments", {
  method: "POST",
  headers: { "Authorization": "Bearer zspat_..." }
});
const result = await resp.json();

require "net/http"
require "json"

uri = URI("https://yourshop.zeroshop.io/admin/api/commission/payments")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer zspat_..."
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
result = JSON.parse(resp.body)

POST /admin/api/commission/payments/{public_id}/reconcile

Response 200

{
  "status": "paid"
}

Example

curl -X POST "https://yourshop.zeroshop.io/admin/api/commission/payments/9A8B7C6D5E4F3021/reconcile" \
  -H "Authorization: Bearer zspat_..."

import requests

resp = requests.post(
    "https://yourshop.zeroshop.io/admin/api/commission/payments/9A8B7C6D5E4F3021/reconcile",
    headers={"Authorization": "Bearer zspat_..."}
)
status = resp.json()["status"]

const resp = await fetch("https://yourshop.zeroshop.io/admin/api/commission/payments/9A8B7C6D5E4F3021/reconcile", {
  method: "POST",
  headers: { "Authorization": "Bearer zspat_..." }
});
const { status } = await resp.json();

require "net/http"
require "json"

uri = URI("https://yourshop.zeroshop.io/admin/api/commission/payments/9A8B7C6D5E4F3021/reconcile")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer zspat_..."
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
status = JSON.parse(resp.body)["status"]