API Overview
The OKNowShop Partner API powers seller-scoped catalog, order, shipping, financial-record, and controlled integration workflows.
This page describes API surface area, not a promise that every route is available to every account. Account configuration, plan entitlements, and the status in Feature Availability still apply. A successful response should be used only for the purpose and data meaning documented for that endpoint.
Authentication
Production authentication exchanges the signed-in seller’s marketplace session for a short-lived Partner API token. The exchange requires MFA assurance level aal2, and the resulting token is scoped to that seller.
- Production:
POST /api/v1/auth/exchange - Seller profile creation/binding:
POST /api/v1/auth/register
For detailed setup, see Authentication Guide.
API Endpoints
All endpoints are prefixed with /api/v1/. Interactive OpenAPI documentation is available at /docs in non-production environments.
Supplier-operator endpoints are documented outside this doc set; seller-facing supplier-network workflows remain in scope here. See Partner vs Supplier Scope.
Core Commerce
| Module | Base Path | Description |
|---|---|---|
| Auth | /api/v1/auth | Supabase token exchange, seller registration, and development login |
| Sellers | /api/v1/sellers | Seller profile, settings, business details |
| Products | /api/v1/products | Product catalog CRUD, images, bulk operations |
| Pricing | /api/v1/pricing | Account-gated pricing endpoints; competitive recommendations and automation are not currently available for live price changes |
| Orders | /api/v1/orders | Seller order lines — accept/reject, dispatch, labels, and tracking |
| Shipping | /api/v1/shipping | Seller profiles/rules, quotes, labels, tracking, and read-only provider/service catalog |
| Fulfillment | /api/v1/fulfillment | Deferred/pilot BOPIS and fulfilment support; currently unavailable as a seller workflow |
| Inventory | /api/v1/products | Stock tracking, reorder points (via products module) |
Financial
| Module | Base Path | Description |
|---|---|---|
| Payment processing | Customer checkout rails | Customer payment capture is processed outside seller-writable Partner API routes |
| Payout setup | /api/v1/payouts | Stripe Connect onboarding and dashboard links |
| Payout records | /api/v1/payments/payouts | Seller-scoped payout record reads and history |
| Fees | /api/v1/fees | Commission structures, transaction fees |
| Financials | /api/v1/financials | Financial records, settlements, marketplace activity, and exports |
| Billing | /api/v1/billing | Account entitlement/catalog reads; paid subscription checkout is currently disabled |
Analytics & Intelligence
| Module | Base Path | Description |
|---|---|---|
| Dashboard | /api/v1/dashboard | Seller operational summaries and action projections under their stated source contract |
| Analytics | /api/v1/analytics | Deferred portal analytics; API payloads are source/data dependent |
| Pricing Intelligence | /api/v1/pricing | Not currently available for live pricing decisions; see the Pricing Intelligence guide |
| Forecasting | /api/v1/forecasting | Limited computed projections; history and source coverage required |
| Marketplace Intel | /api/v1/marketplace-intel | Limited account-enabled on-platform aggregates; no standard portal workflow is currently supported |
| Cost Components | /api/v1/profitability | Coverage-gated known cost components where source-backed data exists |
| Customer Analytics | /api/v1/customer-analytics | RFM segmentation, cohort analysis, LTV |
| Search Insights | /api/v1/search-insights | Limited account-enabled query signals; empty means no usable report, not measured zero demand |
Marketing & Growth
| Module | Base Path | Description |
|---|---|---|
| Marketing | /api/v1/marketing | Marketing support APIs for enabled growth workflows |
| Offers | /api/v1/offers | Deferred coupon/discount endpoints; currently unavailable as a seller workflow |
Seller Operations
| Module | Base Path | Description |
|---|---|---|
| Onboarding | /api/v1/onboarding | Guided seller setup wizard, progress tracking |
| KYC | /api/v1/kyc | Know Your Customer verification |
| Seller Agreements | /api/v1/seller-agreement | Terms acceptance, agreement management |
| ABN Validation | /api/v1/sellers/validate-abn | Australian Business Number verification |
| Quality | /api/v1/quality | Listing-readiness substrate; dedicated Quality portal routes are deferred |
| Reviews | /api/v1/reviews | Ratings/private-feedback substrate. Public review text/count and shopper-visible seller replies are not currently supported |
| Customer Service | /api/v1/customer_service | Ticket management, SLA tracking (Beta) |
| FAQ | /api/v1/faqs | Product and brand FAQ management |
Engagement & Communication
| Module | Base Path | Description |
|---|---|---|
| Messaging | /api/v1/messages | Buyer-seller messaging, conversation threads |
| Notifications | /api/v1/notifications | Seller notifications (review alerts, order updates), polled by the seller portal |
| UGC | /api/v1/ugc | Account-gated content endpoints; currently unavailable as a seller workflow |
| Marketplace Loyalty | /api/v1/loyalty | Unified loyalty program, points wallet (Beta) |
Platform & Compliance
| Module | Base Path | Description |
|---|---|---|
| Audit | /api/v1/audit | Seller-authorised activity-log reads where enabled |
| Webhooks | /api/v1/webhooks | Outbound webhook management and delivery records |
Supply Network (Seller-facing)
| Module | Base Path | Description |
|---|---|---|
| Wholesale | /api/v1/wholesale | Seller-side B2B purchasing, supplier catalog access, and wholesale order workflows (Beta) |
| Dropship | /api/v1/dropship | Seller-side supplier-backed listing, routing, and dropship order workflows (Beta) |
For the seller-facing workflow model across onboarding, catalog sync, supplier connection review, dropship orders, and settlement reconciliation, see Supply Network.
Integrations
| Module | Base Path | Description |
|---|---|---|
| Channels | /api/v1/channels | Multi-channel listing management (Beta) |
| Shopify Webhooks | /api/v1/webhooks/shopify | Product/catalog and supported inventory events; order events are visibility-only |
| Stripe Webhooks | /api/v1/webhooks/stripe | Provider callback receiver; not a seller integration endpoint |
Seller Plans and HTTP 402
Some endpoints are part of paid seller plans (Free / Small / Big). Calling a gated endpoint on a plan that does not include it returns HTTP 402 with a structured body your integration should handle:
{
"error": "feature_not_available",
"feature_name": "auto_reprice",
"tier": "free",
"message": "The auto reprice feature is not available on the Free tier.",
"upgrade_url": "/settings/billing"
}
Count-limited resources return "error": "tier_limit_exceeded" with
current_usage and limit fields. Treat 402 as a stable plan boundary, not a
transient failure — do not retry. See Partner Portal Settings → Billing for
what your plan includes. For cache-first empty analytics and similar operational
caveats, treat empty payloads as “no usable snapshot,” not as a measured zero.
An entitlement response only grants access; it does not prove source quality or
activate a currently unavailable workflow.
Analytics Freshness
Some dashboard and analytics families are pre-computed and served from cache.
Freshness varies by source contract; not every family is scheduled, populated,
or approved for current use. Consumers must inspect generated_at, cache_status,
source_contract, semantic-status, and missing-component fields where supplied.
Do not assume an empty payload will populate overnight, and do not replace a
missing component with zero.
Security Model
Protected seller routes authenticate and resolve seller scope server-side. Public health, registration, published-rate, and provider-callback routes have different authentication contracts. Do not treat route registration or a bearer token as permission to read another seller's data; use the current OpenAPI and authentication dependency for the endpoint being integrated.
Rate Limiting
Handle 429 responses with bounded exponential backoff and respect
Retry-After when present. This handbook does not publish a fixed global
requests-per-second allowance because enforcement can differ by endpoint,
environment, and edge policy. Use the limit communicated for your coordinated
integration.
Error Handling
Error envelopes vary by route family: domain and HTTP handlers commonly return
a detail, validation uses FastAPI's structured detail list, and feed runs
use their typed row-result envelope. See Error Reference for the
supported shapes and retry rules.
Getting Started
- Create your seller account and complete verification in Partner Portal.
- Authenticate — exchange your marketplace session for an API token. See Authentication.
- Make your first call —
GET /api/v1/dashboard/summaryreturns the seller-scoped dashboard summary when the source contract is available. - Explore the contract — the generated OpenAPI reference describes the mounted HTTP surface in non-production environments. It does not grant an account entitlement. See the Integration Guide for product sync, webhooks, and reconciliation patterns.
Versioning
- Current version:
v1 - Documented seller API families are prefixed with
/api/v1/; health, documentation, metrics, and internal service routes have separate paths and are not seller integration surfaces. - Breaking changes will introduce new versions
Support
- API Status: status.oknowshop.com.au
- Health Check:
GET /health— service availability - Seller Support: seller-support@oknowshop.com.au