Packages

A Package in Ecart API is one shipment unit: the group of items from an Order that will travel together in the same shipment to the customer. An order can have one or many packages—for example, if part of the order ships from one warehouse and the rest from another, that order has two packages.

In many ecommerces, you do not ship "the order" directly. You ship packages (or fulfillment orders). Each package has an identifier, line items and quantities to fulfill, status (e.g. open, in progress, fulfilled), and often an assigned location. When you mark one as shipped with tracking, the platform creates a Fulfillment linked to it. So: a Package is what needs to be shipped; a Fulfillment is the act of shipping it. You read packages first, then create fulfillments for them.

Concept	Meaning
Package	One shipment unit or fulfillment order—the set of items that will be (or were) shipped together, with an identifier and status.
Key field	fulfillmentOrderId — the identifier you send when creating a fulfillment to ship this package.

Not every ecommerce has packages

Platforms differ: in some ecommerces a full package resource exists (with status, location, etc.); in others, packages are derived from the order's fulfillment or shipment data, or the list may be empty. Ecart API normalizes to Package wherever the platform has an equivalent (fulfillment order, package, shipment, delivery order). Where the platform has no such concept, the package list may be empty or derived. Create, update, and delete are not available on all platforms—many ecommerces manage packages automatically when the order is placed; on those you only use GET to read them.

Note: Always get the order's packages first (or list packages) when you need to create a fulfillment. Use the package's fulfillmentOrderId in the fulfillment request when the platform requires it.

Where packages appear

1. Inside an Order response

When you get an order (GET /api/v2/orders/{id}), the response can include a packages array. Each entry is a summary: id, fulfillmentOrderId, number, locationId, type, status, dates, ecartapiUrl. Use this when you already have an order and need to know which packages exist and their state.

2. Standalone Package resource

Ecart API also exposes packages as a standalone resource with dedicated endpoints. The standalone version is richer: line items (which products are in the package), shipping info, dimensions, pricing. Use the order-level packages array when you only need ids and statuses; use the standalone endpoints when you need full package details.

Note: Not all platforms include packages in the order response. If order.packages is empty, try /api/v2/orders/{orderId}/packages or /api/v2/packages directly.

API endpoints

Method	Path	Description
GET	`/api/v2/packages`	List all packages (can be filtered by query params).
GET	`/api/v2/packages/{id}`	Get a single package by its id.
GET	`/api/v2/orders/{orderId}/packages`	List packages belonging to a specific order.
POST	`/api/v2/packages/{orderId}`	Create a package for an order. Not available on all platforms.
PUT	`/api/v2/packages/{id}`	Update a package. Not available on all platforms.
DELETE	`/api/v2/packages/{id}`	Delete a package. Not available on all platforms.

For full request/response shapes and per-platform support, see the API Reference (packages).

Main fields

Field	Type	Description
`id`	string \| null	The package's unique identifier on the platform.
`fulfillmentOrderId`	string \| null	The key field. Unified identifier you use when creating a Fulfillment to ship this package.
`number`	string \| null	Human-readable package number.
`locationId`	string \| null	Id of the location (warehouse, store) this package ships from.
`type`	string \| null	e.g. `default`, `combined`, `split`.
`status.ecartapi`	string \| null	Canonical status: `pending`, `shipped`, `delivered`, `canceled`, `refunded`, `other`.
`dates.createdAt`, `dates.updatedAt`	string \| null	Creation and last update (ISO 8601).
`ecartapiUrl`	string \| null	Direct API URL to retrieve this package.

Standalone package responses also include orderId, items, shipping, dimensions, and related fields.

fulfillmentOrderId

fulfillmentOrderId is the canonical identifier for "which package you are fulfilling." Different platforms use different names (fulfillment order id, package id, shipment id, delivery order id); Ecart API normalizes all of them into this single field.

When you read an order or list packages, each package has id and fulfillmentOrderId.
When you create a Fulfillment, you send fulfillmentOrderId in the payload so the backend knows which package you are marking as shipped.
On many platforms, fulfillmentOrderId is required to create a fulfillment; omitting it can result in an error (e.g. fulfillmentOrderIdMissing) or 400 Bad Request.

Flow: Get order packages (or GET packages) → take the fulfillmentOrderId of the package you want to ship → POST create fulfillment with that fulfillmentOrderId and tracking. Same payload across platforms.