Skip to main content

Shipping Carrier

A shipping carrier (or shipping company) service provides real-time shipping rates for merchants.

Using these endpoints, you can add a shipping carrier to a store and provide shipping rates at checkout.

Shipping Carrier Properties

PropertyExplanation
idThe unique numeric identifier for the Shipping Carrier.
nameThe name of the Shipping Carrier as seen by both merchants and buyers.
callback_urlThe URL endpoint that we need to retrieve shipping rates. Must be HTTPS.
typesThe supported shipping types, can be one or both ship or pickup.
activeWhether this Shipping Carrier is active.
created_atDate when the Shipping Carrier was created in ISO 8601 format.
updated_atDate when the Shipping Carrier was last updated in ISO 8601 format.

Shipping Carrier Options

Almost every shipping carrier has multiple options to offer to the consumers, like standard and express shipping options. These options may provide some configurable values to the merchants through the store's admin, like additional costs and days, and also free shipping availability options.

Shipping Carrier Options Properties

PropertyExplanation
idThe unique numeric identifier for the Shipping Carrier Option.
codeA unique code associated with the Shipping Carrier Option.
nameThe name of the Shipping Carrier Option as seen by both merchants and buyers.
additional_daysThe additional days configurable value that will be added to the option's estimated delivery time.
additional_costThe additional cost configurable value that will be added to the option's consumer price.
allow_free_shippingThe configurable free shipping eligible parameter that specifies that an option allows free shipping.
activeWhether this Shipping Carrier Option is active.
created_atDate when the Shipping Carrier Option was created in ISO 8601 format.
updated_atDate when the Shipping Carrier Option was last updated in ISO 8601 format.

Providing rates to our merchants

When adding a Shipping Carrier to a store, you need to provide POST endpoints in the callback properties where we can retrieve the shipping rates.

We provide to different kind of shipments. Shipments that will be shipped to a buyer's address (ship) or shipments that will be picked up by the buyer (pickup).

The response object rates must be a JSON array of objects with the following fields. We need all required fields for the integration to work properly.

Important: you have to post all your available rates, our API will filter by carrier options active, and apply the settings made by users over the rates (additional days and additional cost).

Note: Additional information about price and price_merchant related to free shipping can be found in this guide.

Note: Check out this video where we show how price and price_merchant rules work.

Note: It's possible to send the same code for more than one pickup option in the rates. For ship options, the code cannot be repeated. If two options with the same code are sent, we will only process the first one.

PropertyExplanation
name(required) The name of the rate which buyers will see at the storefront or checkout.
code(required) A unique code associated with the carrier option code. It's used to apply the settings over the rate. Must be a string.
price(required) The rate's price that will be payed by the buyer. Check out this video for more info.
currency(required) The rate's currency. Currency codes must be specified according to ISO 4217
type(required) The rate's type: ship if it will be deliverd to a buyer's address or pickup if it will be picked up by the buyer.
address(required) (pickup only) Where the pickup point is located.
hours(required) (pickup only) The location open hours providing: day (0: sunday, 6: saturday), start and end on HHMM format.
price_merchantThe rate's price that will be payed by the merchant. It may be different than price due to items with free shipping. Defaults to price. Check out this video for more info.
min_delivery_dateThe earliest estimated delivery date in ISO 8601 format. Defaults to null.
max_delivery_dateThe latest estimated delivery date in ISO 8601 format. Defaults to null.
id_requiredWhether the customer must provide an identification number at checkout. Defaults to false.
phone_requiredWhether the customer must provide a phone number at checkout. Defaults to false.
accepts_codWhether the customer is allowed to pay for this rate with a Cash on Delivery (COD) payment method (defaults to true).
referenceAn internal reference yo wish to save for the rate. We will save it and return it on the Order as shipping_option_reference.
availability(pickup only) Whether there is availability for all items at the location. Defaults to true.

Example requests for shipping rates

POST /your_callback_url

{
"store_id": 123456,
"currency": "ARS",
"language": "es",
"origin": {
"name": null,
"location_id": "01GQ85S6PRCSS6ZHQBX9B1HBPW",
"address": "Avenida Cabildo",
"number": "4781",
"floor": null,
"locality": "Nuñez",
"city": "Capital Federal",
"province": "Capital Federal",
"country": "AR",
"postal_code": "1602",
"phone": null
},
"destination": {
"name": null,
"address": "Juan B. Justo",
"number": "3000",
"floor": null,
"locality": "Nuñez",
"city": "Capital Federal",
"province": "Capital Federal",
"country": "AR",
"postal_code": "1602",
"phone": null
},
"items": [
{
"id": 1,
"product_id": 1,
"name": "My product",
"sku": null,
"quantity": 1,
"free_shipping": true,
"grams": 1000,
"price": 20.00,
"dimensions": {
"width": 12.0,
"height": 10.0,
"depth": 10.0
}
}
],
"carrier": {
"id": "1234567",
"name": "Carrier Nube",
"options": [
{
"id": "14349849",
"name": "Nube - Entrega estándar",
"code": "standard",
"allow_free_shipping": false,
"additional_cost": {
"amount": 1500,
"currency": "ARS"
},
"additional_days": 3
},
{
"id": "14349850",
"name": "Nube - Entrega express",
"code": "express",
"allow_free_shipping": false,
"additional_cost": {
"amount": 1500,
"currency": "ARS"
},
"additional_days": 3
}
]
}
}

HTTP/1.1 200 OK

{
"rates": [
{
"name": "Standard Shipping",
"code": "standard",
"price": 14.15,
"price_merchant": 14.15,
"currency": "ARS",
"type": "ship",
"min_delivery_date": "2016-07-14T14:48:45-0300",
"max_delivery_date": "2016-07-17T14:48:45-0300",
"phone_required": true,
"reference": "ref123"
},
{
"name": "Express Shipping",
"code": "express",
"price": 28.15,
"price_merchant": 28.15,
"currency": "ARS",
"type": "ship",
"min_delivery_date": "2016-07-12T14:48:45-0300",
"max_delivery_date": "2016-07-13T14:48:45-0300",
"id_required": true,
"reference": "ref123"
},
{
"name": "Shipping branch #1",
"code": "pickup_1",
"price": 14.15,
"price_merchant": 14.15,
"currency": "ARS",
"type": "pickup",
"min_delivery_date": "2016-07-14T14:48:45-0300",
"max_delivery_date": "2016-07-17T14:48:45-0300",
"phone_required": true,
"id_required": true,
"accepts_cod": true,
"address": {
"address": "My address",
"number": "345",
"floor": null,
"locality": "Lanús",
"city": "Lanús",
"province": "Buenos Aires",
"country": "AR",
"phone": "+54 11 5678-1234",
"zipcode": "1824",
"latitude": "123456",
"longitude": "-123456"
},
"hours": [
{
"day": 1,
"start": "0900",
"end": "1800"
},
{
"day": 2,
"start": "0900",
"end": "1800"
},
{
"day": 3,
"start": "0900",
"end": "1800"
},
{
"day": 4,
"start": "0900",
"end": "1800"
},
{
"day": 5,
"start": "0900",
"end": "1800"
}
],
"availability": false,
"reference": "ref123"
},
{
"name": "Shipping branch #2",
"code": "pickup_1",
"price": 14.15,
"currency": "ARS",
"type": "pickup",
"min_delivery_date": "2016-07-12T14:48:45-0300",
"max_delivery_date": "2016-07-13T14:48:45-0300",
"accepts_cod": true,
"phone_required": true,
"id_required": true,
"address": {
"address": "Another address",
"number": "123",
"floor": null,
"locality": "Florida",
"city": "Vicente Lopez",
"province": "Buenos Aires",
"country": "AR",
"phone": "+54 11 1234-5678",
"zipcode": "1602",
"latitude": null,
"longitude": null
},
"hours": [
{
"day": 1,
"start": "0900",
"end": "1800"
},
{
"day": 2,
"start": "0900",
"end": "1800"
},
{
"day": 3,
"start": "0900",
"end": "1800"
},
{
"day": 4,
"start": "0900",
"end": "1800"
},
{
"day": 5,
"start": "0900",
"end": "1800"
}
],
"reference": "ref123"
}
]
}

Server-side caching of requests

We will provide server-side caching to reduce the number of requests done to your callback URLs. Any shipping rate request that identically matches the following fields will be retrieved from our cache of the initial response:

  • variant ids
  • variant quantities
  • default shipping box weight and dimensions
  • shipping carrier id
  • origin address
  • destination address
  • item weights & dimensions

If any of these fields differ, or if the cache has expired since the original request, then new shipping rates are requested.

About caching expire time (TTL)

  • Success responses, with status code 200 from callback URLs, expire after 15 minutes.
  • Error responses, with status code 422 from callback URLs, expire after 1 minute.
  • Otherwise, the responses won't be cached.

Circuit Breaker for Unstable Shipping Carrier

If your callback URL experiences frequent errors or high response delays, we implement a circuit breaker to reduce the number of requests sent to your callback, helping prevent overloading of API. This circuit breaker activates under specific conditions:

  • At least 500 requests have been made to your callback URL in the past 30 minutes.
  • At least 50% of these requests have resulted in failures (either due to 5xx status codes or response timeouts of 10 seconds). Each request is monitored for success or failure, and metrics are maintained within a rolling 30 minutes window. If requests are interrupted due to unhealthy metrics, we allow the sent of new requests after 5 minutes to check the API's status.

After this period and with at least 10 new requests, we re-evaluate whether to fully resume or continue limiting requests. If the circuit remains open, we perform health checks every 5 minutes until the callback URL’s performance stabilizes.

Endpoints

POST /shipping_carriers

Create a new Shipping Carrier

ParameterExplanation
name(required) The name of the Shipping Carrier as seen by both merchants and buyers.
callback_url(required) The URL endpoint that we need to retrieve shipping rates when the buyer wants the items ship to an address.
types(required) Comma separated values indicating supported methods: can be any of ship or pickup.
activeThe shipping carrier availability status, used to disable or enable it for the store. Defaults to true.

POST /shipping_carriers

{
"name": "My Shipping Company",
"callback_url": "https://example.com/rates",
"types": "ship,pickup"
}

HTTP/1.1 201 Created

{
"id": 123,
"name": "My Shipping Company",
"active": true,
"callback_url": "https://example.com/rates",
"types": "ship,pickup",
"created_at": "2013-06-11T11:12:10-03:00",
"updated_at": "2013-06-11T11:12:10-03:00"
}

GET /shipping_carriers

Receive a list of all Shipping Carriers.

GET /shipping_carriers

HTTP/1.1 200 OK

[
{
"id": 1,
"name": "Example Company",
"active": true,
"callback_url": "https://example.com/rates",
"created_at": "2013-04-12T10:15:10-03:00",
"updated_at": "2013-04-12T10:15:10-03:00"
},
{
"id": 2,
"name": "Another example Company",
"active": true,
"callback_url": "https://example.com/rates",
"created_at": "2013-04-12T10:20:13-03:00",
"updated_at": "2013-04-12T10:20:13-03:00"
}
]

GET /shipping_carriers/{id}

Receive a single Shipping Carrier

GET /shipping_carrier/1

HTTP/1.1 200 OK

{
"id": 1,
"name": "Example Company",
"active": true,
"callback_url": "https://example.com/rates",
"created_at": "2013-04-12T10:15:10-03:00",
"updated_at": "2013-04-12T10:15:10-03:00"
}

PUT /shipping_carriers/{id}

Modify an existing Shipping Carrier

PUT /shipping_carriers/123

{
"name": "My Super Shipping Company",
"types": "ship",
"active": false
}

HTTP/1.1 200 OK

{
"id": 123,
"name": "My Super Shipping Company",
"active": false,
"callback_url": "https://example.com/rates",
"types": "ship",
"created_at": "2013-06-11T11:12:10-03:00",
"updated_at": "2013-06-13T23:09:43-03:00"

}

DELETE /shipping_carriers/{id}

Remove a Shipping Carrier

DELETE /shipping_carriers/123

HTTP/1.1 200 OK

{}

POST /shipping_carriers/{carrier_id}/options

Create a new Shipping Carrier Option

ParameterExplanationRequired
codeA unique code associated with the Shipping Carrier Option. The carrier option code is used for matching against the shipping rates. This allows merchant to add additional day and cost settings to the retrieved carrier options. Must be a string.Yes
nameThe name of the Shipping Carrier Option as seen by both merchants and buyers.Yes
additional_daysThe additional days configurable value that will be added to the option's estimated delivery time.No
additional_costThe additional cost configurable value that will be added to the option's consumer price.No
allow_free_shippingThe configurable free shipping eligible parameter that specifies that an option allows free shipping.No
activeThe avaiability status of the Shipping Carrier Option. Defaults to trueNo

POST /shipping_carriers/1234/options

{
"code": "pac",
"name": "Correios - PAC"
}

HTTP/1.1 201 Created

{
"id": 123,
"code": "pac",
"name": "Correios - PAC",
"additional_days": 2,
"additional_cost": 10.0,
"allow_free_shipping": true,
"active": true,
"created_at": "2013-04-12T10:15:10-03:00",
"updated_at": "2013-04-12T10:15:10-03:00"
}

GET /shipping_carriers/{carrier_id}/options

Receive a list of all Shipping Carriers Options.

GET /shipping_carriers/1234/options

HTTP/1.1 200 OK

[
{
"id": 123,
"code": "pac",
"name": "Correios - PAC",
"additional_days": 0,
"additional_cost": 0.0,
"allow_free_shipping": false,
"active": true,
"created_at": "2013-04-12T10:15:10-03:00",
"updated_at": "2013-04-12T10:15:10-03:00"
},
{
"id": 456,
"code": "sedex",
"name": "Correios - SEDEX",
"additional_days": 0,
"additional_cost": 0.0,
"allow_free_shipping": false,
"active": true
}
]

GET /shipping_carriers/{carrier_id}/options/{option_id}

Receive a single Shipping Carrier Option.

GET /shipping_carrier/1234/options/123

HTTP/1.1 200 OK

{
"id": 123,
"code": "pac",
"name": "Correios - PAC",
"additional_days": 0,
"additional_cost": 0.0,
"allow_free_shipping": false,
"active": true,
"created_at": "2013-04-12T10:15:10-03:00",
"updated_at": "2013-04-12T10:15:10-03:00"
}

PUT /shipping_carriers/{carrier_id}/options/{option_id}

Modify an existing Shipping Carrier Option.

PUT /shipping_carriers/1234/options/123

{
"additional_days": 2,
"additional_cost": 10.0,
"allow_free_shipping": true
}

HTTP/1.1 200 OK

{
"id": 123,
"code": "pac",
"name": "Correios - PAC",
"additional_days": 2,
"additional_cost": 10.0,
"allow_free_shipping": true,
"active": true,
"created_at": "2013-04-12T10:15:10-03:00",
"updated_at": "2013-04-12T10:15:10-03:00"
}

DELETE /shipping_carriers/{carrier_id}/options/{option_id}

Remove a Shipping Carrier Option

DELETE /shipping_carriers/1234/options/123

HTTP/1.1 200 OK

{}

Fulfillment Events

A Fulfillment Event represents a tracking event belonging to the order's fulfillment. Fulfillment events are displayed on the order tracking page to give buyers visibility on their shipment status.

📢 Important 📢

A new Fulfillment Events API with support for multi inventory is currently being rolled out to every merchant.

For any new development, we strongly recommend you to use the new version. Please contact us to activate this new version in your stores if needed.

GET /orders/{order_id}/fulfillments

Receive a list of all Fulfillment Events for an order.

HTTP/1.1 200 OK

[
{
"id": 1,
"order_id": 123,
"status": "dispatched",
"description": "Objeto postado",
"city": "São Paulo",
"province": "São Paulo",
"country": "BR",
"created_at": "2013-04-20T08:23:42-03:00",
"updated_at": "2013-04-20T08:23:42-03:00",
"happened_at": "2013-04-20T05:17:02-03:00",
"estimated_delivery_at": "2013-04-22T12:00:00-03:00"
},
{
"id": 2,
"order_id": 123,
"status": "in_transit",
"description": "Objeto encaminhado",
"city": "São Paulo",
"province": "São Paulo",
"country": "BR",
"created_at": "2013-04-21T17:15:00-03:00",
"updated_at": "2013-04-21T17:15:00-03:00",
"happened_at": "2013-04-21T17:14:25-03:00",
"estimated_delivery_at": "2013-04-22T12:00:00-03:00"
}
]

GET /orders/{order_id}/fulfillments/{id}

Receive a single Fulfillment Event

GET /orders/123/fulfillments/1

HTTP/1.1 200 OK

{
"id": 1,
"order_id": 123,
"status": "dispatched",
"description": "Objeto postado",
"city": "São Paulo",
"province": "São Paulo",
"country": "BR",
"created_at": "2013-04-20T08:23:42-03:00",
"updated_at": "2013-04-20T08:23:42-03:00",
"happened_at": "2013-04-20T05:17:02-03:00",
"estimated_delivery_at": "2013-04-22T12:00:00-03:00"
}

POST /orders/{order_id}/fulfillments

Create a new Fulfillment Event

ParameterExplanation
statusFulfillment Event's status (see below for accepted values).
descriptionMessage describing the status.
cityFulfillment Event's city.
provinceFulfillment Event's province.
countryFulfillment Event's country in ISO 3166-1 format.
happened_atDate when the Fulfillment Event occured was created in ISO 8601 format.
estimated_delivery_atEstimated date when the package will be delivered in ISO 8601 format.

Valid dates ISO-8601 are:

DateExplanation
2021-03-03 12:32:54-0300YYYY-MM-DD hh:mm:ss±hhmm
2021-10-12 12:32+03:00YYYY-MM-DD hh:mm±hh:mm
2021-04-03 12:32:54ZYYYY-MM-DD hh:mm:ssZ
2021-11-23 12:32ZYYYY-MM-DD hh:mmZ
2021-04-03 12:32:54YYYY-MM-DD hh:mm:ss
2021-05-17T12:32:54+0300YYYY-MM-DDThh:mm:ss±hhmm
2021-03-03T12:32-03:00YYYY-MM-DDThh:mm±hh:mm
2021-08-11T12:32:54ZYYYY-MM-DDThh:mm:ssZ
2021-03-03T12:32ZYYYY-MM-DDThh:mmZ
2021-03-03T12:32:02YYYY-MM-DDThh:mm:ss
2021-03-03YYYY-MM-DD

Some invalid dates examples:

DateExplanation
20210303The formmat YYYYMMDD is not accepted
2021-02-29Feb 29 in a non-leap year
2021-02-05 1300time cannot be represented as hhmm it should be hh:mm
2021-03-03T12:32Z-03:00Two timezone is not accepted
2021-03-03T12:32:1-03:00time must have pattern hh:mm:ss not hh:mm:s
20-10-2020Pattern DD-MM-YYYY is invalid it should be YYYY-MM-DD

Valid status are:

StatusExplanation
dispatchedPackage has been posted by the merchant.
received_by_post_officePackage has been received by the Shipping Carrier.
in_transitPackage is in transit.
out_for_deliveryPackage is out for delivery.
delivery_attempt_failedPackage could not be delivered.
delayedPackage delayed.
ready_for_pickupPackage is ready for pickup.
deliveredPackage was delivered.
returned_to_senderPackage was returned to sender.
lostPackage lost.
failurePackage delivery failed.

POST /orders/123/fulfillments

{
"status": "delivered",
"description": "Objeto entregue ao destinatário",
"city": "São Paulo",
"province": "São Paulo",
"country": "BR",
"happened_at": "2013-04-22T11:39:12-03:00",
"estimated_delivery_at": "2013-04-22T11:39:12-03:00"
}

HTTP/1.1 201 Created

{
"id": 3,
"order_id": 123,
"status": "delivered",
"description": "Objeto entregue ao destinatário",
"city": "São Paulo",
"province": "São Paulo",
"country": "BR",
"created_at": "2013-04-20T08:23:42-03:00",
"updated_at": "2013-04-20T08:23:42-03:00",
"happened_at": "2013-04-20T05:17:02-03:00",
"estimated_delivery_at": "2013-04-22T12:00:00-03:00"
}

Any invalid request wil return a 402 code for example

Invalid request

{
"status": "in_transit",
"happened_at": "28-01-2021",
"estimated_delivery_at": "2021-12-32",
"description": "Em rota",
"city": "[SP] São Paulo",
"province": "SP",
"country": "Brasil"
}

HTTP/1.1 422 Unprocessable Entity

{
"code": 422,
"message": "Unprocessable Entity",
"description": "Validation error",
"happened_at": [
"The happened at must be a valid ISO 8601 datetime."
],
"estimated_delivery_at": [
"The estimated delivery at must be a valid ISO 8601 datetime."
]
}

DELETE /orders/${order_id}/fulfillments/{id}

Remove a Fulfillment Event

DELETE /orders/123/fulfillments/1

HTTP/1.1 200 OK

{}