Quotes

Scope: parcels:write. Base path: /carrier-accounts/quotes.

Why this exists

A create-parcel dialog used to fan out one fees/resolve call per account, then guess whether the courier actually covers the commune. That is slow, expensive, and incomplete — a null fee and a missing territory look the same to the caller.

POST /carrier-accounts/quotes answers once: for each of your carrier accounts, is this destination deliverable, at what price, with which stopdesk pickup, and which account is the cheapest available.

Request

{
  "country": "DZ",
  "state": "16",
  "city": "Alger Centre",
  "deliveryType": "home",
  "accountIds": ["ca_…"],
  "includeUnavailable": true
}

• accountIds optional — omit to quote every active account for the tenant.
• Unknown / foreign ids are skipped (same contract as batch fees resolve).
• When Atlas cannot auto-accept the destination, every quote is unresolvable_geo and recommended is null — HTTP 200, so the UI can show alternatives[].

Response

{
  "data": {
    "destination": {
      "stateCode": "16",
      "cityName": "Alger Centre",
      "resolved": { "method": "exact", "confidence": 1, "autoAccept": true }
    },
    "quotes": [
      {
        "accountId": "ca_…",
        "courierId": "yalidine",
        "provider": "yalidine",
        "name": "Yalidine main",
        "available": true,
        "reason": null,
        "amount": 450,
        "matched": "city",
        "fees": { "home": 450, "stopdesk": 350, "return": 200, "exchange": null },
        "suggestedPickupId": null,
        "capabilities": { "create": true, "cancel": true, "labels": true, "webhooks": true, "edit": true }
      }
    ],
    "recommended": { "accountId": "ca_…", "amount": 450, "suggestedPickupId": null }
  }
}

Unavailable reason values: unresolvable_geo, no_coverage, delivery_type_unsupported, no_pickup, inactive, create_unsupported.

Ranking

Among available && amount !== null: minimum amount; ties prefer matched order city > state > default, then lexicographic accountId. 0 (free) is a real price and can win.