Use case: Shipping and carrier platforms

This guide walks through the end-to-end integration for shipping platforms, carriers, and 3PL providers that need to retrieve orders from merchant stores and post fulfillment and tracking information back.

Overview of the flow

Merchant connects store → EcartAPI OAuth
        ↓
New order event fires → webhook delivery to your endpoint (free)
        ↓
Retrieve full order details → GET /api/v2/orders/{id}
        ↓
Pick, pack, ship
        ↓
Post fulfillment with tracking → POST /api/v2/orders/{id}/fulfillments

Step 1 — Connect merchant stores

Each merchant connects their store through your integration page (powered by EcartAPI OAuth). One merchant may have stores on multiple platforms — each store is connected separately and produces its own shop_id and access_token.

Store the shop_id and access_token for each connected store. Use shop_id as the stable key in your system (it does not change on reconnection). See Store identification for the recommended pattern.

Step 2 — Subscribe to order events

Subscribe to order creation (and optionally update) events for each connected store using that store's access_token. Embed the store identifier in the webhook URL so you know which store triggered the event.

POST /api/v2/webhooks
Authorization: Bearer {access_token}

{
  "resource": "orders",
  "action": "create",
  "url": "https://yourplatform.com/webhooks/{shop_id}/orders/create"
}

Repeat this for each store you manage. Webhook deliveries are free and do not count toward your monthly request quota.

Use OPTIONS /api/v2/webhooks to confirm which events are supported per platform before subscribing.

Step 3 — Receive and process orders

When a new order is created on the merchant's store, EcartAPI posts the full order object to your webhook URL. Process the order in your system and use the order id for subsequent API calls.

If you need to poll instead of using webhooks (e.g. for initial backfill), use date filters to retrieve only recent orders efficiently:

GET /api/v2/orders?updatedAt[from]=2024-06-01T00:00:00Z&sort=asc&limit=100
Authorization: Bearer {access_token}

Each page counts as 1 billable request. See Billing for pagination cost details.

Step 4 — Post fulfillment with tracking

Before implementing this step, read the fulfillment reference for each platform you plan to support. Payload structure, required fields, and supported features (partial fulfillments, fulfillment order IDs, location requirements, carrier validation) vary significantly between platforms. Find the per-platform specs in Supported Requests by Platform — navigate to your platform and open the Fulfillments section.

All fulfillments go through the same endpoint, but the body you send must match what that platform accepts:

POST /api/v2/orders/{orderId}/fulfillments
Authorization: Bearer {access_token}

{ ... platform-specific payload ... }

Some things to verify in the platform reference before building:

• Required fields — some platforms require fields like fulfillmentOrderId, locationId, or companyId that others do not.
• Partial fulfillment support — not all platforms allow submitting fulfillments for a subset of items. Check whether the platform supports partial fulfillments before designing your split-shipment logic.
• Carrier validation — some platforms (Amazon v2) require a valid companyId from an allowed-carriers list. Use GET /services/allowed before creating a fulfillment to retrieve valid values.
• Tracking fields — the tracking.number, tracking.company, and tracking.url fields are standard, but their requirements and validation differ per platform.

Under EcartAPI's unified schema these differences are abstracted as much as possible, but platform constraints always apply — a field the platform requires must be present in the request.

Step 5 — Handle token expiration

Store access tokens can expire or be revoked if a merchant uninstalls your integration from their platform. Watch for 401 responses with ecartapiError: false — this means the token is no longer valid and the merchant must reconnect.

Notify the merchant and direct them to reconnect via your OAuth URL. The shop_id will remain the same after reconnection; only the access_token changes.

See Error codes and token expiration for the full reconnection flow.

Next

→ Webhooks — Delivery format, signature validation, retries, and IP allowlist.
→ Fulfillments — Full fulfillments endpoint reference.
→ Store identification — How to manage multiple stores per merchant.
→ Billing — What counts as a request and how to estimate monthly usage.