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

Property	Explanation
id	The unique numeric identifier for the Shipping Carrier.
name	The name of the Shipping Carrier as seen by both merchants and buyers.
callback_url	The URL endpoint that we need to retrieve shipping rates. Must be HTTPS.
types	The supported shipping types, can be one or both ship or pickup.
active	Whether this Shipping Carrier is active.
created_at	Date when the Shipping Carrier was created in ISO 8601 format.
updated_at	Date 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

Property	Explanation
id	The unique numeric identifier for the Shipping Carrier Option.
code	A unique code associated with the Shipping Carrier Option.
name	The name of the Shipping Carrier Option as seen by both merchants and buyers.
additional_days	The additional days configurable value that will be added to the option's estimated delivery time.
additional_cost	The additional cost configurable value that will be added to the option's consumer price.
allow_free_shipping	The configurable free shipping eligible parameter that specifies that an option allows free shipping.
active	Whether this Shipping Carrier Option is active.
created_at	Date when the Shipping Carrier Option was created in ISO 8601 format.
updated_at	Date 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.

Property	Explanation
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_merchant	The 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_date	The earliest estimated delivery date in ISO 8601 format. Defaults to `null`.
max_delivery_date	The latest estimated delivery date in ISO 8601 format. Defaults to `null`.
id_required	Whether the customer must provide an identification number at checkout. Defaults to `false`.
phone_required	Whether the customer must provide a phone number at checkout. Defaults to `false`.
accepts_cod	Whether the customer is allowed to pay for this rate with a Cash on Delivery (COD) payment method (defaults to `true`).
reference	An 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,
        "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
            }
        }
    ]
}

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_2",
           "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

Parameter	Explanation
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`.
active	The 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

Parameter	Explanation	Required
code	A 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
name	The name of the Shipping Carrier Option as seen by both merchants and buyers.	Yes
additional_days	The additional days configurable value that will be added to the option's estimated delivery time.	No
additional_cost	The additional cost configurable value that will be added to the option's consumer price.	No
allow_free_shipping	The configurable free shipping eligible parameter that specifies that an option allows free shipping.	No
active	The avaiability status of the Shipping Carrier Option. Defaults to true	No

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

Parameter	Explanation
status	Fulfillment Event's status (see below for accepted values).
description	Message describing the status.
city	Fulfillment Event's city.
province	Fulfillment Event's province.
country	Fulfillment Event's country in ISO 3166-1 format.
happened_at	Date when the Fulfillment Event occured was created in ISO 8601 format.
estimated_delivery_at	Estimated date when the package will be delivered in ISO 8601 format.

Valid dates ISO-8601 are:

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

Some invalid dates examples:

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

Valid status are:

Status	Explanation
dispatched	Package has been posted by the merchant.
received_by_post_office	Package has been received by the Shipping Carrier.
in_transit	Package is in transit.
out_for_delivery	Package is out for delivery.
delivery_attempt_failed	Package could not be delivered.
delayed	Package delayed.
ready_for_pickup	Package is ready for pickup.
delivered	Package was delivered.
returned_to_sender	Package was returned to sender.
lost	Package lost.
failure	Package 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

{}

Shipping Carrier

Shipping Carrier Properties​

Shipping Carrier Options​

Shipping Carrier Options Properties​

Providing rates to our merchants​

Example requests for shipping rates​

POST /your_callback_url​

Server-side caching of requests​

Circuit Breaker for Unstable Shipping Carrier​

Endpoints​

POST /shipping_carriers​

POST /shipping_carriers​

GET /shipping_carriers​

GET /shipping_carriers​

GET /shipping_carriers/{id}​

GET /shipping_carrier/1​

PUT /shipping_carriers/{id}​

PUT /shipping_carriers/123​

DELETE /shipping_carriers/{id}​

DELETE /shipping_carriers/123​

POST /shipping_carriers/{carrier_id}/options​

POST /shipping_carriers/1234/options​

GET /shipping_carriers/{carrier_id}/options​

GET /shipping_carriers/1234/options​

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

GET /shipping_carrier/1234/options/123​

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

PUT /shipping_carriers/1234/options/123​

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

DELETE /shipping_carriers/1234/options/123​

Fulfillment Events​

GET /orders/{order_id}/fulfillments​

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

GET /orders/123/fulfillments/1​

POST /orders/{order_id}/fulfillments​

POST /orders/123/fulfillments​

Any invalid request wil return a 402 code for example​

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

DELETE /orders/123/fulfillments/1​

Shipping Carrier Properties

Shipping Carrier Options

Shipping Carrier Options Properties

Providing rates to our merchants

Example requests for shipping rates

POST /your_callback_url

Server-side caching of requests

Circuit Breaker for Unstable Shipping Carrier

Endpoints

POST /shipping_carriers

POST /shipping_carriers

GET /shipping_carriers

GET /shipping_carriers

GET /shipping_carriers/{id}

GET /shipping_carrier/1

PUT /shipping_carriers/{id}

PUT /shipping_carriers/123

DELETE /shipping_carriers/{id}

DELETE /shipping_carriers/123

POST /shipping_carriers/{carrier_id}/options

POST /shipping_carriers/1234/options

GET /shipping_carriers/{carrier_id}/options

GET /shipping_carriers/1234/options

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

GET /shipping_carrier/1234/options/123

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

PUT /shipping_carriers/1234/options/123

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

DELETE /shipping_carriers/1234/options/123

Fulfillment Events

GET /orders/{order_id}/fulfillments

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

GET /orders/123/fulfillments/1

POST /orders/{order_id}/fulfillments

POST /orders/123/fulfillments

Any invalid request wil return a 402 code for example

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

DELETE /orders/123/fulfillments/1