8Merch Ecommerce API (1.0.0)

1. Get a key. Keys are issued by 8Merch - ask your account manager. A key can read all your stores (including ones you connect later) or only the ones you choose. You receive it once; keep it on your server, never in a browser or app. Every request sends it:

curl https://api.8merch.com/ecommerce/v1/account \
  -H "Authorization: Bearer $EIGHTMERCH_ECOMMERCE_KEY"

2. List your statements for a period - one per store per month:

curl "https://api.8merch.com/ecommerce/v1/statements?period_from=2026-07&period_to=2026-09" \
  -H "Authorization: Bearer $EIGHTMERCH_ECOMMERCE_KEY"

3. Read one in full - totals, sales by product, refunds, extra costs and the payout: GET /statements/{id}. Its orders, each with its own figures, are at GET /statements/{id}/orders.

4. Or pull a whole quarter at once across every store: GET /sales?period_from=2026-07&period_to=2026-09 gives one row per product per store per month, with the product's vendor (normally the artist) on each row - ready to group for royalties. GET /refunds is its counterpart for refunds.

5. Reconcile payouts with GET /payouts: what we owe or have paid for each statement.

Every figure is frozen when the statement is generated and never changes afterwards. Amounts are in the statement's currency (the currency of the region the store sells from), rounded to 2 decimals.

Which month an order belongs to. A sale is on the statement for the month it was fulfilled (shipped), not the month it was ordered. A refund is on the statement for the month it was made, once its order has been fulfilled - a refund made before shipping waits for the statement of the month the order ships.

Extra costs that are bigger than the payout are part-deducted and the rest is carried to the next statement. Each extra cost line shows amount (deducted here), original_amount and carried_amount.

Sales by product. Inside an order with several products, the order's frozen net value, VAT and cost of goods are shared across its products in proportion to price and product cost. The per-product lines always add up to the order's figures, and the orders always add up to the statement.

When statements appear. A statement is visible here once 8Merch has reviewed and approved it - the same moment it appears in your portal. A month with no sales and no costs still gets a statement, with status no_activity and every figure zero.

Each statement belongs to one store (store, store_name). Filter any list with store=st_..., or leave it out to read every store your key covers (GET /stores lists them).

For royalties, GET /sales is the endpoint you want. Every row carries product_vendor - the vendor field of the product in the store, which is normally the artist or brand - and you can filter to one with product_vendor=.... Subtract that artist's rows from GET /refunds' items (matched by SKU) for the same period to get their net.

Sales are reported per statement currency. If your stores sell in different regions you will see USD, EUR and GBP rows side by side - we never convert between them.

Marketplace stores (is_marketplace: true), which settle with each vendor separately, are not covered by this version of the API.

Errors share one shape, with a stable code to branch on and a request_id to quote to us:

{"error":{"type":"invalid_request","code":"invalid_period","message":"period must be YYYY-MM.",
          "param":"period","request_id":"req_8sK2..."}}

Every response carries a Request-Id header, and RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset.

Lists return {"data": [...], "has_more": true, "next_cursor": "..."}. Pass cursor=<next_cursor> for the next page until has_more is false. /sales and /refunds are bounded by their period instead and return everything at once.

Can I see this month's sales so far? No - only statements, which are generated after the month ends. Your portal's Orders tab shows live orders.

Why does a statement's per-product cost look slightly different from the product's cost? Inside multi-product orders the order's frozen cost is shared across its products (see above); single-product orders always match exactly. The statement totals are the figures that were paid.

Will a statement ever change? Not once it is approved - that is when it appears here. Its figures are frozen.

When was a payout paid? payout.status becomes paid once the money has been sent. The exact transfer date is on your Stripe Express dashboard.

Is there a sandbox? Not for this API: it is read-only, so a key can safely be pointed at your real data from day one.

Who the key belongs to and which stores it covers.

Monthly statements - one per store per month - in full.

Sales and refunds flattened across stores and months, for accounting and royalties.

What we owe you, and what we have paid.

Your products, their cost and the stock we hold.