Carriers

What is a Carrier in ecartAPI?

A Carrier is a shipping provider that transports packages from the seller to the customer. In ecartAPI, carriers operate in two distinct modes:

Ecommerce carriers — the shipping providers built into the connected platform (e.g., Shopify's configured carriers, Mercado Libre's logistics options, Amazon's shipping services). These are managed on the platform side and listed through ecartAPI with the ?ecommerce=true filter.
Registered carriers — custom shipping providers registered directly in ecartAPI. These are stored in ecartAPI's database and can provide shipping rate quotes through the actions endpoint. This is used when a platform supports carrier-calculated shipping rates (e.g., Shopify Carrier Service, BigCommerce Shipping Provider).

Understanding this distinction is essential: the same /api/v2/services/carriers endpoint returns different data depending on whether you pass ?ecommerce=true or not.

How it works

Without ?ecommerce=true: Returns carriers registered in ecartAPI for this access token. These are custom integrations you've set up.
With ?ecommerce=true: Calls the connected platform's API and returns its configured shipping providers, normalized to a canonical shape.
Allowed carriers (/services/allowed): Returns the platform's supported carrier list (not the configured ones, but what's available).

Important: Not all platforms support carrier management. Carrier registration, rate quotes, and options are available only on platforms that implement carrier service APIs.

API endpoints

Core carrier CRUD

Method	Path	Description
GET	`/api/v2/services/carriers`	List carriers. Use `?ecommerce=true` for platform carriers.
GET	`/api/v2/services/carriers/{id}`	Get a single carrier by id.
POST	`/api/v2/services/carriers`	Register a new carrier in ecartAPI.
PUT	`/api/v2/services/carriers/{id}`	Update a registered carrier.
DELETE	`/api/v2/services/carriers/{id}`	Delete a registered carrier.
GET	`/api/v2/services/allowed`	List the platform's allowed/supported carriers.

Carrier options

Method	Path	Description
GET	`/api/v2/services/carriers/{carrierId}/options`	List options for a carrier.
GET	`/api/v2/services/carriers/{carrierId}/options/{id}`	Get a single carrier option.
POST	`/api/v2/services/carriers/{carrierId}/options`	Create a carrier option.
PUT	`/api/v2/services/carriers/{carrierId}/options/{id}`	Update a carrier option.
DELETE	`/api/v2/services/carriers/{carrierId}/options/{id}`	Delete a carrier option.

Rate quotes and services

Method	Path	Description
POST	`/api/v2/services/carriers/actions/{reference}`	Request shipping rate quotes from a registered carrier. No auth required.
GET	`/api/v2/services/carriers/actions/{reference}`	Alternative GET for rate quotes. No auth required.
GET	`/api/v2/services/carriers/available/{reference?}`	List available services from a carrier. No auth required.

Note: The {reference} is a unique identifier assigned to each registered carrier. Rate quote and available services endpoints do not require authentication — they are called by the ecommerce platform's checkout process.

Query filters

Parameter	Description
`ecommerce`	Set to `true` to list the platform's carriers instead of registered carriers.
`id`	Filter by carrier id.
`name`	Filter by carrier name.
`active`	Filter by active status.
`countryCode2`	Filter by country (ISO 3166-1 alpha-2).
`deliveryType`	Filter by delivery type.
`orderId`	Filter carriers available for a specific order.
`lineItemIds`	Filter by line item ids.
`fulfillmentId`	Filter by fulfillment id.
`marketplaceId`	Filter by marketplace.

Response shape

Ecommerce carrier (with `?ecommerce=true`)

The shape varies by platform, but common fields include:

Field	Type	Description
`id`	string	Carrier identifier on the platform.
`name`	string	Carrier name (e.g., "FedEx", "DHL", "Correos de México").
`active`	boolean	Whether the carrier is currently active.

Some platforms include additional fields like url, type, idReference, or shipping limits.

Registered carrier (without `?ecommerce=true`)

Field	Type	Description
`id`	string	ecartAPI-generated identifier (MongoDB ObjectId).
`carrierId`	string	Platform-side carrier id (if registered with the platform).
`name`	string	Carrier name.
`url`	string	Callback URL for rate quote requests.
`active`	boolean	Whether the carrier is active.
`settings`	object	Platform-specific carrier settings.
`token`	string	Authentication token for the carrier.
`ratesUrl`	string	URL for fetching shipping rates.
`servicesUrl`	string	URL for listing available services.
`createdAt`	string	ISO 8601 creation timestamp.

Rate quote response

When a rate quote is requested via the actions endpoint, the response contains shipping rate options normalized from the carrier's external response. The format follows the connected platform's expected structure (e.g., Shopify's carrier service response format).

Important notes

Two-world model. Always be aware of whether you're working with ecommerce carriers or registered carriers. The ?ecommerce=true flag switches the data source entirely.
Rate quotes are unauthenticated. The /actions/{reference} and /available/{reference} endpoints do not require an ecartAPI access token — they are designed to be called by the ecommerce platform during checkout.
Creating carriers requires the platform to support carrier service registration (e.g., Shopify Carrier Service API, BigCommerce Shipping Provider API).
Allowed carriers (/services/allowed) lists what carriers the platform supports natively, not what you've configured. Use this to discover available options.
Response fields are platform-dependent. Not all fields listed in the response shape are available for every ecommerce platform. Some properties may be absent or returned as null depending on what the connected platform's API provides.
If a platform does not support carrier operations, ecartAPI returns 400 with "The resource is not available for this ecommerce".