Partner API Quickstart

Use this page for the shortest end-to-end Partner API path. It deliberately does not restate the complete authentication, error, endpoint, or compatibility contracts; the dedicated pages linked below own those details.

Before you start

You need:

a verified seller account with MFA enabled
Partner API access arranged through seller onboarding
a marketplace access token for that signed-in seller
an integration environment that can retain request IDs and replay keys

Two paths for catalogue data:

Path	Who	How
Portal / spreadsheet	Most sellers	Products or Inventory Bulk Operations while signed in — no machine API key
API / automation	Technical integrations	Session token exchange below, then feed-runs or product routes

Long-lived machine API keys (mint/revoke in Account without a browser session) are not a self-service product yet. Do not invent keys in Account; use the signed-in portal for bulk files, or the session exchange flow for approved integrations.

Set the API root once:

export PARTNER_API_BASE_URL="https://partner-api.oziosko.com.au/api/v1"

Use a non-production API root only when OKNowShop has explicitly issued one for your integration. Do not infer an environment URL from the production hostname, and do not point an automated client at production before seller onboarding has approved it.

1. Exchange the seller session

Exchange the current marketplace token for a short-lived, seller-scoped Partner API token:

curl -X POST "$PARTNER_API_BASE_URL/auth/exchange" \
  -H "Content-Type: application/json" \
  -d '{"supabase_token":"<marketplace-access-token>"}'

Store the returned bearer token in memory and send it on later requests:

export PARTNER_API_TOKEN="<partner-api-token>"
curl -H "Authorization: Bearer $PARTNER_API_TOKEN" \
  "$PARTNER_API_BASE_URL/dashboard/summary"

Production exchange requires MFA assurance level aal2. Do not build a production client around the development-only password token route. The Authentication contract owns token lifecycle, failure states, seller binding, and credential handling.

2. Confirm seller scope

Use a read request such as GET /dashboard/summary or GET /products to confirm that:

the token is accepted;
the response belongs to the intended seller; and
your client records X-Request-ID for support and reconciliation.

Never accept a seller ID from an end user and use it to switch API scope. Sign in as the intended seller and exchange that seller's marketplace session.

3. Choose one catalog path

Catalog need	Supported starting point
Create or update a small catalog in the UI	Partner Portal Products
Import a spreadsheet in the UI	Partner Portal Inventory → Bulk Operations
Create or update a small catalog via API	Product routes under `/products` with a session-exchanged bearer token
Import Shopify, Amazon seller, eBay, or Etsy-shaped CSV via API	Compatibility profile + durable `/products/feed-runs` (same bearer token)
Update stock in bulk via API	Inventory feed run
Reconcile your source system	Product/inventory export plus feed-run row results

For a file integration over the API, read the runtime envelope before uploading:

curl -H "Authorization: Bearer $PARTNER_API_TOKEN" \
  "$PARTNER_API_BASE_URL/products/feed-contract"

Then submit a durable run with a replay-safe key:

curl -X POST \
  "$PARTNER_API_BASE_URL/products/feed-runs?feed_type=products&profile_id=<profile_id>" \
  -H "Authorization: Bearer $PARTNER_API_TOKEN" \
  -H "Idempotency-Key: <stable-key-for-this-file-and-operation>" \
  -F "file=@products.csv"

Poll the returned status URL and retain row results. If the run returns a curation batch_id, submit the linked batch before expecting imported products to become approved listings. The Seller Integration Program owns compatibility profiles, feed semantics, supported data directions, and the full rollout checklist.

4. Prove one order lifecycle

List the signed-in seller's work:

curl -H "Authorization: Bearer $PARTNER_API_TOKEN" \
  "$PARTNER_API_BASE_URL/orders?status=pending&page=1"

Acceptance is per order item and requires an empty JSON body:

curl -X POST \
  "$PARTNER_API_BASE_URL/orders/items/<order_item_id>/accept" \
  -H "Authorization: Bearer $PARTNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Shipping is recorded through the current shipping-manifest path, not a guessed per-order /ship endpoint:

curl -X POST "$PARTNER_API_BASE_URL/orders/shipping-manifest" \
  -H "Authorization: Bearer $PARTNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '["<order_item_id>"]'

Use data from the approved test environment to prove the transition and reconcile the resulting seller order state before automating a queue.

5. Add event delivery

Use /webhooks only after the polling/reconciliation path works. Your receiver must verify the configured signature, retain a delivery identifier for replay safety, and acknowledge only after durable processing. Treat webhook delivery as an accelerator, not the sole record of order or financial state.

Use the OpenAPI document for your issued environment for the current registration schema and supported event names. Do not copy event lists from old screenshots or examples.

Production checklist

Which page owns what?

Page	Canonical responsibility
This quickstart	One minimal seller-authorized catalog/order/event path
Seller Integration Program	Supported data in/out, compatibility position, rollout checklist
API Overview	Module map, availability qualifications, plan and data caveats
Authentication	Token exchange, MFA, seller binding, and credential failures
Errors	Error envelope, status meanings, correlation IDs, and retry boundaries
Environment OpenAPI	Current request/response schemas and endpoint parameters

If those sources disagree, use the current environment OpenAPI for wire shape, Feature Availability for supported workflow status, and Partner Portal for the seller account's enabled packaging.

Before you start​

1. Exchange the seller session​

2. Confirm seller scope​

3. Choose one catalog path​

4. Prove one order lifecycle​

5. Add event delivery​

Production checklist​

Which page owns what?​