Agentic commerceDelivery options for AI agents and checkout chats

We are opening up for experimenting with AI in the checkout. An AI agent or a checkout chat can ask for Posten and Bring delivery options, and get a recommendation it can explain to the customer.

It runs on Model Context Protocol (MCP), an open standard for letting language models call real systems instead of guessing. Our server publishes one tool, get_shipping_rates, on the same shipping guide and Mybring checkout configuration as our platform plugins. So an agent and your checkout quote the same prices and lead times.

The server is new, and we would like to hear what you build with it. Write to checkoutno@posten.no.

At a glance

Endpoint: POST https://api.bring.com/checkout/mcp/AGENT_ID
Calls: One HTTP POST per question. Nothing to set up beforehand. MCP revision 2025-06-18.
Tool: get_shipping_rates – read-only, idempotent
Identification: Your Agent ID in the path. No separate API key.

Designed around customer intent

Shoppers ask “what is cheapest?” or “can it arrive before the weekend?”, not for a service code. So the tool takes an optional selection object: an intent, plus constraints that override it.

The full rate list always comes back, unfiltered and in the same order.
recommendation names one of those rates, with reasonCodes, an explanation and a rankingPolicyVersion. Ranking runs in our code, not in a model.
Options that break a constraint appear in rejectedOptions with reason codes.
A recommendation always points at a rate in the list, and at a pickup point inside that rate.
When the data cannot answer the intent, recommendation is null and warnings says why.
Errors are typed codes with messages you can show a customer.

What you can build

A chat in the checkout: the shopper asks in their own words, your backend runs a tool-use loop against get_shipping_rates, real prices come back.
A shopping assistant that needs freight cost before an address is picked.
An internal agent answering “what would this cost to send?”
An external assistant your customers already use.

In a chat like this, the model picks which two or three options to surface and why, while the server fills in prices, dates and pickup point names from the tool response, so what the customer sees cannot drift from the shipping guide.

Connect a client

Your Agent ID comes from the agents page in Mybring checkout, and decides which services, destinations, prices and lead times to quote. In a client that reads an mcpServers configuration:

{
  "mcpServers": {
    "posten-bring-shipping": {
      "type": "http",
      "url": "https://api.bring.com/checkout/mcp/AGENT_ID"
    }
  }
}

Or using curl, to check that the tool is there. Both headers are required, and the reply arrives either as plain JSON or as one event-stream event wrapping the same JSON.

curl -X POST https://api.bring.com/checkout/mcp/AGENT_ID \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Call the mcp server from your backend, not from the browser.

Reference

Request model

The input schema is strict: unknown fields are rejected with INVALID_ARGUMENT rather than ignored, so a model that invents a field finds out immediately.

Arguments

origin

Required

Sender address.; object
Countries: NO SE DK SJ

destination

Required

Recipient address.; object
Countries: NO SE DK SJ FI

cart

Required

The cart the shipment is for.

object

selection

Ask for a recommendation on top of the rates. See selection. Omit for the rate list only.

object

locale

Language of service descriptions and pickup point opening hours. Codes and recommendation explanations stay in English.; string
Enum: en nb-NO sv-SE da-DK
Default: en

address

countryCode

Required

ISO 3166-1 alpha-2.

string

postalCode

Required

Postal code in that country.

string

address1, address2

Street lines. On destination, used to find nearby pickup points.

string

cart

currency

Required

ISO 4217. Prices come back in this currency. The tool does not convert.

string

totalCost

Required

Cart value. Drives discounted and tiered rates, so an inaccurate value changes the prices you get back.

number, minimum 0

items

Required

Cart lines. See cart.items.

array, 1–100 entries

cart.items[]

quantity

Required

Units on this line.

integer, 1–10 000

weightInGrams

Required

Weight per unit. Decides which services and weight limits apply.

integer, 1–1 000 000

inStock

Affects lead time.

boolean, default true

tooBigForLocker

Set on any line that will not fit a locker. Excludes locker services.

boolean, default false

requiresGroupageOrPallet

Set on any line that has to go as groupage or on a pallet.

boolean, default false

Aggregated weight – quantity × weightInGrams across all lines – must not exceed 50 000 000 grams.

selection

intent

Required

What the customer is optimising for. See intents.; string
Enum: CHEAPEST FASTEST LOWEST_EMISSIONS MOST_PREDICTABLE

constraints

Hard requirements that win over intent. See constraints.

object

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_shipping_rates",
    "arguments": {
      "origin": { "countryCode": "NO", "postalCode": "0174" },
      "destination": { "countryCode": "NO", "postalCode": "1550" },
      "cart": {
        "currency": "NOK",
        "totalCost": 500,
        "items": [{ "quantity": 1, "weightInGrams": 1000 }]
      },
      "selection": {
        "intent": "FASTEST",
        "constraints": { "maxPrice": 200, "latestDeliveryDate": "2026-09-04" }
      },
      "locale": "nb-NO"
    }
  }
}

Mirrors what tools/list returns, which is the authoritative copy. Also available as get_shipping_rates-input-schema.json.

{
  "type": "object",
  "properties": {
    "origin": {
      "type": "object",
      "properties": {
        "countryCode": {
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "enum": [
            "NO",
            "SE",
            "DK",
            "SJ"
          ],
          "description": "ISO 3166-1 alpha-2 country code"
        },
        "postalCode": {
          "type": "string"
        },
        "address1": {
          "type": "string"
        },
        "address2": {
          "type": "string"
        }
      },
      "required": [
        "countryCode",
        "postalCode"
      ],
      "additionalProperties": false
    },
    "destination": {
      "type": "object",
      "properties": {
        "countryCode": {
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "enum": [
            "NO",
            "SE",
            "DK",
            "SJ",
            "FI"
          ],
          "description": "ISO 3166-1 alpha-2 country code"
        },
        "postalCode": {
          "type": "string"
        },
        "address1": {
          "type": "string"
        },
        "address2": {
          "type": "string"
        }
      },
      "required": [
        "countryCode",
        "postalCode"
      ],
      "additionalProperties": false
    },
    "cart": {
      "type": "object",
      "description": "The shopping cart the shipment is for",
      "properties": {
        "currency": {
          "type": "string",
          "pattern": "^[A-Za-z]{3}$",
          "description": "ISO 4217 currency code used for cart values and returned prices. The tool does not convert currencies."
        },
        "totalCost": {
          "type": "number",
          "minimum": 0,
          "description": "Total cart value in cart.currency - required, used for discounted/tiered rates"
        },
        "items": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "properties": {
              "quantity": {
                "type": "integer",
                "minimum": 1
              },
              "weightInGrams": {
                "type": "integer",
                "minimum": 1,
                "description": "Required - affects which services/rate types are available and their weight limits"
              },
              "inStock": {
                "type": "boolean"
              },
              "tooBigForLocker": {
                "type": "boolean"
              },
              "requiresGroupageOrPallet": {
                "type": "boolean"
              }
            },
            "required": [
              "quantity",
              "weightInGrams"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "currency",
        "totalCost",
        "items"
      ],
      "additionalProperties": false
    },
    "selection": {
      "type": "object",
      "description": "Optional intent-driven recommendation on top of the real, unfiltered rates in the response",
      "properties": {
        "intent": {
          "type": "string",
          "enum": [
            "CHEAPEST",
            "FASTEST",
            "LOWEST_EMISSIONS",
            "MOST_PREDICTABLE"
          ],
          "description": "CHEAPEST, FASTEST, LOWEST_EMISSIONS (documented environmental labeling, not measured emissions), or MOST_PREDICTABLE delivery"
        },
        "constraints": {
          "type": "object",
          "description": "Hard requirements that always win over intent - a cheaper option that violates a constraint is never recommended",
          "properties": {
            "maxPrice": {
              "type": "number",
              "exclusiveMinimum": 0
            },
            "latestDeliveryDate": {
              "type": "string",
              "format": "date",
              "description": "ISO-8601 date (YYYY-MM-DD)"
            },
            "allowedDeliveryTypes": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "string",
                "enum": [
                  "PICKUP_POINT",
                  "PARCEL_LOCKER",
                  "DOOR",
                  "MAILBOX",
                  "MAILBOX_ABROAD",
                  "PARCEL_TO_BUSINESS",
                  "GROUPAGE",
                  "PALLET"
                ]
              }
            },
            "requireFossilFree": {
              "type": "boolean"
            }
          },
          "additionalProperties": false
        }
      },
      "required": [
        "intent"
      ],
      "additionalProperties": false
    },
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "nb-NO",
        "sv-SE",
        "da-DK"
      ],
      "description": "Language used for service descriptions and pickup point opening hours. Supported values are en, nb-NO, sv-SE, and da-DK. Defaults to en. Recommendation explanations are always in English, while codes remain stable regardless of language."
    }
  },
  "required": [
    "origin",
    "destination",
    "cart"
  ],
  "additionalProperties": false
}

Response model

Always the same envelope: ok, data, error. Exactly one of data and error is populated.
Delivered both as JSON text and as structuredContent, so schema-aware clients can use the typed form.
Tool failures come back with ok: false and the MCP result flagged as an error, not as an HTTP error status.

data

rates

Every available option, unmodified. See rates.

array

recommendation

Present when you sent a selection and we could answer it. See recommendation.

object or null

rejectedOptions

Options your constraints excluded, each with serviceId, pickupPointId and reasonCodes. Still listed in rates.

array

warnings

What the data could not support. See warnings.

array

rates[]

serviceId

Service code, for example 5800. Matches a recommendation to a rate.

string

displayName, description

Customer-facing text, in the requested locale.

string

type

Delivery type. Which types appear depends on your checkout configuration, the route and the cart.; string
Enum: PICKUP_POINT PARCEL_LOCKER DOOR MAILBOX MAILBOX_ABROAD PARCEL_TO_BUSINESS GROUPAGE PALLET

brand

Posten or Bring, depending on service and route.

string

price

amount and currency, as declared by the cart.

object

agreedDelivery

True when the service has an agreed or guaranteed delivery date.

boolean

leadTime

deliveryDate, an optional deliveryTimeWindow and, for home delivery, deliveryDateAlternatives. Times are HH:mm local. Carried on the rate for door and mailbox types; pickup point types carry it per pickup point.

object or null

pickupPoints

For PICKUP_POINT and PARCEL_LOCKER: the locations to choose from, with id, displayName, address, formattedAddress, distanceInKm, open247, openingHours, openingHoursLanguage, coordinates, and their own leadTime and environmentalData. Null for other types.

array or null

environmentalData

fossilFree, nordicSwanEcoLabel and tagUrl. A null field means unknown, not false.

object or null

recommendation

serviceId, pickupPointId

Always an option that exists in rates, and a pickup point that exists within it. pickupPointId is null for types without pickup points.

string, string or null

intent

The intent this answers, echoed back.

string

reasonCodes

Why this option won. Stable identifiers, safe to map to your own wording and language. See reason codes.

array

explanation

One sentence, always in English.

string

rankingPolicyVersion

The ranking policy behind this recommendation, so you can tell when it changed.

string, currently 2

{
  "ok": true,
  "data": {
    "rates": [
      {
        "serviceId": "5800",
        "displayName": "Pickup parcel",
        "description": "Collect your parcel at a pickup point",
        "type": "PICKUP_POINT",
        "brand": "Posten",
        "price": { "amount": 79, "currency": "NOK" },
        "agreedDelivery": false,
        "pickupPoints": [
          {
            "id": "123456",
            "displayName": "Coop Extra Storgata",
            "formattedAddress": "Storgata 1, 1550 Hølen",
            "address": { "postalCode": "1550", "city": "Hølen", "countryCode": "NO" },
            "distanceInKm": 0.8,
            "open247": false,
            "openingHours": "Man-fre 07-23, lør 08-21",
            "openingHoursLanguage": "nb-NO",
            "coordinates": { "lat": 59.6, "long": 10.7 },
            "leadTime": { "deliveryDate": "2026-09-02" },
            "environmentalData": { "fossilFree": true, "nordicSwanEcoLabel": true, "tagUrl": null }
          }
        ],
        "environmentalData": { "fossilFree": true, "nordicSwanEcoLabel": true, "tagUrl": null }
      }
    ],
    "recommendation": {
      "serviceId": "5800",
      "pickupPointId": "123456",
      "intent": "FASTEST",
      "reasonCodes": ["EARLIEST_DELIVERY"],
      "explanation": "This is the fastest option that satisfies all constraints.",
      "rankingPolicyVersion": "2"
    },
    "rejectedOptions": [
      { "serviceId": "5600", "pickupPointId": null, "reasonCodes": ["DELIVERY_AFTER_DEADLINE"] }
    ],
    "warnings": []
  },
  "error": null
}

Mirrors what tools/list returns, which is the authoritative copy. Also available as get_shipping_rates-output-schema.json.

{
  "type": "object",
  "description": "{ok, data, error} envelope. Exactly one of data/error is non-null.",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": [
        "object",
        "null"
      ],
      "description": "Present only when ok=true",
      "properties": {
        "rates": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "serviceId": {
                "type": "string"
              },
              "displayName": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "enum": [
                  "PICKUP_POINT",
                  "PARCEL_LOCKER",
                  "DOOR",
                  "MAILBOX",
                  "MAILBOX_ABROAD",
                  "PARCEL_TO_BUSINESS",
                  "GROUPAGE",
                  "PALLET"
                ]
              },
              "brand": {
                "type": "string"
              },
              "price": {
                "type": "object",
                "properties": {
                  "amount": {
                    "type": "number"
                  },
                  "currency": {
                    "type": "string",
                    "description": "ISO 4217 currency code declared by cart.currency; no conversion is performed"
                  }
                },
                "required": [
                  "amount",
                  "currency"
                ],
                "additionalProperties": false
              },
              "agreedDelivery": {
                "type": "boolean",
                "description": "True when this service has an agreed/guaranteed delivery date"
              },
              "leadTime": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "deliveryDate": {
                    "type": "string",
                    "format": "date"
                  },
                  "deliveryTimeWindow": {
                    "type": "object",
                    "description": "Delivery time window. Times are HH:mm (24-hour, local time), or null if unknown.",
                    "properties": {
                      "from": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "to": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    },
                    "additionalProperties": false
                  },
                  "deliveryDateAlternatives": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "object",
                      "properties": {
                        "deliveryDate": {
                          "type": "string",
                          "format": "date"
                        },
                        "deliveryTimeWindows": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "description": "Delivery time window. Times are HH:mm (24-hour, local time), or null if unknown.",
                            "properties": {
                              "from": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "to": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            },
                            "additionalProperties": false
                          }
                        }
                      },
                      "required": [
                        "deliveryDate",
                        "deliveryTimeWindows"
                      ],
                      "additionalProperties": false
                    }
                  }
                },
                "required": [
                  "deliveryDate"
                ]
              },
              "pickupPoints": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The pickupPointId used to match a recommendation/rejectedOption to a specific pickup point"
                    },
                    "displayName": {
                      "type": "string"
                    },
                    "address": {
                      "type": "object",
                      "properties": {
                        "addressLine": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "postalCode": {
                          "type": "string"
                        },
                        "city": {
                          "type": "string"
                        },
                        "countryCode": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "postalCode",
                        "city",
                        "countryCode"
                      ],
                      "additionalProperties": false
                    },
                    "formattedAddress": {
                      "type": "string"
                    },
                    "distanceInKm": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "open247": {
                      "type": "boolean"
                    },
                    "openingHours": {
                      "type": "string",
                      "description": "Free text, in the language given by openingHoursLanguage"
                    },
                    "openingHoursLanguage": {
                      "type": "string",
                      "description": "BCP 47 tag for the language openingHours is written in"
                    },
                    "coordinates": {
                      "type": "object",
                      "properties": {
                        "lat": {
                          "type": "number"
                        },
                        "long": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "lat",
                        "long"
                      ],
                      "additionalProperties": false
                    },
                    "leadTime": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "deliveryDate": {
                          "type": "string",
                          "format": "date"
                        },
                        "deliveryTimeWindow": {
                          "type": "object",
                          "description": "Delivery time window. Times are HH:mm (24-hour, local time), or null if unknown.",
                          "properties": {
                            "from": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "to": {
                              "type": [
                                "string",
                                "null"
                              ]
                            }
                          },
                          "additionalProperties": false
                        },
                        "deliveryDateAlternatives": {
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "object",
                            "properties": {
                              "deliveryDate": {
                                "type": "string",
                                "format": "date"
                              },
                              "deliveryTimeWindows": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "description": "Delivery time window. Times are HH:mm (24-hour, local time), or null if unknown.",
                                  "properties": {
                                    "from": {
                                      "type": [
                                        "string",
                                        "null"
                                      ]
                                    },
                                    "to": {
                                      "type": [
                                        "string",
                                        "null"
                                      ]
                                    }
                                  },
                                  "additionalProperties": false
                                }
                              }
                            },
                            "required": [
                              "deliveryDate",
                              "deliveryTimeWindows"
                            ],
                            "additionalProperties": false
                          }
                        }
                      },
                      "required": [
                        "deliveryDate"
                      ]
                    },
                    "environmentalData": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "null fields mean unknown, not false",
                      "properties": {
                        "fossilFree": {
                          "type": [
                            "boolean",
                            "null"
                          ]
                        },
                        "nordicSwanEcoLabel": {
                          "type": [
                            "boolean",
                            "null"
                          ]
                        },
                        "tagUrl": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "id",
                    "displayName",
                    "address",
                    "formattedAddress",
                    "open247",
                    "openingHours",
                    "openingHoursLanguage",
                    "coordinates"
                  ],
                  "additionalProperties": false
                }
              },
              "environmentalData": {
                "type": [
                  "object",
                  "null"
                ],
                "description": "null fields mean unknown, not false",
                "properties": {
                  "fossilFree": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "nordicSwanEcoLabel": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "tagUrl": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "additionalProperties": false
              }
            },
            "required": [
              "serviceId",
              "displayName",
              "description",
              "type",
              "brand",
              "price",
              "agreedDelivery"
            ],
            "additionalProperties": false
          }
        },
        "recommendation": {
          "type": [
            "object",
            "null"
          ],
          "description": "The (serviceId, pickupPointId) here always corresponds exactly to an entry (or nested pickup point) in data.rates - never a dropped or unknown service.",
          "properties": {
            "serviceId": {
              "type": "string"
            },
            "pickupPointId": {
              "type": [
                "string",
                "null"
              ]
            },
            "intent": {
              "type": "string",
              "enum": [
                "CHEAPEST",
                "FASTEST",
                "LOWEST_EMISSIONS",
                "MOST_PREDICTABLE"
              ]
            },
            "reasonCodes": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "LOWEST_PRICE",
                  "EARLIEST_DELIVERY",
                  "KNOWN_DELIVERY_DATE",
                  "FOSSIL_FREE",
                  "NORDIC_SWAN_ECO_LABEL",
                  "AGREED_DELIVERY",
                  "NARROW_DELIVERY_WINDOW",
                  "PRICE_ABOVE_MAXIMUM",
                  "DELIVERY_AFTER_DEADLINE",
                  "DELIVERY_TYPE_NOT_ALLOWED",
                  "FOSSIL_FREE_REQUIRED",
                  "DELIVERY_DATE_UNKNOWN",
                  "ENVIRONMENTAL_DATA_INCOMPLETE"
                ]
              }
            },
            "explanation": {
              "type": "string",
              "description": "Always in English"
            },
            "rankingPolicyVersion": {
              "type": "string"
            }
          },
          "required": [
            "serviceId",
            "intent",
            "reasonCodes",
            "explanation",
            "rankingPolicyVersion"
          ]
        },
        "rejectedOptions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "serviceId": {
                "type": "string"
              },
              "pickupPointId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "reasonCodes": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "LOWEST_PRICE",
                    "EARLIEST_DELIVERY",
                    "KNOWN_DELIVERY_DATE",
                    "FOSSIL_FREE",
                    "NORDIC_SWAN_ECO_LABEL",
                    "AGREED_DELIVERY",
                    "NARROW_DELIVERY_WINDOW",
                    "PRICE_ABOVE_MAXIMUM",
                    "DELIVERY_AFTER_DEADLINE",
                    "DELIVERY_TYPE_NOT_ALLOWED",
                    "FOSSIL_FREE_REQUIRED",
                    "DELIVERY_DATE_UNKNOWN",
                    "ENVIRONMENTAL_DATA_INCOMPLETE"
                  ]
                }
              }
            },
            "required": [
              "serviceId",
              "reasonCodes"
            ],
            "additionalProperties": false
          }
        },
        "warnings": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "NO_AVAILABLE_RATES",
                  "NO_OPTIONS_MATCH_CONSTRAINTS",
                  "ENVIRONMENTAL_RANKING_USES_LABELS",
                  "ENVIRONMENTAL_DATA_INCOMPLETE",
                  "INSUFFICIENT_DELIVERY_DATA",
                  "INSUFFICIENT_PREDICTABILITY_DATA"
                ]
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "rates",
        "rejectedOptions",
        "warnings"
      ],
      "additionalProperties": false
    },
    "error": {
      "type": [
        "object",
        "null"
      ],
      "description": "Present only when ok=false. Never contains raw exception messages, stack traces, or internal identifiers.",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "INVALID_ARGUMENT",
            "WEBSHOP_NOT_FOUND",
            "WEBSHOP_NOT_INSTALLED",
            "UNSUPPORTED_ORIGIN_COUNTRY",
            "UNSUPPORTED_DESTINATION_COUNTRY",
            "UPSTREAM_UNAVAILABLE",
            "RATE_CALCULATION_FAILED",
            "INTERNAL_ERROR"
          ]
        },
        "message": {
          "type": "string"
        },
        "field": {
          "type": [
            "string",
            "null"
          ],
          "description": "Dotted path of the offending request field, if applicable"
        },
        "retryable": {
          "type": "boolean",
          "description": "True only when retrying the same call could plausibly succeed, e.g. a transient upstream failure"
        }
      },
      "required": [
        "code",
        "message",
        "retryable"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "ok",
    "data",
    "error"
  ],
  "additionalProperties": false
}

Intents

Intent	Ranks by
`CHEAPEST`	Lowest price, then earliest known delivery date.
`FASTEST`	Earliest delivery date. Needs one option with a known date, otherwise no recommendation and an `INSUFFICIENT_DELIVERY_DATA` warning.
`LOWEST_EMISSIONS`	Documented labelling – `fossilFree` and `nordicSwanEcoLabel` – not measured emissions. Always returns an `ENVIRONMENTAL_RANKING_USES_LABELS` warning.
`MOST_PREDICTABLE`	Agreed delivery, then a narrow delivery window, then a known date.

Constraints

Constraints are hard requirements. An option that breaks one is never recommended. It moves to rejectedOptions with a reason code, and stays in the rate list.

Constraint	Type	Effect
`maxPrice`	number	Rejects anything priced above it: `PRICE_ABOVE_MAXIMUM`.
`latestDeliveryDate`	date	`YYYY-MM-DD`. Rejects later dates with `DELIVERY_AFTER_DEADLINE`, and unknown dates with `DELIVERY_DATE_UNKNOWN`.
`allowedDeliveryTypes`	array	Others get `DELIVERY_TYPE_NOT_ALLOWED`. Omit to allow everything; an empty array is an error.
`requireFossilFree`	boolean	Others get `FOSSIL_FREE_REQUIRED`.

Reason codes

Code	Appears on	Meaning
`LOWEST_PRICE`	Recommendation	Cheapest qualifying option.
`EARLIEST_DELIVERY`	Recommendation	Earliest delivery date.
`KNOWN_DELIVERY_DATE`	Recommendation	The delivery date is known.
`NARROW_DELIVERY_WINDOW`	Recommendation	Has a complete delivery time window.
`AGREED_DELIVERY`	Recommendation	Agreed or guaranteed delivery date.
`FOSSIL_FREE`	Recommendation	Documented as fossil-free.
`NORDIC_SWAN_ECO_LABEL`	Recommendation	Carries the Nordic Swan eco label.
`PRICE_ABOVE_MAXIMUM`	Rejection	Above `maxPrice`.
`DELIVERY_AFTER_DEADLINE`	Rejection	Arrives after `latestDeliveryDate`.
`DELIVERY_DATE_UNKNOWN`	Rejection	No known date, so a deadline cannot be guaranteed.
`DELIVERY_TYPE_NOT_ALLOWED`	Rejection	Not in `allowedDeliveryTypes`.
`FOSSIL_FREE_REQUIRED`	Rejection	Not documented as fossil-free.
`ENVIRONMENTAL_DATA_INCOMPLETE`	Rejection	No documented environmental signal to rank on.

Warnings

Warnings arrive with ok: true. They say what the data could not support, not that the call failed.

Code	Meaning
`NO_AVAILABLE_RATES`	No rates at all for this route and cart.
`NO_OPTIONS_MATCH_CONSTRAINTS`	Rates exist, none satisfies every constraint. See `rejectedOptions`.
`ENVIRONMENTAL_RANKING_USES_LABELS`	Always on `LOWEST_EMISSIONS`: ranking is by labelling, not measurement.
`ENVIRONMENTAL_DATA_INCOMPLETE`	No qualifying option has a documented environmental signal.
`INSUFFICIENT_DELIVERY_DATA`	No qualifying option has a known delivery date.
`INSUFFICIENT_PREDICTABILITY_DATA`	Nothing has agreed delivery, a known date or a time window.

Errors

On failure, error carries a code, a message written for a person, an optional field naming the offending request field, and retryable – true only when the same call could plausibly succeed on a second attempt.

Code	Meaning	Retryable
`INVALID_ARGUMENT`	Arguments do not match the schema, or a value is out of range.	No
`WEBSHOP_NOT_FOUND`	No webshop is configured for that Agent ID.	No
`WEBSHOP_NOT_INSTALLED`	The webshop exists but is not activated.	No
`UNSUPPORTED_ORIGIN_COUNTRY`	Sender country outside NO, SE, DK, SJ.	No
`UNSUPPORTED_DESTINATION_COUNTRY`	Recipient country outside NO, SE, DK, SJ, FI.	No
`UPSTREAM_UNAVAILABLE`	A service we depend on is temporarily unavailable.	Yes
`RATE_CALCULATION_FAILED`	Rates could not be calculated for this route.	No
`INTERNAL_ERROR`	Something failed on our side.	Sometimes