GET /v1/orders returns the canonical orders for the shops your API key can see. GET /v1/events returns the same changes as outbound webhooks.
Order
Each order has an id prefixed ord_, a connection id prefixed conn_, a platform (shopee, tiktok_shop, lazada, shopify, or mock on Sandbox), a platform order id, a status, and optional fulfillment fields such as tracking number.
Statuses move forward only. A pending order can become ready to ship. Jumping from pending straight to shipped is ignored until a legal intermediate status arrives. A fulfilled Shopify order is stored as shipped, not completed, because ready to ship cannot move directly to completed.
Canonical status values match the OpenAPI enum: unpaid, pending, ready_to_ship, shipped, delivered, completed, cancelled, in_refund, refunded.
Money and address fields
All amounts in totals and line item price are decimal strings (for example "99.00"). Currency is on the order root as currency.
| Platform | shipping_address.country source | totals.discount |
|---|---|---|
| Shopee | recipient_address.region from the platform payload | voucher_from_seller + voucher_from_shopee, or "0.00" when both are absent |
| TikTok Shop | recipient_address.region_code | payment.seller_discount + payment.platform_discount, or "0.00" |
| Lazada | Shipping address country when present | voucher, otherwise voucher_seller + voucher_platform |
| Shopify | Shipping address country | Mapped from total_discounts |
Sandbox (mock) | "MY" on sample orders | "0.00" |
country is not normalized to ISO 3166 across platforms. Treat it as the marketplace’s own region or country code string.
| Platform | city | state | postal_code | country |
|---|---|---|---|---|
| Shopee | recipient_address.city | recipient_address.state | recipient_address.zipcode | recipient_address.region |
| TikTok Shop | recipient_address.district_info (city level) | district_info (state or province) | postal_code when present | region_code |
| Lazada | address_shipping.city | address_shipping.address2 when present | post_code | country when present |
| Shopify | Shipping address city | Shipping address province | Shipping address zip | Shipping address country |
Sandbox (mock) | Sample city on test orders | Sample state | Sample postal code | "MY" on sample orders |
Fields stay null when the marketplace payload omits them.
Fulfillment fields (read path)
On GET /v1/orders and webhooks, fulfillment is a snapshot of what the marketplace already stored when Ongapi last synced the order. It is not updated by your app until you call a write endpoint below or the platform pushes a change.
waybill_url on the order object is a tracking link when the platform sends one, not a PDF label download. Use GET /v1/orders/{id}/shipping-label for marketplace AWBs when supported.
| Platform | tracking_number | shipping_provider | waybill_url |
|---|---|---|---|
| Shopee | Logistics tracking when Shopee returns one; otherwise null | Carrier from order detail | Always null (not a PDF label URL) |
| TikTok Shop | Package tracking when present | Package carrier name | Always null |
| Lazada | tracking_code from order items when present | shipment_provider from the same row | Always null |
| Shopify | Fulfillment tracking number | Fulfillment carrier | Shopify tracking_url when set (tracking link, not a marketplace AWB) |
Sandbox (mock) | null unless your test payload sets fulfillment | Same | null |
Events
Event ids use the prefix evt_.
| Type | When |
|---|---|
order.created | The order is stored for the first time |
order.updated | Status or fulfillment changed. changed_fields lists what moved |
connection.reauth_required | The shop token must be authorized again |
On Sandbox, post a mock webhook to create an order, then read it back with your test key. See Getting started.
Write APIs (integrations)
| Endpoint | Purpose |
|---|---|
POST /v1/orders/{id}/ship | Push seller tracking or request platform logistics (mode: seller_tracking or platform_logistics). Requires Idempotency-Key. Updates fulfillment and emits order.updated. |
GET /v1/orders/{id}/shipping-label | Download or fetch a platform AWB when the marketplace provides one. Shopify returns waybill_unavailable. |
GET /v1/connections/{id}/warehouses | List warehouse or location ids for inventory writes. |
PUT /v1/connections/{id}/inventory | Set available quantity per SKU or platform_item_id and warehouse_id. Requires Idempotency-Key. |
Sandbox (mock): all write calls return success and update the canonical order (ship also emits order.updated).
Live shops: Shopee, TikTok Shop, and Lazada call the marketplace for ship, shipping labels, warehouses, and inventory. Shopify POST …/ship accepts only seller_tracking and creates a fulfillment; platform_logistics returns capability_unsupported. Shopify GET …/shipping-label always returns HTTP 409 with waybill_unavailable. Shopify warehouses and inventory use Admin locations and inventory levels.
Missing partner scopes return HTTP 501 with capability_unsupported. Re-authorize the shop after partner scopes are added. Shopify platform_logistics also returns 501 capability_unsupported (seller tracking only). A label that the marketplace cannot print yet returns HTTP 409 with waybill_unavailable. Idempotency-Key is stored for 24 hours: the same key replays the first successful response and does not call the platform again.
For seller_tracking, Shopee requires tracking_number only. TikTok Shop and Lazada also require shipping_provider (TikTok: carrier id or exact provider name from TikTok logistics; Lazada: carrier name such as LEX).
Error code | HTTP | When |
|---|---|---|
invalid_request | 400 | Missing or invalid body (for example tracking_number or shipping_provider) |
waybill_unavailable | 409 | No platform AWB (always for Shopify; or order not ready on SEA marketplaces) |
capability_unsupported | 501 | Missing OAuth scopes for this write, or unsupported mode (for example Shopify platform_logistics) |
platform_error | 502 | Marketplace API failed; response may include the platform message |