Orders & Plugin API
List merchant orders and reference WooCommerce plugin routes, including plan/quota access payloads, merchant-only shipment holds, access-blocked re-polls, status sync, and deletion.
Merchant Order Routes
/api/v1/orders/api/v1/orders/:idThese JWT-authenticated routes are always scoped to the token's merchantId. The list is paginated; detail returns the order and its shipments. Platform-neutral logic uses externalOrderId, not the legacy WooCommerce-only wcOrderId.
WooCommerce Plugin Authentication
Protected routes below /plugin/* bypass the merchant JWT guard but are authenticated by plugin middleware. The current plugin sends its API key plus the current WordPress site URL in X-OT-Store-URL; legacy store flows use HMAC headers. After normalizing case and trailing slashes, the middleware requires the header to exactly match the store bound to the key before it attaches merchant/store context, records key use, or runs the route.
/api/v1/plugin/health/api/v1/plugin/woocommerce/latest/api/v1/plugin/heartbeat/api/v1/plugin/orders/sync/api/v1/plugin/shipments/repoll/api/v1/plugin/shipments/statuses/api/v1/plugin/shipments/delete| Route | Purpose |
|---|---|
plugin/health | Validate the stored plugin key and return connected store context plus a complete plan, usage, quota, renewal/trial/cancellation lifecycle, shipmentAccess, and merchant-facing access-copy snapshot. |
plugin/dashboard-summary | Return selected-range operational metrics and exact-sum status percentages, a zero-filled 12-month volume series, and all-time carrier/destination performance scoped to the bound merchant and exact WooCommerce store. analyticsScopes documents each cohort. |
plugin/woocommerce/latest | Return current plugin release metadata (1.1.55). |
plugin/heartbeat | Update scheduled/admin heartbeat and environment metadata, then return the same complete plan, usage, quota, lifecycle, and access snapshot. |
plugin/orders/sync | Idempotently create/update a platform-neutral order, its normalized shippingAddress destination country, and its tracking numbers. Each tracking item may include an HTTP(S) trackingLink for a custom provider. Bulk sync traffic is isolated by the authenticated store; each shipment result reports trackingState and nullable trackingHoldReason. |
plugin/shipments/repoll | Request an immediate carrier check, or return 402 SHIPMENT_ACCESS_BLOCKED with access details when held. |
plugin/shipments/statuses | Read carrier status plus operational tracking state/hold reason without polling the carrier. |
plugin/shipments/delete | Delete a shipment for the authenticated store/order. |
trackingState: held and its hold reason are merchant-only processing metadata. They must not replace the shipment's carrier status or be written into a customer event timeline.