Shopify live checkout rates

During checkout, Shopify asks EcartAPI for shipping rates. EcartAPI sends one POST to your quote URL and waits for your rates. Your JSON array becomes the shipping methods the buyer sees. Home delivery (dropOff) and pickup (pickup) are both rows in that same list.

You have 5 seconds. After that the request fails and Shopify receives no rates from you.

Request you receive

POST your quote URL with Content-Type: application/json.

The body is one quote: origin, destination, items, package, currency, and locale. Item prices are in major units. Weight is kilograms.

{
  "origin": {
    "name": null,
    "company": "TechNest",
    "street": "Vasconcelos 1400",
    "city": "San Pedro",
    "state": "NL",
    "country": "MX",
    "postalCode": "66236"
  },
  "destination": {
    "name": "testing test",
    "street": "Casa de los azulejos #234, Casa",
    "city": "San Nicolas",
    "state": "NL",
    "country": "MX",
    "postalCode": "34567"
  },
  "items": [
    {
      "name": "Prueba del checkout",
      "quantity": "1",
      "weight": "0",
      "price": "4000",
      "productId": "10306702442665",
      "variantId": "50504275624105"
    }
  ],
  "package": {
    "weight": "1",
    "weightUnit": "KG",
    "lengthUnit": "CM",
    "dimensions": { "length": "17.1", "width": "17.1", "height": "17.1" }
  },
  "currency": "MXN",
  "locale": "es-MX"
}

Response you return

Answer HTTP 200 with a JSON array. Each element is one shipping method. An empty array is valid and means you have no rates. Do not wrap the array in { "rates": [] } — EcartAPI builds that object for Shopify after mapping.

No field is required. Unknown keys are ignored. If one element has a known field with the wrong type, that element is dropped and the rest are still shown.

type chooses the mapper. Comparison is case-insensitive.

Pickup elements that include pickupPoint are limited to 6 per serviceId. Home-delivery elements are not limited.

Empty string, null, and a missing key are treated the same: that value is skipped and the next priority is used.

Home delivery example

{
  "type": "dropOff",
  "serviceId": "1",
  "service": "FedEx Nacional Económico",
  "serviceDescription": "Door to door",
  "totalPrice": 119.87,
  "currency": "MXN",
  "phoneRequired": false,
  "deliveryDate": {
    "min": { "date": "2026-10-03", "time": "09:00" },
    "max": { "date": "2026-10-04", "time": "18:00" }
  }
}

Pickup example

{
  "type": "pickup",
  "serviceId": "9",
  "service": "Branch delivery",
  "totalPrice": 80,
  "currency": "MXN",
  "phoneRequired": true,
  "deliveryDate": {
    "max": { "date": "2026-10-04", "time": "18:00" }
  },
  "pickupPoint": {
    "pickupPointCode": "SUC-02",
    "reference": "Entrega en Sucursal",
    "address": {
      "address": "Av. Insurgentes",
      "number": "200",
      "locality": "Roma Norte",
      "city": "Ciudad de México",
      "postalCode": "06700"
    }
  }
}

date is YYYY-MM-DD. time is HH:mm. totalPrice is major units (80 or 119.87), not cents — "119.87" as a string is accepted. phoneRequired accepts true, false, "true", and "false".

Shared fields

These three fields use the same rule for home delivery and pickup.

Price → total_price

Currency → currency

Phone flag → phone_required

The phone string is ignored. Only the boolean is mapped.

Home delivery mapping

Shopify fields produced: service_name, service_code, description, total_price, currency, min_delivery_date, max_delivery_date, phone_required.

Title → service_name

service and serviceDescription can both be present. The title uses service. The second line can still use serviceDescription. If you send only serviceDescription, that text becomes both the title and the second line.

Second line → description

There is no fallback chain. The second line is only serviceDescription.

If you also send deliveryDate.min.date and deliveryDate.max.date, Shopify shows its own delivery promise from those dates — for example "1 a 2 días hábiles" — instead of relying on this text.

Code → service_code

This value is not shown to the buyer. Shopify sends it back when the buyer selects the method.

Always send serviceId. Without it, the selected method comes back as undefined.

Delivery window

If deliveryDate is missing, or a bound has no date, that Shopify field is omitted. min and max are independent — you can send only one.

Pickup mapping

Shopify fields produced: service_name, service_code, description, total_price, currency, max_delivery_date, phone_required.

min_delivery_date is never set for pickup, even if you send deliveryDate.min.

Title → service_name

Second line → description

The second line is the address only. serviceDescription is not used here. Opening hours in availability are not shown here.

Pieces are skipped when they are missing, null, or "". The remaining pieces stay in this order, joined with , :

If every piece is empty, description is null.

These address keys are accepted and ignored: street, country, province, state, latitude, longitude.

Code → service_code

This is not the same rule as home delivery. A pickup without pickupPointCode becomes null, not undefined. serviceId is not the pickup code — it only caps pickup rows at 6 per service.

Delivery window → max_delivery_date

Same Shopify field, different source

Fields that never reach checkout

Timeout and error handling

Answer in under 5 seconds. A slow 200 is a failure, not a late success.