Seller Integration Program
Use this page as the partner/seller integration checklist. It packages the current Partner API, CSV/feed imports, webhook delivery, exports, and rollout boundaries into one implementation path.
This page owns supported data directions, compatibility boundaries, and the production checklist. Use the Partner API Quickstart for the shortest first integration; use Authentication, API Overview, and Errors for their respective normative contracts.
Program Entry Points
| Need | Start here |
|---|---|
| First API test | Integration Guide |
| Endpoint map | API Overview |
| Authentication/token rules | Authentication |
| Error handling | Errors |
| Plan limits and packaging | Partner Portal → Settings → Billing |
| Operational caveats | API Overview (402 / empty analytics) |
| Supplier-backed seller flows | Supply Network |
| Financial exports and values | Financial Records API |
Non-production OpenAPI docs are available at /docs, /redoc, and
/openapi.json on the partner API host. Production interactive docs are not a
self-service contract surface; use staging/local OpenAPI for client generation
and integration tests.
Access Model
- Production auth uses marketplace/Supabase SSO exchange:
POST /api/v1/auth/exchange. - Do not build production clients against development-only password-token endpoints.
- Every protected route is seller-scoped server-side.
- OKNowShop does not yet expose public self-service app registration, OAuth scopes, or third-party app marketplace approvals. Implementation partners should use seller-authorized API access arranged through onboarding.
Supported Data In
| Surface | Current path | Notes |
|---|---|---|
| Catalog create/update | POST/PUT /api/v1/products | Uses product identity rules; product visibility still follows curation. |
| Product images | Product image upload APIs and product image routes | Use hosted image URLs or upload fallback where supported by Partner Portal/API. |
| Inventory updates | Product inventory APIs, inventory CSV import | Seller-owned stock path; supplier-backed availability is separate from supplier source stock. |
| Durable product/inventory feeds | POST /api/v1/products/feed-runs | Canonical coordinated integration path; atomically persists applied rows, status, row evidence, and replay key. |
| Runtime feed envelope | GET /api/v1/products/feed-contract | Canonical byte, row, content-type, and synchronous execution-time limits used by the API and seller portal. |
| Compatibility profiles | POST /api/v1/products/import-profiles/detect, POST /api/v1/products/import-profiles | Shopify, Amazon seller product, eBay File Exchange, and Etsy listings v1 shapes are currently documented. |
| Shopify channel sync | Shopify OAuth and signed Shopify webhooks | Product create/update/delete and inventory_levels/update are mapped to seller catalog/channel state. |
| Order operations | /api/v1/orders lifecycle routes | Seller order workflow, not full external marketplace OMS parity. |
| Seller-side supplier workflows | /api/v1/dropship, /api/v1/wholesale, /api/v1/sourcing | Seller-facing supplier network operations; supplier-operator APIs live in supplier docs. |
Supported Data Out
| Surface | Current path | Notes |
|---|---|---|
| Product/catalog export | GET /api/v1/products/export | CSV/JSON export for reconciliation and round-trip editing. |
| Inventory export | Inventory export routes in products module | Use for stock reconciliation; feed-run status is separate. |
| Order queues/status | GET /api/v1/orders and detail routes | Poll when webhook delivery is not enough. |
| Financial records | /api/v1/financials, /api/v1/payouts | Use for seller payout and settlement reconciliation. |
| Webhook events | /api/v1/webhooks | Signed delivery, retry handling, and event subscriptions. |
| Feed-run status/evidence | GET /api/v1/products/feed-runs/{run_id} and /row-results | Use for integration dashboards, retry decisions, and support evidence. |
Compatibility Position
OKNowShop is compatibility-first at the edge, not a new universal PIM format. Current seller feed work supports practical ingestion from common marketplace and store exports, then normalizes into OKNowShop identity, curation, inventory, checkout, settlement, and claim-evidence rules.
Integration is inbound-first for catalog, inventory, and identity: sellers bring product data into OKNowShop from tools they already run. There are two distinct outbound directions, and they are treated differently:
- Commerce data back to your own systems — a goal. OKNowShop returns orders, fees, refunds, and payouts, and on the roadmap trade documents (purchase orders, invoices, receipts, remittance, credit notes), so you can run normal accounting/ERP/OMS workflows in your existing tools — for example importing OKNowShop's settlement and marketplace-activity CSV export into Xero/MYOB/QuickBooks (you import the export; OKNowShop does not push into your accounting software), or supplier document exchange.
- Listing syndication out to other marketplaces — not a seller feature. OKNowShop is not a channel manager and does not push your listings back out to Amazon, eBay, or others. There is no launch merchant-of-record rail that resells supplier SKUs as OKNowShop. A 1P outbound path would be a separately approved contingency, not a seller integration.
Current profile scope:
- Shopify products v1: useful for small seller/source-of-truth catalog exports.
- Amazon seller products v1: useful for SKU, title, price, quantity, brand, and identifier import.
- eBay File Exchange v1: useful for listing/offer migration basics.
- Etsy listings v1: useful for handmade/maker sellers migrating listing basics.
Shopify channel scope:
- Shopify product create/update webhooks can create or update seller catalog rows using the same product identity rules as other seller imports.
- Shopify product delete webhooks deactivate mapped seller/channel rows.
- Shopify
inventory_levels/updatewebhooks resolve by Shopifyinventory_item_id; unknown inventory items are recorded as action-required integration issues rather than guessed from SKU or barcode. - Shopify order webhooks are recorded for visibility only. They do not create, accept, cancel, allocate, or fulfill OKNowShop orders yet.
Not a goal:
- Outbound listing syndication / channel management to Amazon, eBay, or other external marketplaces as a seller feature. OKNowShop ingests from these sources; it does not push seller listings back out to them.
Not yet claimed:
- Full Amazon/eBay/Mirakl inbound API parity (current support is file/profile ingestion, plus Shopify live webhooks).
- Self-service public app store registration and OAuth app scopes.
- Full external OMS/order-ingestion parity for Shopify/Amazon/eBay.
- Supplier trade-document exchange (supplier invoices, receipts, ASN-style documents) as a published seller API.
Go-Live Checklist
- Staging token exchange tested and refresh/re-auth path implemented.
- Product identity strategy chosen: OKNowShop
product_id, global ID,MPN_BRAND, or explicit identifier exemption. - Feed imports use durable
/products/feed-runswithIdempotency-Key. - Upload code reads
/products/feed-contractand handles typed413,422, execution-failure, and timeout responses. - Row errors and warnings are stored in your integration dashboard.
- Product curation batch submission is handled for imported products.
- Webhook signatures are verified and delivery IDs are stored for replay safety.
- Pagination, 409 conflict handling, 402 plan boundaries, and 429/5xx retry policy are implemented.
- Unsupported parity gaps are documented in your operating runbook.