Skip to main content

Delivery and discounts on agent carts

An agent that builds a cart over /agent/mcp can give a shipping destination and get your store's delivery options with their prices, select one, submit coupon codes, and say who the cart is for. The cart it gets back shows the delivery row, the discounts and the total the same quote shows in your own checkout.

The shopper still completes the purchase in your storefront through the cart's continue_url. Agents cannot check out or pay.

What your store needs​

Delivery and discounts have no settings of their own. They work when Enable Agent Cart and Enable Generic MCP Endpoint are Yes on the Settings page and use what your store already has configured:

  • Shipping methods - at Stores -> Configuration -> Sales -> Delivery Methods. Each active method that can ship the cart to the destination becomes a delivery option. With no active method, agents see no delivery options, and the merchant profile does not declare delivery.
  • Allowed countries - at Stores -> Configuration -> General -> General -> Country Options. A destination outside them gets no options and a message saying the store does not deliver there.
  • Cart price rules - at Marketing -> Promotions -> Cart Price Rules. Rules without a coupon apply automatically and are reported on the cart. Rules with a coupon apply when the agent submits the code.

The merchant profile at /.well-known/ucp declares the two capabilities agents look for: dev.ucp.shopping.fulfillment (delivery, to a single destination, shipping only) and dev.ucp.shopping.discount.

Delivery​

The agent sends the destination in cart.fulfillment on create_cart or update_cart. A country and postcode are enough. A full street address gives more exact rates for carriers that price by address.

"fulfillment": {
  "methods": [{
    "type": "shipping",
    "destinations": [{"address_country": "US", "postal_code": "90034"}]
  }]
}

The cart comes back with the options under fulfillment.methods[0].groups[0].options, each with an id, a title and a price in minor units (500 is $5.00):

"options": [
  {"id": "flatrate_flatrate", "title": "Fixed", "carrier": "Flat Rate",
   "totals": [{"type": "fulfillment", "amount": 500}]},
  {"id": "tablerate_bestway", "title": "Table Rate", "carrier": "Best Way",
   "totals": [{"type": "fulfillment", "amount": 1500}]}
]

Until an option is selected, the totals leave out delivery, and the cart carries a totals_partial message saying so. Before a destination is given, the message also says tax may change. The agent selects an option by sending its id:

"fulfillment": {
  "methods": [{
    "type": "shipping",
    "groups": [{"id": "package", "selected_option_id": "flatrate_flatrate"}]
  }]
}

The delivery row then appears in totals, and the grand total includes it.

  • When no method can deliver to the destination, the cart has no options and a message explains why. The agent is not shown a total that silently leaves out delivery.
  • Every change to the cart's items prices delivery again. If the selected option is no longer offered, the selection is cleared and a message says so.
  • A cart ships to one address. On update_cart, "methods": [] removes the destination.

Discounts​

The agent submits coupon codes in cart.discounts.codes:

"discounts": {"codes": ["SUMMER10"]}
  • When a code in a new list applies, it replaces the coupon submitted before, and [] removes the coupon. When no code in the list applies, the cart is left as it was, including the coupon it already had.
  • Magento applies one coupon per cart, so codes are tried in order and the first one that applies is kept. The codes after it come back with a message saying the cart takes one coupon code.
  • Every discount that lowers the cart's price is listed under discounts.applied with its title and amount. A rule whose only effect is free shipping is not listed there; it shows as a lower delivery price. Automatic rules are marked "automatic": true; a coupon discount carries its code.
  • A refused code comes back with a message that says why: not a valid code, not active yet, expired, used up, needs a signed-in customer, or the cart does not meet the rule's conditions. A coupon that stops applying after the cart changes is removed, with a message.
  • Each cart allows a limited number of code attempts, so a cart cannot be used to guess codes.

Buyer​

The agent can state who the cart is for in cart.buyer: first_name, last_name, email and phone_number (in international format, for example +14155550123). The cart stores these and returns them, so the agent can confirm them with the shopper. They do not create a customer account, and the shopper enters their details at checkout as usual.

Try it​

The Test with an agent button on the Agent Activity dashboard builds a cart and then, on a separate cart, prices delivery to the country, region, postcode and city of your shipping origin (Stores -> Configuration -> Sales -> Shipping Settings -> Origin) and selects the first option, so you can see the options and the delivery row your store returns. The cart behind the test's continue_url has no delivery address.

If no shipping method delivers to your origin address, the delivery step is marked ✗ with the reason an agent would get, and no option is selected. This does not fail the test, since the origin is your warehouse address, which you may not sell to. The test skips delivery when your store has no active shipping method, when no origin country is set, or when the first steps failed.