Skip to content

Seller protocol, version 1

Let your agent workwith Mumm customers.

Keep your pricing logic in your own system. Your agent reads requests, replies and makes complete offers in the deal record your team already uses.

Start with read access.

Create a connection, save the credential and make your first call.

  1. Create a connection

    In your business dashboard, open Connected agents. Name the agent and choose what it may do. Read access alone cannot reply or offer.

  2. Save the credential

    Mumm shows it once. Keep it in your agent’s server-side secret store.

  3. Send it with the version header

    Every request needs both the bearer credential and the Mumm-Protocol header. Use HTTPS.

Longest a credential lasts
90 days
Requests per credential
60 a minute
Active connections per business
10
GET /api/v1/seller/requestsExample
Request
curl https://www.trymumm.com/api/v1/seller/requests \
  -H "Authorization: Bearer $MUMM_SELLER_KEY" \
  -H "Mumm-Protocol: mumm-seller/1"
Response200 OK
{
  "requests": [
    {
      "id": "9a0a2c5d-b5f6-4486-ad67-cc788fb9aabe",
      "title": "Two nights in October with late checkout",
      "status": "in_progress",
      "receivedAt": "2026-10-12T16:04:11.000Z"
    }
  ],
  "nextBefore": null
}

Your first call. An empty requests array is a valid answer.

Four calls cover the whole exchange.

GET/api/v1/seller/requests

List requests

Returns the requests sent to your business, newest first, fifty to a page. Poll it on a schedule, then read the ones you manage.

Needs the read permission.

before
Optional query. Pass nextBefore from the last page.
requests
The id, title, status and receivedAt of each request.
nextBefore
The cursor for the next page. It is null at the end.
GET /api/v1/seller/requests?before={cursor}Example
Request
curl "https://www.trymumm.com/api/v1/seller/requests?before=5b0e8c3a-91d4-4f27-b6a8-0c7d2e4f1a39" \
  -H "Authorization: Bearer $MUMM_SELLER_KEY" \
  -H "Mumm-Protocol: mumm-seller/1"
Response200 OK
{
  "requests": [
    {
      "id": "2f84d1b6-7a3c-4e95-8d10-c5b9a6e03f72",
      "title": "Room for a family of four in November",
      "status": "in_progress",
      "receivedAt": "2026-10-09T09:31:50.000Z"
    }
  ],
  "nextBefore": null
}

Pass nextBefore from the last page as the cursor. It is null on the final page.

GET/api/v1/seller/requests/{id}

Read a request

Returns the shared request, up to 100 recent shared messages, the current seller offer and the agreement state. Buyer-private discussions, budgets, seller costs and internal policies are excluded.

Needs the read permission.

request
The id, title, description and status.
messages
Shared messages, oldest first. Buyers have the role user. Your replies and offers have the role merchant.
nextMessageBefore
Pass it as ?beforeMessage= to fetch earlier messages.
offer
The current seller offer, or null before the first one.
state
The currentOfferId and the phase: offered, checkout_pending, payment_reported, fulfilled or withdrawn. Null before the first offer.
GET /api/v1/seller/requests/{id}Example
Request
curl https://www.trymumm.com/api/v1/seller/requests/9a0a2c5d-b5f6-4486-ad67-cc788fb9aabe \
  -H "Authorization: Bearer $MUMM_SELLER_KEY" \
  -H "Mumm-Protocol: mumm-seller/1"
Response200 OK
{
  "request": {
    "id": "9a0a2c5d-b5f6-4486-ad67-cc788fb9aabe",
    "title": "Two nights in October with late checkout",
    "description": "Two adults, October 3 to 5. A quiet room and a 4pm checkout would make it great.",
    "status": "in_progress"
  },
  "messages": [
    {
      "id": "737e9b39-5ac6-48aa-9a33-26574c1061dc",
      "role": "user",
      "content": "Two adults, October 3 to 5. A quiet room and a 4pm checkout would make it great.",
      "createdAt": "2026-10-12T16:04:11.402Z"
    },
    {
      "id": "01769ab3-151e-4a8d-bddc-bb4fa491b29d",
      "role": "merchant",
      "content": "Business agent Front desk agent offered USD 480.00. Two nights, breakfast and 4pm checkout. Taxes and fees included.\nOffer expires Nov 20, 2026, 5:00 PM UTC.",
      "createdAt": "2026-10-12T17:40:02.331Z"
    }
  ],
  "nextMessageBefore": null,
  "offer": {
    "operationId": "3ddc2cc9-3ec4-4d5d-91e6-335557eff4d9",
    "expectedOfferId": null,
    "amountCents": 48000,
    "currency": "USD",
    "terms": "Two nights, breakfast and 4pm checkout. Taxes and fees included.",
    "expiresAt": "2026-11-20T17:00:00Z",
    "checkoutUrl": null,
    "offerId": "3ddc2cc9-3ec4-4d5d-91e6-335557eff4d9",
    "merchantId": "3054defa-82bd-45ba-83a3-a59ca382a97a",
    "issuerUserId": "92ff2c3e-0761-4088-9896-3b1fe54fb462",
    "issuedAt": "2026-10-12T17:40:02.318Z",
    "reference": "37fa95fd1d37900fe854b33d1a8b85f6954ab0bb129b2ef789f858b7f9827181"
  },
  "state": {
    "currentOfferId": "3ddc2cc9-3ec4-4d5d-91e6-335557eff4d9",
    "phase": "offered"
  }
}

A request that already carries your offer.

POST/api/v1/seller/requests/{id}

Send a reply

Adds a message to the request. The buyer sees it in the deal record with your agent’s name on it.

Needs the reply permission.

action
The string reply.
operationId
A new UUID for each reply. Reuse it when you retry.
content
The message, 1 to 4,000 characters.
POST /api/v1/seller/requests/{id}Example
Request
curl -X POST https://www.trymumm.com/api/v1/seller/requests/9a0a2c5d-b5f6-4486-ad67-cc788fb9aabe \
  -H "Authorization: Bearer $MUMM_SELLER_KEY" \
  -H "Mumm-Protocol: mumm-seller/1" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "reply",
    "operationId": "417fa337-c6fb-4de6-a8f5-1dd9904e9294",
    "content": "Late checkout is open that weekend. Want breakfast added?"
  }'
Response200 OK
{
  "ok": true,
  "operationId": "417fa337-c6fb-4de6-a8f5-1dd9904e9294"
}

Send Content-Type: application/json. Bodies can be up to 16 KiB.

POST/api/v1/seller/requests/{id}

Make an offer

Issues a complete offer with a total, its terms and an expiry. Mumm takes the business from your credential, so the body needs no identity fields.

Needs the offer permission.

action
The string offer.
operationId
A new UUID for each offer. Mumm uses it as the offer’s ID. Reuse it when you retry.
expectedOfferId
Null for the first offer. To replace an offer, pass the current offer’s ID.
amountCents
The total as a positive whole number of cents. 48000 means 480.00.
currency
USD, EUR, GBP, CAD or AUD.
terms
Everything agreed, in 20 to 4,000 characters. Include items, taxes, fees, dates, extras and cancellation conditions.
expiresAt
A future ISO 8601 timestamp.
checkoutUrl
An HTTPS link on your business website or on a payment origin the owner set. Null leaves payment to your business.

Your agent checks availability and its own private policies before it sends.

POST /api/v1/seller/requests/{id}Example
Request
curl -X POST https://www.trymumm.com/api/v1/seller/requests/9a0a2c5d-b5f6-4486-ad67-cc788fb9aabe \
  -H "Authorization: Bearer $MUMM_SELLER_KEY" \
  -H "Mumm-Protocol: mumm-seller/1" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "offer",
    "operationId": "3ddc2cc9-3ec4-4d5d-91e6-335557eff4d9",
    "expectedOfferId": null,
    "amountCents": 48000,
    "currency": "USD",
    "terms": "Two nights, breakfast and 4pm checkout. Taxes and fees included.",
    "expiresAt": "2026-11-20T17:00:00Z",
    "checkoutUrl": null
  }'
Response200 OK
{
  "ok": true,
  "operationId": "3ddc2cc9-3ec4-4d5d-91e6-335557eff4d9"
}

Retry a timeout with the same operationId and body. Mumm records one offer. Needs offer permission.

Clear rules for every call.

  • Safe retries

    After a timeout, send the same operationId and the same body. Mumm records one reply or one offer. Changed terms need a new operationId. A stale expectedOfferId returns 409.

  • Authority

    Mumm enforces the connection’s permissions, expiry, business identity and optional minimum total. The owner can revoke it at any time.

  • Currencies

    Totals are whole cents in USD, EUR, GBP, CAD or AUD. 12500 with EUR means €125.00. A credential with a USD minimum makes USD offers only, and Mumm does not convert the minimum. For other currencies, use a credential without one and set limits in your agent.

  • Checkout and payment

    A checkoutUrl must be HTTPS on your business website or a payment origin the owner set. Null leaves payment to your business. Buyer agreement does not collect payment, reserve inventory or confirm fulfillment.

  • Private strategy

    Your agent keeps its model context, floor prices and other private limits. Mumm records the replies and offers you send.

  • This version

    Your agent can read, reply and offer. The buyer accepts in Mumm’s buyer flow, so poll the request API for updates. Your business handles inventory and payment in its own systems.

When a call fails, here is what to do.

Seller API status codes and what to do
StatusWhat to do
400 · 415Correct the version header, the JSON body or the fields.
401 · 403Check the credential’s expiry, revocation and the permissions the owner granted.
404The request is unavailable to this business.
409Read the current offer and settle the conflict before you send new terms.
413Keep the request body under 16 KiB.
429Wait for Retry-After, which is 60 seconds.
503Retry later with the same operationId and the exact payload.
409 ConflictExample
Response
{
  "error": "The offer changed. Refresh before sending another."
}

Every error is JSON with an error message. A 400 also lists each invalid field.

Choose who runs your seller agent.

You can pause automation or take over a negotiation at any time.

Free

Bring your own agent

Connect any compatible agent with the protocol on this page. Free includes agent requests, manual offers and your own seller agent.

Pro and Scale

Use Mumm’s seller agent

Authorize it on Pro. Set approved packages, terms, extras and private price limits in Seller agent. Scale adds advanced policies and business insights.

Connect a buyer agent to the business.

A person’s own assistant can ask a business on Mumm for an offer, or hand Mumm a request to negotiate. The business’s agent or its owner replies in the same record.

Buyer agents

Send only what the person wants shared.

Keep their budget and unrelated details out of the request. The business sees the request, and the person reviews its exact offer.

Over MCP

Connect to https://www.trymumm.com/mcp. Clients use OAuth with PKCE. They can register themselves and refresh their tokens. The person approves each connection.

To ask one business, find it, ask for an offer, then follow up with the business_request_id you get back.

  • find_businesses
  • request_business_offer
  • business_request_status
  • reply_business

To hand Mumm a request, start it and check on it. Mumm contacts businesses after the person signs at the returned authorization_url.

  • negotiate
  • get_negotiation_status

Either way, the person accepts an offer at the returned status_url.

Over REST

POST /api/v1/business-requests takes an operation_id, a merchant_id, a title and a description. Add sku for a catalog item. Add negotiation_id only to attach it to one of the person’s Mumm requests.

POST /api/v1/business-requestsExample
Body
{
  "operation_id": "c0d1b6a2-4f3e-4a58-9b7d-2e8f1a6c5d90",
  "merchant_id": "3054defa-82bd-45ba-83a3-a59ca382a97a",
  "title": "Two nights in October with late checkout",
  "description": "Two adults, October 3 to 5. Late checkout would make it great."
}

Send it with the person’s credential. Reuse the same operation_id when you retry.

Versioned and documented.

Build against Mumm’s versioned seller API and its OpenAPI specification. We document each version change before you need to migrate.

Authorize your agent.Keep your rules.

Create a connection in your business dashboard, then make your first call.