Fulfillments

A Fulfillment in Ecart API is the shipment record: the act of marking one or more items (or a Package) as shipped. When you create a fulfillment, you tell the platform: this package has left the warehouse—here is the tracking number and carrier. The platform then updates the order's fulfillment status and, typically, sends the customer a shipping notification.

If a Package is "what needs to be shipped," a Fulfillment is "we shipped it—here's the proof." You get the order's packages (or list packages), read the fulfillmentOrderId from the package you are shipping, then create a fulfillment with that id and tracking info. This flow works the same way across supported platforms; Ecart API maps your canonical payload to what each ecommerce expects.

Important: A fulfillment is always created in the context of an order (/api/v2/orders/{orderId}/fulfillments). There is no standalone fulfillment resource. On many platforms you must provide fulfillmentOrderId when creating a fulfillment; get it from the Packages guide and the package response.

API endpoints

Method	Path	Description
GET	`/api/v2/orders/{orderId}/fulfillments`	List all fulfillments for an order.
GET	`/api/v2/orders/{orderId}/fulfillments/{id}`	Get a single fulfillment by id.
POST	`/api/v2/orders/{orderId}/fulfillments`	Create a fulfillment — main action for shipping.
PUT	`/api/v2/orders/{orderId}/fulfillments/{id}`	Update a fulfillment (e.g. change tracking).
POST	`/api/v2/orders/{orderId}/fulfillments/{id}/cancel`	Cancel a fulfillment. Platform-dependent.
POST	`/api/v2/orders/{orderId}/packages/fulfillments`	Bulk create multiple fulfillments for multiple packages in one request.

For query filters (limit, page, date ranges) and full request/response shapes, see the API Reference (fulfillments).

Creating a fulfillment

The request body is wrapped under the key fulfillment. Core fields:

Field	Required?	Description
fulfillmentOrderId	Yes on most platforms	Id of the Package you are fulfilling. Get it from the package response. Omitting it on platforms that require it causes an error.
tracking	Recommended	`number` (tracking number), `company` (carrier name), `companyId` (carrier id if used), `url` (tracking URL).
`items`	Optional	Array of `{ id, quantity }` for partial fulfillments. If omitted, the platform typically fulfills all items in the package.
`notifyCustomer`	Optional	Whether to send a shipping notification to the customer.

Other optional fields include locationId, shippingMethod, shippingDate, documents, fileUrl, and address overrides—see the API Reference for the full schema.

Example request payload

Most fulfillments only need fulfillmentOrderId and tracking:

{
  "fulfillment": {
    "fulfillmentOrderId": "123456789",
    "tracking": {
      "number": "1Z999AA10123456784",
      "company": "UPS",
      "url": "https://www.ups.com/track?tracknum=1Z999AA10123456784"
    }
  }
}

Get fulfillmentOrderId from the order's packages array or from GET /api/v2/orders/{orderId}/packages (or the Packages endpoints). Never hardcode it—always read it from the package you are shipping.

Updating a fulfillment

Use PUT /api/v2/orders/{orderId}/fulfillments/{id} to update tracking or status. The payload is also under the key fulfillment; you can send tracking, status (including status.ecartapi for canonical status), and other supported fields. Not all platforms support all update operations.

Typical flow

1. List or get Orders (with filters as needed).
2. For the order you want to ship, get Packages (or read order.packages).
3. Take the fulfillmentOrderId of the package you are shipping.
4. POST create fulfillment with that fulfillmentOrderId, tracking number, carrier, and optional tracking URL.
5. Where the platform supports it, use PUT to update the fulfillment (e.g. change tracking).

For partial fulfillments, bulk fulfillments, and per-platform behaviour, see the API Reference (fulfillments).