Cart

The Cart resource allows the manipulation of shopping carts generated in a storefront.

Only a Cart that is still modifiable can be accesed. Carts that have been converted or are still in the conversion process to an Order are no longer accessible via the Cart resource. Also, a Cart that has initiated a Redirect checkout process is no longer accessible.

You need the corresponding read_orders or write_orders scopes in order to call these endpoints.

Endpoints

GET /carts/{id}

Receive a single Cart by its id.

If you would like to retrieve an Order instead, refer to the Order resource.

Kit line items

When a Cart contains kits, each line item that is a kit component carries a catalog_kit_id, an order_kit_id (the kit instance in the cart) and a kit object describing the kit it belongs to. Only the kit-related fields are shown below:

{
  "id": 467422732,
  "product_id": 17310718,
  "variant_id": 33739098,
  "quantity": 1,
  "catalog_kit_id": 8901234,
  "order_kit_id": 778001,
  "kit": {
    "id": 778001,
    "catalog_kit_id": 8901234,
    "variant_id": 5678901,
    "name": "Summer Bundle",
    "image": "https://d2r9epyceweg5n.cloudfront.net/stores/001/234/products/summer-bundle.jpg",
    "price": 4999,
    "quantity": 2
  }
}

The kit object's id is the order_kit_id (the kit instance in this cart), not the catalog_kit_id. kit.catalog_kit_id is the kit type in the catalog, and kit.quantity is the number of units of that kit combination in the cart.

DELETE /carts/{id}/line-items/{id}

Remove a line item from a Cart by its line item id.

DELETE /carts/1234/line-items/5678

HTTP/1.1 200 OK

{}

DELETE /carts/{id}/coupons/{id}

Unset a Coupon from a Cart by its coupon id.

DELETE /carts/1234/coupons/5678

HTTP/1.1 200 OK

{}

Shipping Quotations

Unstable version only

The Shipping Quotations API is only available on the unstable version of the Cart API. The base URL is https://api.tiendanube.com/unstable/{store_id} (or https://api.nuvemshop.com.br/unstable/{store_id}).

The Shipping Quotations API lets an app quote the shipping options available for a Cart's current destination and line items, and then assign one of those options back to the Cart — without ever handling a raw postal code or a raw shipping method/option code.

It replaces the browser-only storefront checkout endpoints for app-to-API integrations: it doesn't accept an external postal code (it always quotes using the address already stored on the Cart, so it can never silently overwrite it), and it doesn't let the caller assign an arbitrary method/code pair. Instead, GET returns a signed, single-use assigned_token per option, and PUT only accepts that exact token back.

The two endpoints always use the same quotation engine as the Shipping Carrier rate callbacks, so the options you see here are the same options a buyer would see at checkout.

Scopes

Property	Explanation
read_shipping_quotation	Allows you to read the shipping options quoted for a Cart.
write_shipping_quotation	Allows you to assign a previously quoted shipping option to a Cart.

The assigned_token (JWT)

Every option returned by GET /carts/{id}/shipping/quotations carries its own assigned_token: a JSON Web Token (JWT), signed by Nuvemshop/Tiendanube with HS256, that represents that specific quoted option, for that specific Cart, quoted by that specific App. You don't need to (and can't) decode or inspect it — treat it as an opaque string and send it back exactly as received.

To assign a shipping option to the Cart, send its assigned_token to PUT /carts/{id}/shipping/quotations. The request is only accepted if all of the following hold:

#	Check	Failure response
1	The token's signature is valid and well-formed.	422 — Token signature is invalid or malformed
2	The token has not expired.	422 — Token has expired
3	The token was issued to the App making the request.	422 — Token was not issued for this application
4	The token was issued for the current Store.	422 — Token does not match the current store
5	The token was issued for the Cart in the URL (path {id}).	422 — Token does not match the requested cart

This means an assigned_token obtained by App A, for Store X, for Cart 123, can only be redeemed by App A, on Store X, on Cart 123. It cannot be replayed on a different app, store, or cart, even if it is somehow leaked.

Tokens expire 5 minutes after being issued. This is intentional: it guarantees that the price and delivery estimate a buyer sees is the price and estimate that gets assigned — no stale quotations from a previous session can be redeemed. If a token expires before the buyer confirms their choice, call GET /carts/{id}/shipping/quotations again to get a fresh set of options and tokens, then retry the PUT.

PUT /carts/{id}/shipping/quotations is idempotent: assigning the same valid, non-expired assigned_token more than once has the same effect as assigning it once.

Sequence diagram

Properties

ShippingQuotationOption

The shape of each entry returned by GET /carts/{id}/shipping/quotations, and — without assigned_token — the shape of the object returned by PUT /carts/{id}/shipping/quotations.

Field Name	Field Type	Description
name	String	The name of the shipping option, as seen by the buyer.
type	ShippingQuotationOptionType	The type of shipping option: ship or pickup.
price	Money	The option's price. currency is nullable.
estimated_delivery_time	EstimatedDeliveryTime	The estimated delivery time breakdown. Nullable — null when the carrier didn't provide delivery date estimates.
pickup_points	PickupPoint[]	GET only. Present when type is pickup. null for ship options. May contain more than one point when several pickup locations share the same method, code, price and delivery estimate — see the notes on the GET endpoint below.
pickup_point	PickupPoint	PUT only. The single pickup point that was assigned to the Cart. null for ship options.
assigned_token	String (JWT)	GET only. The signed, single-use token identifying this exact option. See The assigned_token (JWT).

ShippingQuotationOptionType

Type	Description
ship	The option ships to the buyer's address.
pickup	The option is picked up by the buyer at one or more physical locations.

EstimatedDeliveryTime

Field Name	Field Type	Description
min	EstimatedDeliveryTimeBound	The minimum estimated delivery bound. Nullable.
max	EstimatedDeliveryTimeBound	The maximum estimated delivery bound. Nullable.

EstimatedDeliveryTimeBound

Field Name	Field Type	Description
days	UnsignedInt	Total estimated delivery days, including non-business days.
business_days	UnsignedInt	Total estimated delivery business days.
date	DateTime	The estimated delivery date, in ISO 8601 format.
aggregate_days	EstimatedDeliveryTimeAggregateDays	Breakdown of how the delivery days are composed.

EstimatedDeliveryTimeAggregateDays

Mirrors the same breakdown used on FulfillmentOrderAggregateDaysBase.

Field Name	Field Type	Description
by_product_handling_days	UnsignedInt	Days added by product handling time.
by_transfer_handling_days	UnsignedInt	Days added by stock transfer handling between locations.
by_dc_preparation_days	UnsignedInt	Days added by distribution center preparation time.
by_dc_preparation_days_skipped	UnsignedInt	Distribution center preparation days skipped because the shipping option is flagged to ignore DC preparation time (express/same-day).
by_dc_non_working_days_skipped	UnsignedInt	Non-working days skipped at the distribution center.
by_carrier_pickup_days_and_times_of_cuts	UnsignedInt	Days added by carrier pickup schedules and cut-off times.
by_carriers_original_estimated_days	UnsignedInt	Carrier's original estimated delivery days.
by_carriers_additional_days	UnsignedInt	Additional days added on top of the carrier's original estimate.
by_carrier_non_working_days_skipped	UnsignedInt	Non-working days skipped by the carrier.

PickupPoint

Field Name	Field Type	Description
id	String	The pickup point identifier. This is the value to send as pickup_point_id on PUT /carts/{id}/shipping/quotations to select this specific location.
address	PickupPointAddress	The pickup point's address.
pickup_hours	PickupHour[]	The pickup point's open hours. Default: [].

PickupPointAddress

Field Name	Field Type	Description
street	String	The street name. Nullable.
number	String	The street number. Nullable.
floor	String	The floor / unit. Nullable.
locality	String	The locality / neighborhood. Nullable.
city	String	The city. Nullable.
province	String	The province / state. Nullable.
zipcode	String	The postal code. Nullable.
country	Object	{ "code": String } — the country's ISO code. Nullable.
latitude	String	The pickup point's latitude. Nullable.
longitude	String	The pickup point's longitude. Nullable.
phone	String	The pickup point's contact phone. Nullable.

PickupHour

Field Name	Field Type	Description
day	String	The day of the week (eg.: Monday).
start	String	The opening time, HH:MM format.
end	String	The closing time, HH:MM format.

GetCartShippingQuotationsResponse

The response body of GET /carts/{id}/shipping/quotations: an object wrapping the list of quoted options, not a bare array.

Field Name	Field Type	Description
options	ShippingQuotationOption[]	The list of quoted shipping options.

GET /carts/{id}/shipping/quotations

Quote the shipping options available for a Cart, based on the destination address and line items already stored on the Cart. There is no query parameter to override the destination — update the Cart's shipping address first if you need to quote a different one.

URL values

Field name	Field Type	Mandatory	Description
store_id	String	✅	Store identifier
id	String	✅	Cart identifier

Headers

Header	Field Type	Mandatory	Description
Authorization	String	✅	Bearer App token. Eg.: Bearer {app_token}

Notes

• Requires the read_shipping_quotation scope.
• The Cart must not have been converted into an Order and must still be modifiable (see the introduction above).
• The Cart must already have a destination address (shipping_country set) and at least one shippable line item, or the request fails with 400 Bad Request.
• Pickup options that share the same method, code, price and delivery estimate are grouped into a single option, with every matching location listed under pickup_points.
• Each assigned_token is valid for 5 minutes — see The assigned_token (JWT).

Responses

HTTP 200 - Ok

Type	Description
GetCartShippingQuotationsResponse	The list of quoted shipping options, wrapped in an options field.

GET /carts/789/shipping/quotations

{
  "options": [
    {
      "name": "PAC",
      "type": "ship",
      "price": {
        "value": 25.9,
        "currency": "BRL"
      },
      "estimated_delivery_time": {
        "min": {
          "days": 5,
          "business_days": 4,
          "date": "2026-07-12T00:00:00+00:00",
          "aggregate_days": {
            "by_product_handling_days": 1,
            "by_transfer_handling_days": 0,
            "by_dc_preparation_days": 0,
            "by_dc_preparation_days_skipped": 0,
            "by_dc_non_working_days_skipped": 0,
            "by_carrier_pickup_days_and_times_of_cuts": 0,
            "by_carriers_original_estimated_days": 4,
            "by_carriers_additional_days": 0,
            "by_carrier_non_working_days_skipped": 0
          }
        },
        "max": {
          "days": 8,
          "business_days": 6,
          "date": "2026-07-15T00:00:00+00:00",
          "aggregate_days": {
            "by_product_handling_days": 1,
            "by_transfer_handling_days": 0,
            "by_dc_preparation_days": 0,
            "by_dc_preparation_days_skipped": 0,
            "by_dc_non_working_days_skipped": 0,
            "by_carrier_pickup_days_and_times_of_cuts": 0,
            "by_carriers_original_estimated_days": 7,
            "by_carriers_additional_days": 0,
            "by_carrier_non_working_days_skipped": 0
          }
        }
      },
      "pickup_points": null,
      "assigned_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJ0bi1zaGlwcGluZy1xdW90YXRpb24iLCJhdWQiOiI0MiIsImlhdCI6MTc1MTg5NjAwMCwiZXhwIjoxNzUxODk2MzAwLCJkYXRhIjp7ImNvZGUiOiJwYWMiLCJtZXRob2QiOiJjb3JyZWlvcyIsInN0b3JlX2lkIjoxMjM0NTYsImNhcnRfaWQiOjc4OX19.9x0eR3q8b8v6r3nQvY0m0m2yqvqzXk4G5c8f0f0f0f0"
    },
    {
      "name": "Retirada na loja",
      "type": "pickup",
      "price": {
        "value": 0,
        "currency": "BRL"
      },
      "estimated_delivery_time": null,
      "pickup_points": [
        {
          "id": "01ARZ3NDEKTSV4RRFFQ69G5DAD",
          "address": {
            "street": "Avenida Paulista",
            "number": "1000",
            "floor": null,
            "locality": "Bela Vista",
            "city": "São Paulo",
            "province": "São Paulo",
            "zipcode": "01310-100",
            "country": {
              "code": "BR"
            },
            "latitude": "-23.5613",
            "longitude": "-46.6564",
            "phone": "1140000000"
          },
          "pickup_hours": [
            {
              "day": "Monday",
              "start": "09:00",
              "end": "18:00"
            }
          ]
        }
      ],
      "assigned_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJ0bi1zaGlwcGluZy1xdW90YXRpb24iLCJhdWQiOiI0MiIsImlhdCI6MTc1MTg5NjAwMCwiZXhwIjoxNzUxODk2MzAwLCJkYXRhIjp7ImNvZGUiOiJzdG9yZSIsIm1ldGhvZCI6InBpY2t1cCIsInN0b3JlX2lkIjoxMjM0NTYsImNhcnRfaWQiOjc4OX19.6a1bC2d3E4f5G6h7I8j9K0l1M2n3O4p5Q6r7S8t9U0"
    }
  ]
}

HTTP 400 - Bad Request

Returned when the Cart cannot be quoted: it has no shippable line items or no destination address set.

Type	Description
Error	The Bad Request Error Response.

{
  "code": 400,
  "message": "Bad Request",
  "description": "Cart has no destination address"
}

HTTP 401 - Unauthorized

Type	Description
Error	The Unauthorized Response.

HTTP 404 - Not Found

Returned when the Cart doesn't exist, doesn't belong to the Store, or has already been converted into an Order.

Type	Description
Error	The Not Found Error Response.

{
  "code": 404,
  "message": "Not Found",
  "description": "Cart not found"
}

HTTP 503 - Service Unavailable

Returned when the shipping carriers couldn't be reached to produce a quotation.

Type	Description
Error	The Service Unavailable Error Response.

PUT /carts/{id}/shipping/quotations

Assign a previously quoted shipping option to the Cart, by redeeming its assigned_token.

URL values

Field name	Field Type	Mandatory	Description
store_id	String	✅	Store identifier
id	String	✅	Cart identifier

Headers

Header	Field Type	Mandatory	Description
Authorization	String	✅	Bearer App token. Eg.: Bearer {app_token}
Content-type	String	✅	The request content-type "application/json"

Notes

• Requires the write_shipping_quotation scope.
• Parameters are sent in the body, JSON format.
• assigned_token must be a token previously returned by GET /carts/{id}/shipping/quotations, for this same Cart. See The assigned_token (JWT) for the full validation chain.
• pickup_point_id identifies which PickupPoint the buyer chose, by its id. It's used to disambiguate when the quoted option's pickup_points contained more than one location; it's ignored for ship options.
• The Cart must not have already been converted into an Order.
• This endpoint is idempotent: redeeming the same valid, non-expired assigned_token more than once has the same effect as redeeming it once.
• On success, the assigned shipping cost and delivery estimate are persisted on the Cart, and any coupon that covers shipping is reapplied.

Request Payload

Type	Description
ShippingQuotationAssignmentInput	The Shipping Quotation Assignment Input.

ShippingQuotationAssignmentInput

Field Name	Field Type	Mandatory	Description
assigned_token	String (JWT)	✅	The token of the quoted option to assign. See above.
pickup_point_id	String		The id of the chosen PickupPoint, when applicable.

{
  "assigned_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJ0bi1zaGlwcGluZy1xdW90YXRpb24iLCJhdWQiOiI0MiIsImlhdCI6MTc1MTg5NjAwMCwiZXhwIjoxNzUxODk2MzAwLCJkYXRhIjp7ImNvZGUiOiJwYWMiLCJtZXRob2QiOiJjb3JyZWlvcyIsInN0b3JlX2lkIjoxMjM0NTYsImNhcnRfaWQiOjc4OX19.9x0eR3q8b8v6r3nQvY0m0m2yqvqzXk4G5c8f0f0f0f0"
}

pickup_point_id is only relevant when the redeemed option is of type pickup and the original quotation grouped more than one location under it; it's omitted here because this example redeems a ship option.

Responses

HTTP 200 - Ok

Type	Description
ShippingQuotationOption	The shipping option assigned to the Cart.

PUT /carts/789/shipping/quotations

{
  "name": "PAC",
  "type": "ship",
  "price": {
    "value": 25.9,
    "currency": "BRL"
  },
  "estimated_delivery_time": {
    "min": {
      "days": 5,
      "business_days": 4,
      "date": "2026-07-12T00:00:00+00:00",
      "aggregate_days": {
        "by_product_handling_days": 1,
        "by_transfer_handling_days": 0,
        "by_dc_preparation_days": 0,
        "by_dc_preparation_days_skipped": 0,
        "by_dc_non_working_days_skipped": 0,
        "by_carrier_pickup_days_and_times_of_cuts": 0,
        "by_carriers_original_estimated_days": 4,
        "by_carriers_additional_days": 0,
        "by_carrier_non_working_days_skipped": 0
      }
    },
    "max": {
      "days": 8,
      "business_days": 6,
      "date": "2026-07-15T00:00:00+00:00",
      "aggregate_days": {
        "by_product_handling_days": 1,
        "by_transfer_handling_days": 0,
        "by_dc_preparation_days": 0,
        "by_dc_preparation_days_skipped": 0,
        "by_dc_non_working_days_skipped": 0,
        "by_carrier_pickup_days_and_times_of_cuts": 0,
        "by_carriers_original_estimated_days": 7,
        "by_carriers_additional_days": 0,
        "by_carrier_non_working_days_skipped": 0
      }
    }
  },
  "pickup_point": null
}

HTTP 401 - Unauthorized

Type	Description
Error	The Unauthorized Response.

HTTP 404 - Not Found

Returned when the Cart doesn't exist, doesn't belong to the Store, or has already been converted into an Order.

Type	Description
Error	The Not Found Error Response.

{
  "code": 404,
  "message": "Not Found",
  "description": "Cart not found"
}

HTTP 422 - Unprocessable Entity

Returned when assigned_token is missing, or fails any step of the validation chain, or when the quoted option is no longer available on the Cart.

Type	Description
Validation	The Unprocessable Entity Error Response.

{
  "code": 422,
  "message": "Unprocessable Entity",
  "description": "Validation error",
  "assigned_token": ["Token has expired"]
}

HTTP 500 - Internal Server Error

Returned when the option can no longer be assigned to the Cart for a reason outside of the checks above (eg. the underlying carrier information could not be resolved).

Type	Description
Error	The Internal Server Error Response.