haggl.ai

List vendors that accept AI-agent price negotiations through haggl.ai. A vendor appears once haggl.ai is installed on its own store or website (the listed website): the haggl.ai Shopify app on that store, or its snippet detected on that site. Vendors can opt out, so the list is not exhaustive. haggl.ai runs each vendor's sales agent, and vendors on a paid plan pay haggl.ai for it; the list is not a ranking or recommendation. Use it when the user asks for a discount or wants to negotiate a price, not for a purchase at the listed price.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "vendors": {
      "type": "array",
      "description": "Participating vendors. Not a ranking or recommendation.",
      "items": {
        "type": "object",
        "description": "A participating merchant.",
        "properties": {
          "vendorId": {
            "type": "string",
            "description": "Vendor id for haggl_start_negotiation."
          },
          "name": {
            "type": "string",
            "description": "Merchant name."
          },
          "category": {
            "type": "string",
            "description": "Merchant category."
          },
          "website": {
            "type": "string",
            "description": "The merchant's own website."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "What the merchant sells."
          }
        }
      }
    },
    "next_step": {
      "type": "string",
      "description": "What to call next."
    },
    "error": {
      "type": "string",
      "description": "Present only when the call failed: what went wrong."
    },
    "code": {
      "type": "string",
      "description": "Present only when the call failed: a machine-readable error code, e.g. quote_uncertain or rate_limited."
    },
    "recovery": {
      "type": "object",
      "description": "When the outcome is uncertain: the tool and session_id to read before retrying.",
      "properties": {}
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the same call may be retried."
    },
    "retry_after_seconds": {
      "type": "integer",
      "description": "When rate limited: seconds to wait before retrying."
    }
  }
}

Start a price negotiation with a vendor. Returns contextual guidance, current permitted actions and a new session with a session id. No customer-profile selection is required. Skip this tool if REST initialization already returned a session; pass that session.id directly to haggl_submit_offer.

{
  "type": "object",
  "properties": {
    "vendor_id": {
      "type": "string",
      "description": "Vendor id from haggl_list_vendors, a haggl-vendor meta tag, or a haggl-negotiate URL."
    },
    "data": {
      "type": "object",
      "description": "Optional available buyer context; together with ask, requests an opening quote in this same call."
    },
    "ask": {
      "type": "object",
      "description": "Optional requested products, quantities or service, in the same shape as the haggl_submit_offer ask. Supply known context upfront."
    },
    "haggl_id": {
      "type": "string",
      "description": "Optional: the user's haggl ID from haggl_create_haggl_id, so this offer and its code are kept with their other offers."
    }
  },
  "required": [
    "vendor_id"
  ]
}

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "description": "Negotiation session id."
    },
    "vendor_id": {
      "type": "string",
      "description": "Vendor id."
    },
    "status": {
      "type": "string",
      "description": "Session status."
    },
    "state": {
      "type": "object",
      "description": "Canonical negotiation state. Follow allowed_actions.",
      "properties": {
        "status": {
          "type": "string",
          "description": "open, offered, final, reserved, accepted, expired, rejected, unavailable or merchant_action_required."
        },
        "allowed_actions": {
          "type": "array",
          "description": "The actions permitted now.",
          "items": {
            "type": "string"
          }
        },
        "offer_version": {
          "type": "integer",
          "description": "The current offer version; acceptance names the version the buyer approved."
        },
        "finality_reason": {
          "type": [
            "string",
            "null"
          ],
          "description": "Why no further offer will come, when final."
        },
        "offer_expires_at": {
          "type": "string",
          "description": "ISO 8601 time the current offer expires."
        },
        "commits_purchase": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Whether acceptance itself commits a purchase (never true: payment happens at the merchant)."
        },
        "acceptance_requires_user_approval": {
          "type": "boolean",
          "description": "Always true: accept only an offer the buyer approved."
        },
        "acceptance_effects": {
          "type": "array",
          "description": "What acceptance does, e.g. issues a coupon or a checkout link.",
          "items": {
            "type": "string"
          }
        },
        "merchant_assistance": {
          "type": [
            "object",
            "null"
          ],
          "description": "When status is merchant_action_required: what to tell the buyer.",
          "properties": {
            "message": {
              "description": "What to tell the buyer."
            },
            "contact_email": {
              "description": "Where the buyer can reach the merchant."
            },
            "reference": {
              "description": "The reference to quote."
            }
          }
        }
      }
    },
    "current_offer": {
      "type": [
        "object",
        "null"
      ],
      "description": "The merchant's offer for the requested items. Merchant engines may add fields.",
      "properties": {
        "vendor": {
          "description": "The seller, to show the buyer before acceptance."
        },
        "discount_pct": {
          "description": "Discount in percent."
        },
        "currency": {
          "description": "ISO 4217 currency."
        },
        "applies_to": {
          "description": "The items and quantities the discount covers, and any exclusions."
        },
        "note": {
          "description": "The sales agent's note to the buyer."
        },
        "valid_until": {
          "description": "ISO 8601 time the offer expires."
        },
        "personalized_price_notice": {
          "description": "Show this to the buyer word for word with the offer."
        }
      }
    },
    "guidance": {
      "type": [
        "object",
        "null"
      ],
      "description": "What this merchant values, as contextual guidance. Evidence is optional.",
      "properties": {}
    },
    "context_received": {
      "type": "object",
      "description": "The buyer context fields received so far and their provenance.",
      "properties": {}
    },
    "max_rounds": {
      "type": "integer",
      "description": "Most quote rounds in this session."
    },
    "current_round": {
      "type": "integer",
      "description": "Rounds used."
    },
    "rounds_remaining": {
      "type": "integer",
      "description": "Rounds left."
    },
    "rounds": {
      "type": "array",
      "description": "Each round: the offer and when it was made."
    },
    "accepted_offer": {
      "type": [
        "object",
        "null"
      ],
      "description": "The merchant's offer for the requested items. Merchant engines may add fields.",
      "properties": {
        "vendor": {
          "description": "The seller, to show the buyer before acceptance."
        },
        "discount_pct": {
          "description": "Discount in percent."
        },
        "currency": {
          "description": "ISO 4217 currency."
        },
        "applies_to": {
          "description": "The items and quantities the discount covers, and any exclusions."
        },
        "note": {
          "description": "The sales agent's note to the buyer."
        },
        "valid_until": {
          "description": "ISO 8601 time the offer expires."
        },
        "personalized_price_notice": {
          "description": "Show this to the buyer word for word with the offer."
        }
      }
    },
    "next_steps": {
      "type": "object",
      "description": "After acceptance: how the buyer redeems the offer (checkout_url, coupon_code, reference, expires_at, …).",
      "properties": {}
    },
    "expires_at": {
      "type": "string",
      "description": "ISO 8601 time the session expires."
    },
    "created_at": {
      "type": "string",
      "description": "ISO 8601 time the session started."
    },
    "round": {
      "type": "integer",
      "description": "The round this quote answered."
    },
    "offer": {
      "type": "object",
      "description": "The merchant's offer for the requested items. Merchant engines may add fields.",
      "properties": {
        "vendor": {
          "description": "The seller, to show the buyer before acceptance."
        },
        "discount_pct": {
          "description": "Discount in percent."
        },
        "currency": {
          "description": "ISO 4217 currency."
        },
        "applies_to": {
          "description": "The items and quantities the discount covers, and any exclusions."
        },
        "note": {
          "description": "The sales agent's note to the buyer."
        },
        "valid_until": {
          "description": "ISO 8601 time the offer expires."
        },
        "personalized_price_notice": {
          "description": "Show this to the buyer word for word with the offer."
        }
      }
    },
    "data_feedback": {
      "type": "object",
      "description": "Which context fields were used, and which could improve the offer.",
      "properties": {}
    },
    "session": {
      "type": "object",
      "description": "The new session.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Session id for haggl_submit_offer."
        },
        "negotiate_url": {
          "type": "string",
          "description": "REST URL to request a quote."
        },
        "accept_url": {
          "type": "string",
          "description": "REST URL to accept."
        },
        "status_url": {
          "type": "string",
          "description": "REST URL to read the session."
        },
        "max_rounds": {
          "type": "integer",
          "description": "Most quote rounds."
        },
        "expires_at": {
          "type": "string",
          "description": "ISO 8601 expiry."
        }
      }
    },
    "vendor": {
      "type": "object",
      "description": "The merchant this session negotiates with.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Vendor id."
        },
        "name": {
          "type": "string",
          "description": "Merchant name."
        },
        "category": {
          "type": "string",
          "description": "Merchant category."
        },
        "website": {
          "type": "string",
          "description": "The merchant's own website."
        },
        "local_service": {
          "type": "object",
          "description": "For a local service that closes by phone: prices, saving cap and arrival time.",
          "properties": {}
        }
      }
    },
    "catalog": {
      "type": [
        "object",
        "null"
      ],
      "description": "How to name exact products: a store catalog or a campaign catalog. Search it with haggl_search_catalog.",
      "properties": {
        "type": {
          "type": "string",
          "description": "\"campaign\" for a campaign catalog."
        },
        "search_url": {
          "type": "string",
          "description": "Catalog search URL."
        },
        "how_to_ask": {
          "type": "string",
          "description": "The ask shape this catalog takes."
        }
      }
    },
    "how_it_works": {
      "type": "array",
      "description": "The negotiation flow, step by step.",
      "items": {
        "type": "string"
      }
    },
    "protocol_url": {
      "type": "string",
      "description": "Protocol documentation."
    },
    "error": {
      "type": "string",
      "description": "Present only when the call failed: what went wrong."
    },
    "code": {
      "type": "string",
      "description": "Present only when the call failed: a machine-readable error code, e.g. quote_uncertain or rate_limited."
    },
    "recovery": {
      "type": "object",
      "description": "When the outcome is uncertain: the tool and session_id to read before retrying.",
      "properties": {}
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the same call may be retried."
    },
    "retry_after_seconds": {
      "type": "integer",
      "description": "When rate limited: seconds to wait before retrying."
    }
  }
}

Search a vendor's catalog so the offer can name exact products, then follow the how_to_ask field of the result. A store catalog returns products with a handle, price and collections: ask with ask.items [{ product_handle, quantity }]. A campaign catalog returns eligible variants with a variant_id and approved_combinations with a recipe_id: ask with ask.items [{ variant_id, quantity }] or ask.recipe_id. A quote identifies the exact items and quantities it covers.

{
  "type": "object",
  "properties": {
    "vendor_id": {
      "type": "string",
      "description": "Vendor id."
    },
    "query": {
      "type": "string",
      "description": "Free-text search, e.g. \"tennis racket\"."
    },
    "collection": {
      "type": "string",
      "description": "Optional collection handle to filter by."
    },
    "limit": {
      "type": "number",
      "description": "Max results (default 25)."
    }
  },
  "required": [
    "vendor_id"
  ]
}

{
  "type": "object",
  "properties": {
    "vendor_id": {
      "type": "string",
      "description": "Vendor id."
    },
    "currency": {
      "type": "string",
      "description": "ISO 4217 currency."
    },
    "products": {
      "type": "array",
      "description": "Store catalog: matching products with handle, title, price and collections.",
      "items": {
        "type": "object",
        "description": "A product.",
        "properties": {
          "handle": {
            "type": "string",
            "description": "product_handle for ask.items."
          },
          "title": {
            "type": "string",
            "description": "Product title."
          },
          "url": {
            "type": "string",
            "description": "Product page."
          }
        }
      }
    },
    "total_matches": {
      "type": "integer",
      "description": "Store catalog: number of matching products."
    },
    "collections": {
      "type": "array",
      "description": "Store catalog: collections to filter by."
    },
    "variants": {
      "type": "array",
      "description": "Campaign catalog: eligible variants with a variant_id.",
      "items": {
        "type": "object",
        "description": "A variant.",
        "properties": {
          "variant_id": {
            "type": "string",
            "description": "variant_id for ask.items."
          },
          "title": {
            "type": "string",
            "description": "Product title."
          },
          "price_minor": {
            "type": "integer",
            "description": "Price in minor units."
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 currency."
          }
        }
      }
    },
    "approved_combinations": {
      "type": "array",
      "description": "Campaign catalog: approved combinations with a recipe_id for ask.recipe_id."
    },
    "how_to_ask": {
      "type": "string",
      "description": "How to name these products in haggl_submit_offer."
    },
    "error": {
      "type": "string",
      "description": "Present only when the call failed: what went wrong."
    },
    "code": {
      "type": "string",
      "description": "Present only when the call failed: a machine-readable error code, e.g. quote_uncertain or rate_limited."
    },
    "recovery": {
      "type": "object",
      "description": "When the outcome is uncertain: the tool and session_id to read before retrying.",
      "properties": {}
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the same call may be retried."
    },
    "retry_after_seconds": {
      "type": "integer",
      "description": "When rate limited: seconds to wait before retrying."
    }
  }
}

Read the canonical state, current offer version, guidance and permitted actions of an existing negotiation. Use after human changes, reloads, transport switches or uncertain results; this does not open another session.

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "description": "Existing negotiation session id."
    }
  },
  "required": [
    "session_id"
  ]
}

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "description": "Negotiation session id."
    },
    "vendor_id": {
      "type": "string",
      "description": "Vendor id."
    },
    "status": {
      "type": "string",
      "description": "Session status."
    },
    "state": {
      "type": "object",
      "description": "Canonical negotiation state. Follow allowed_actions.",
      "properties": {
        "status": {
          "type": "string",
          "description": "open, offered, final, reserved, accepted, expired, rejected, unavailable or merchant_action_required."
        },
        "allowed_actions": {
          "type": "array",
          "description": "The actions permitted now.",
          "items": {
            "type": "string"
          }
        },
        "offer_version": {
          "type": "integer",
          "description": "The current offer version; acceptance names the version the buyer approved."
        },
        "finality_reason": {
          "type": [
            "string",
            "null"
          ],
          "description": "Why no further offer will come, when final."
        },
        "offer_expires_at": {
          "type": "string",
          "description": "ISO 8601 time the current offer expires."
        },
        "commits_purchase": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Whether acceptance itself commits a purchase (never true: payment happens at the merchant)."
        },
        "acceptance_requires_user_approval": {
          "type": "boolean",
          "description": "Always true: accept only an offer the buyer approved."
        },
        "acceptance_effects": {
          "type": "array",
          "description": "What acceptance does, e.g. issues a coupon or a checkout link.",
          "items": {
            "type": "string"
          }
        },
        "merchant_assistance": {
          "type": [
            "object",
            "null"
          ],
          "description": "When status is merchant_action_required: what to tell the buyer.",
          "properties": {
            "message": {
              "description": "What to tell the buyer."
            },
            "contact_email": {
              "description": "Where the buyer can reach the merchant."
            },
            "reference": {
              "description": "The reference to quote."
            }
          }
        }
      }
    },
    "current_offer": {
      "type": [
        "object",
        "null"
      ],
      "description": "The merchant's offer for the requested items. Merchant engines may add fields.",
      "properties": {
        "vendor": {
          "description": "The seller, to show the buyer before acceptance."
        },
        "discount_pct": {
          "description": "Discount in percent."
        },
        "currency": {
          "description": "ISO 4217 currency."
        },
        "applies_to": {
          "description": "The items and quantities the discount covers, and any exclusions."
        },
        "note": {
          "description": "The sales agent's note to the buyer."
        },
        "valid_until": {
          "description": "ISO 8601 time the offer expires."
        },
        "personalized_price_notice": {
          "description": "Show this to the buyer word for word with the offer."
        }
      }
    },
    "guidance": {
      "type": [
        "object",
        "null"
      ],
      "description": "What this merchant values, as contextual guidance. Evidence is optional.",
      "properties": {}
    },
    "context_received": {
      "type": "object",
      "description": "The buyer context fields received so far and their provenance.",
      "properties": {}
    },
    "max_rounds": {
      "type": "integer",
      "description": "Most quote rounds in this session."
    },
    "current_round": {
      "type": "integer",
      "description": "Rounds used."
    },
    "rounds_remaining": {
      "type": "integer",
      "description": "Rounds left."
    },
    "rounds": {
      "type": "array",
      "description": "Each round: the offer and when it was made."
    },
    "accepted_offer": {
      "type": [
        "object",
        "null"
      ],
      "description": "The merchant's offer for the requested items. Merchant engines may add fields.",
      "properties": {
        "vendor": {
          "description": "The seller, to show the buyer before acceptance."
        },
        "discount_pct": {
          "description": "Discount in percent."
        },
        "currency": {
          "description": "ISO 4217 currency."
        },
        "applies_to": {
          "description": "The items and quantities the discount covers, and any exclusions."
        },
        "note": {
          "description": "The sales agent's note to the buyer."
        },
        "valid_until": {
          "description": "ISO 8601 time the offer expires."
        },
        "personalized_price_notice": {
          "description": "Show this to the buyer word for word with the offer."
        }
      }
    },
    "next_steps": {
      "type": "object",
      "description": "After acceptance: how the buyer redeems the offer (checkout_url, coupon_code, reference, expires_at, …).",
      "properties": {}
    },
    "expires_at": {
      "type": "string",
      "description": "ISO 8601 time the session expires."
    },
    "created_at": {
      "type": "string",
      "description": "ISO 8601 time the session started."
    },
    "error": {
      "type": "string",
      "description": "Present only when the call failed: what went wrong."
    },
    "code": {
      "type": "string",
      "description": "Present only when the call failed: a machine-readable error code, e.g. quote_uncertain or rate_limited."
    },
    "recovery": {
      "type": "object",
      "description": "When the outcome is uncertain: the tool and session_id to read before retrying.",
      "properties": {}
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the same call may be retried."
    },
    "retry_after_seconds": {
      "type": "integer",
      "description": "When rate limited: seconds to wait before retrying."
    }
  }
}

Request a quote using all context already available. Buyer data and evidence can be omitted; relevant additional context can be supplied later within the remaining rounds. Returns authorized terms or no offer, contextual guidance and permitted next actions.

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "description": "Session id from haggl_start_negotiation or session.id from REST initialization."
    },
    "expected_offer_version": {
      "type": "integer",
      "minimum": 0,
      "description": "Optional state.offer_version last read, to avoid submitting against a session changed by another actor."
    },
    "data": {
      "type": "object",
      "description": "Optional buyer context and consented evidence. Omit or use {} for an opening quote without evidence."
    },
    "ask": {
      "type": "object",
      "description": "What the buyer wants; the offer then says exactly which items the discount covers. Store catalogs: { items: [{ product_handle, quantity }] }. Campaign catalogs (catalog.type \"campaign\"): { items: [{ variant_id, quantity }] } or { recipe_id }, required for a campaign offer. Otherwise describe the product or service, e.g. { product }."
    }
  },
  "required": [
    "session_id"
  ]
}

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "description": "Negotiation session id."
    },
    "vendor_id": {
      "type": "string",
      "description": "Vendor id."
    },
    "status": {
      "type": "string",
      "description": "Session status."
    },
    "state": {
      "type": "object",
      "description": "Canonical negotiation state. Follow allowed_actions.",
      "properties": {
        "status": {
          "type": "string",
          "description": "open, offered, final, reserved, accepted, expired, rejected, unavailable or merchant_action_required."
        },
        "allowed_actions": {
          "type": "array",
          "description": "The actions permitted now.",
          "items": {
            "type": "string"
          }
        },
        "offer_version": {
          "type": "integer",
          "description": "The current offer version; acceptance names the version the buyer approved."
        },
        "finality_reason": {
          "type": [
            "string",
            "null"
          ],
          "description": "Why no further offer will come, when final."
        },
        "offer_expires_at": {
          "type": "string",
          "description": "ISO 8601 time the current offer expires."
        },
        "commits_purchase": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Whether acceptance itself commits a purchase (never true: payment happens at the merchant)."
        },
        "acceptance_requires_user_approval": {
          "type": "boolean",
          "description": "Always true: accept only an offer the buyer approved."
        },
        "acceptance_effects": {
          "type": "array",
          "description": "What acceptance does, e.g. issues a coupon or a checkout link.",
          "items": {
            "type": "string"
          }
        },
        "merchant_assistance": {
          "type": [
            "object",
            "null"
          ],
          "description": "When status is merchant_action_required: what to tell the buyer.",
          "properties": {
            "message": {
              "description": "What to tell the buyer."
            },
            "contact_email": {
              "description": "Where the buyer can reach the merchant."
            },
            "reference": {
              "description": "The reference to quote."
            }
          }
        }
      }
    },
    "current_offer": {
      "type": [
        "object",
        "null"
      ],
      "description": "The merchant's offer for the requested items. Merchant engines may add fields.",
      "properties": {
        "vendor": {
          "description": "The seller, to show the buyer before acceptance."
        },
        "discount_pct": {
          "description": "Discount in percent."
        },
        "currency": {
          "description": "ISO 4217 currency."
        },
        "applies_to": {
          "description": "The items and quantities the discount covers, and any exclusions."
        },
        "note": {
          "description": "The sales agent's note to the buyer."
        },
        "valid_until": {
          "description": "ISO 8601 time the offer expires."
        },
        "personalized_price_notice": {
          "description": "Show this to the buyer word for word with the offer."
        }
      }
    },
    "guidance": {
      "type": [
        "object",
        "null"
      ],
      "description": "What this merchant values, as contextual guidance. Evidence is optional.",
      "properties": {}
    },
    "context_received": {
      "type": "object",
      "description": "The buyer context fields received so far and their provenance.",
      "properties": {}
    },
    "max_rounds": {
      "type": "integer",
      "description": "Most quote rounds in this session."
    },
    "current_round": {
      "type": "integer",
      "description": "Rounds used."
    },
    "rounds_remaining": {
      "type": "integer",
      "description": "Rounds left."
    },
    "rounds": {
      "type": "array",
      "description": "Each round: the offer and when it was made."
    },
    "accepted_offer": {
      "type": [
        "object",
        "null"
      ],
      "description": "The merchant's offer for the requested items. Merchant engines may add fields.",
      "properties": {
        "vendor": {
          "description": "The seller, to show the buyer before acceptance."
        },
        "discount_pct": {
          "description": "Discount in percent."
        },
        "currency": {
          "description": "ISO 4217 currency."
        },
        "applies_to": {
          "description": "The items and quantities the discount covers, and any exclusions."
        },
        "note": {
          "description": "The sales agent's note to the buyer."
        },
        "valid_until": {
          "description": "ISO 8601 time the offer expires."
        },
        "personalized_price_notice": {
          "description": "Show this to the buyer word for word with the offer."
        }
      }
    },
    "next_steps": {
      "type": "object",
      "description": "After acceptance: how the buyer redeems the offer (checkout_url, coupon_code, reference, expires_at, …).",
      "properties": {}
    },
    "expires_at": {
      "type": "string",
      "description": "ISO 8601 time the session expires."
    },
    "created_at": {
      "type": "string",
      "description": "ISO 8601 time the session started."
    },
    "round": {
      "type": "integer",
      "description": "The round this quote answered."
    },
    "offer": {
      "type": "object",
      "description": "The merchant's offer for the requested items. Merchant engines may add fields.",
      "properties": {
        "vendor": {
          "description": "The seller, to show the buyer before acceptance."
        },
        "discount_pct": {
          "description": "Discount in percent."
        },
        "currency": {
          "description": "ISO 4217 currency."
        },
        "applies_to": {
          "description": "The items and quantities the discount covers, and any exclusions."
        },
        "note": {
          "description": "The sales agent's note to the buyer."
        },
        "valid_until": {
          "description": "ISO 8601 time the offer expires."
        },
        "personalized_price_notice": {
          "description": "Show this to the buyer word for word with the offer."
        }
      }
    },
    "data_feedback": {
      "type": "object",
      "description": "Which context fields were used, and which could improve the offer.",
      "properties": {}
    },
    "error": {
      "type": "string",
      "description": "Present only when the call failed: what went wrong."
    },
    "code": {
      "type": "string",
      "description": "Present only when the call failed: a machine-readable error code, e.g. quote_uncertain or rate_limited."
    },
    "recovery": {
      "type": "object",
      "description": "When the outcome is uncertain: the tool and session_id to read before retrying.",
      "properties": {}
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the same call may be retried."
    },
    "retry_after_seconds": {
      "type": "integer",
      "description": "When rate limited: seconds to wait before retrying."
    }
  }
}

Accept the vendor's offer and lock in the deal. Consequential: only call after the buyer has approved this exact offer, every time. Provide the offer version the buyer reviewed and approved; a changed offer needs a new approval. Read state.acceptance_effects and state.commits_purchase first: merchant handoff effects may be unknown. haggl.ai never takes payment: any payment happens at the merchant's checkout, under the merchant's terms and refund policy. A returned checkout link alone does not establish payment or enrollment completion. Accepting the same offer version again returns the same result.

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "description": "Session id of the negotiation to accept."
    },
    "expected_offer_version": {
      "type": "integer",
      "minimum": 1,
      "description": "state.offer_version from the quote reviewed and approved by the buyer."
    },
    "round": {
      "type": "integer",
      "minimum": 1,
      "description": "Legacy offer round. If supplied it must match the current or already reserved offer."
    }
  },
  "required": [
    "session_id",
    "expected_offer_version"
  ]
}

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "description": "Negotiation session id."
    },
    "vendor_id": {
      "type": "string",
      "description": "Vendor id."
    },
    "status": {
      "type": "string",
      "description": "Session status."
    },
    "state": {
      "type": "object",
      "description": "Canonical negotiation state. Follow allowed_actions.",
      "properties": {
        "status": {
          "type": "string",
          "description": "open, offered, final, reserved, accepted, expired, rejected, unavailable or merchant_action_required."
        },
        "allowed_actions": {
          "type": "array",
          "description": "The actions permitted now.",
          "items": {
            "type": "string"
          }
        },
        "offer_version": {
          "type": "integer",
          "description": "The current offer version; acceptance names the version the buyer approved."
        },
        "finality_reason": {
          "type": [
            "string",
            "null"
          ],
          "description": "Why no further offer will come, when final."
        },
        "offer_expires_at": {
          "type": "string",
          "description": "ISO 8601 time the current offer expires."
        },
        "commits_purchase": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Whether acceptance itself commits a purchase (never true: payment happens at the merchant)."
        },
        "acceptance_requires_user_approval": {
          "type": "boolean",
          "description": "Always true: accept only an offer the buyer approved."
        },
        "acceptance_effects": {
          "type": "array",
          "description": "What acceptance does, e.g. issues a coupon or a checkout link.",
          "items": {
            "type": "string"
          }
        },
        "merchant_assistance": {
          "type": [
            "object",
            "null"
          ],
          "description": "When status is merchant_action_required: what to tell the buyer.",
          "properties": {
            "message": {
              "description": "What to tell the buyer."
            },
            "contact_email": {
              "description": "Where the buyer can reach the merchant."
            },
            "reference": {
              "description": "The reference to quote."
            }
          }
        }
      }
    },
    "current_offer": {
      "type": [
        "object",
        "null"
      ],
      "description": "The merchant's offer for the requested items. Merchant engines may add fields.",
      "properties": {
        "vendor": {
          "description": "The seller, to show the buyer before acceptance."
        },
        "discount_pct": {
          "description": "Discount in percent."
        },
        "currency": {
          "description": "ISO 4217 currency."
        },
        "applies_to": {
          "description": "The items and quantities the discount covers, and any exclusions."
        },
        "note": {
          "description": "The sales agent's note to the buyer."
        },
        "valid_until": {
          "description": "ISO 8601 time the offer expires."
        },
        "personalized_price_notice": {
          "description": "Show this to the buyer word for word with the offer."
        }
      }
    },
    "guidance": {
      "type": [
        "object",
        "null"
      ],
      "description": "What this merchant values, as contextual guidance. Evidence is optional.",
      "properties": {}
    },
    "context_received": {
      "type": "object",
      "description": "The buyer context fields received so far and their provenance.",
      "properties": {}
    },
    "max_rounds": {
      "type": "integer",
      "description": "Most quote rounds in this session."
    },
    "current_round": {
      "type": "integer",
      "description": "Rounds used."
    },
    "rounds_remaining": {
      "type": "integer",
      "description": "Rounds left."
    },
    "rounds": {
      "type": "array",
      "description": "Each round: the offer and when it was made."
    },
    "accepted_offer": {
      "type": [
        "object",
        "null"
      ],
      "description": "The merchant's offer for the requested items. Merchant engines may add fields.",
      "properties": {
        "vendor": {
          "description": "The seller, to show the buyer before acceptance."
        },
        "discount_pct": {
          "description": "Discount in percent."
        },
        "currency": {
          "description": "ISO 4217 currency."
        },
        "applies_to": {
          "description": "The items and quantities the discount covers, and any exclusions."
        },
        "note": {
          "description": "The sales agent's note to the buyer."
        },
        "valid_until": {
          "description": "ISO 8601 time the offer expires."
        },
        "personalized_price_notice": {
          "description": "Show this to the buyer word for word with the offer."
        }
      }
    },
    "next_steps": {
      "type": "object",
      "description": "After acceptance: how the buyer redeems the offer (checkout_url, coupon_code, reference, expires_at, …).",
      "properties": {}
    },
    "expires_at": {
      "type": "string",
      "description": "ISO 8601 time the session expires."
    },
    "created_at": {
      "type": "string",
      "description": "ISO 8601 time the session started."
    },
    "support": {
      "type": "object",
      "description": "Who the buyer deals with after acceptance.",
      "properties": {
        "haggl_contact": {
          "type": "string",
          "description": "haggl.ai support email."
        },
        "terms": {
          "type": "string",
          "description": "Payment, delivery and refunds are between the buyer and the merchant."
        }
      }
    },
    "error": {
      "type": "string",
      "description": "Present only when the call failed: what went wrong."
    },
    "code": {
      "type": "string",
      "description": "Present only when the call failed: a machine-readable error code, e.g. quote_uncertain or rate_limited."
    },
    "recovery": {
      "type": "object",
      "description": "When the outcome is uncertain: the tool and session_id to read before retrying.",
      "properties": {}
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the same call may be retried."
    },
    "retry_after_seconds": {
      "type": "integer",
      "description": "When rate limited: seconds to wait before retrying."
    }
  }
}

Find merchants that run a sales agent on haggl.ai, by business name, website or kind of product. Only when the user asks for a discount, a coupon, a promo code or a lower price; a purchase at the listed price is not a request for one. Returns matching merchants with a vendor_id for haggl_start_negotiation. Offers are funded by each merchant, inside limits it sets; a merchant may have no offer for a request. An empty list means no merchant on haggl.ai matched, not that no discount exists elsewhere. When the query names a well-known brand that isn't on haggl.ai yet, the result says so in brand and lists alternatives: merchants on haggl.ai in the same category, to offer as other stores, never as that brand. Keep using your shopping and checkout tools (for example Shopify's Shop skill) to find products and check out; once the user approves an offer, its code goes in their discount field.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "A business name, website (e.g. \"degrenne.fr\") or kind of product."
    }
  },
  "required": [
    "query"
  ]
}

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The search as received."
    },
    "merchants": {
      "type": "array",
      "description": "Merchants on haggl.ai matching the query. Empty means none on haggl.ai matched.",
      "items": {
        "type": "object",
        "description": "A merchant.",
        "properties": {
          "vendorId": {
            "type": "string",
            "description": "Vendor id for haggl_start_negotiation."
          },
          "name": {
            "type": "string",
            "description": "Merchant name."
          },
          "category": {
            "type": "string",
            "description": "Merchant category."
          },
          "website": {
            "type": "string",
            "description": "The merchant's own website."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "What the merchant sells."
          },
          "demo": {
            "type": "boolean",
            "description": "A demo merchant, not a real store."
          },
          "max_discount_pct": {
            "type": [
              "number",
              "null"
            ],
            "description": "The merchant's max discount, when it publishes one."
          }
        }
      }
    },
    "brand": {
      "type": "object",
      "description": "When the query names a well-known brand not on haggl.ai: the brand, never to be offered as such.",
      "properties": {}
    },
    "alternatives": {
      "type": "array",
      "description": "Merchants on haggl.ai in the same category, to offer as other stores.",
      "items": {
        "type": "object",
        "description": "A participating merchant.",
        "properties": {
          "vendorId": {
            "type": "string",
            "description": "Vendor id for haggl_start_negotiation."
          },
          "name": {
            "type": "string",
            "description": "Merchant name."
          },
          "category": {
            "type": "string",
            "description": "Merchant category."
          },
          "website": {
            "type": "string",
            "description": "The merchant's own website."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "What the merchant sells."
          }
        }
      }
    },
    "bids": {
      "type": "object",
      "description": "When the category supports bids: how to get them with haggl_get_bids.",
      "properties": {}
    },
    "how_it_works": {
      "type": "array",
      "description": "The flow, step by step.",
      "items": {
        "type": "string"
      }
    },
    "error": {
      "type": "string",
      "description": "Present only when the call failed: what went wrong."
    },
    "code": {
      "type": "string",
      "description": "Present only when the call failed: a machine-readable error code, e.g. quote_uncertain or rate_limited."
    },
    "recovery": {
      "type": "object",
      "description": "When the outcome is uncertain: the tool and session_id to read before retrying.",
      "properties": {}
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the same call may be retried."
    },
    "retry_after_seconds": {
      "type": "integer",
      "description": "When rate limited: seconds to wait before retrying."
    }
  }
}

Create a haggl ID for the user, so offers and codes from different merchants stay together and can be read back later. Show the user this text first, and call this only if they agree: "haggl.ai, operated by MOOJO.ID, INC. ("we"), offers your agent a haggl ID. You can decline: your agent can still ask merchants for offers without one. If you agree, we link the negotiations your agent opens with the ID and keep a record of them: when the ID was created, how many distinct emails passed our signature check and how many distinct domains signed them, the date of the latest check, how many merchants were asked, how many offers were received and accepted, and how many paid orders we recorded. For each shopping category, such as travel, the record also counts how many of those emails, and how many distinct businesses that signed them, were in it; health purchases are never counted. The record does not include those domains, the businesses' names or any email content. We store a fingerprint of the ID, not the ID itself. We do not require your name or email address to create a haggl ID. We keep limited evidence of your agreement, as described in our privacy policy. You choose whether your agent uses the haggl ID. Using it authorizes us to share the record with the sales agent of each merchant your agent asks for an offer, to help assess eligibility and personalize offer terms. When your agent asks the merchants in a category for bids, we ask up to five of them on your behalf and share the record with each of their sales agents. Merchants never see the ID itself. You separately choose what information your agent submits during each negotiation. Keep the ID private: anyone who has it can retrieve the record, offers and codes, and delete the ID. You can withdraw consent by deleting the ID through your agent or on haggl.ai/agentic-discounts. This removes the stored fingerprint and the record and unlinks its negotiations. The negotiations themselves remain subject to the separate retention and deletion rules in our privacy policy (https://www.haggl.ai/privacy). Your haggl ID expires 12 months after your agent last uses it to ask a merchant for an offer. It cannot be used or renewed after expiry and is then automatically deleted, usually within a day." If they decline, go on without a haggl ID. Send consent_version "2026-10-16.4" and statement: the user's words of agreement, quoted, without names or contact details. If the user is not in this conversation to read the text but their own standing instructions to you say they agree to this consent version, send channel "standing_instruction" with those words as the statement; otherwise use haggl_request_haggl_id_confirmation instead, then call this with its confirmation once they confirmed. The ID is returned once: keep it with the user's settings, and never share it with anyone else.

{
  "type": "object",
  "properties": {
    "consent_version": {
      "type": "string",
      "description": "The consent text version the user agreed to: \"2026-10-16.4\"."
    },
    "statement": {
      "type": "string",
      "maxLength": 200,
      "description": "The user's words of agreement, quoted (for example \"Yes, I agree\"); no names, emails or phone numbers."
    },
    "channel": {
      "type": "string",
      "enum": [
        "agent_relayed",
        "standing_instruction"
      ],
      "description": "How the user agreed: in this conversation (agent_relayed, the default), or in standing instructions they wrote to you beforehand (standing_instruction)."
    },
    "confirmation": {
      "type": "string",
      "description": "Instead of consent_version and statement: the confirmation from haggl_request_haggl_id_confirmation, after the user confirmed at its confirm_url."
    }
  }
}

{
  "type": "object",
  "properties": {
    "haggl_id": {
      "type": "string",
      "description": "The user's haggl ID. Returned once: keep it private with the user's settings."
    },
    "created_at": {
      "type": "string",
      "description": "ISO 8601 creation time."
    },
    "consent_version": {
      "type": "string",
      "description": "The consent text version agreed to."
    },
    "keep_it": {
      "type": "string",
      "description": "How to keep the ID."
    },
    "use_it": {
      "type": "string",
      "description": "How to use the ID."
    },
    "error": {
      "type": "string",
      "description": "Present only when the call failed: what went wrong."
    },
    "code": {
      "type": "string",
      "description": "Present only when the call failed: a machine-readable error code, e.g. quote_uncertain or rate_limited."
    },
    "recovery": {
      "type": "object",
      "description": "When the outcome is uncertain: the tool and session_id to read before retrying.",
      "properties": {}
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the same call may be retried."
    },
    "retry_after_seconds": {
      "type": "integer",
      "description": "When rate limited: seconds to wait before retrying."
    }
  }
}

Get a link for the user to read the haggl ID consent text and confirm it on haggl.ai, when they are not in this conversation to agree to it. Send them confirm_url (valid 30 minutes). After they confirm, call haggl_create_haggl_id with the returned confirmation; until then it answers confirmation_pending.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "confirmation": {
      "type": "string",
      "description": "Pass to haggl_create_haggl_id once the user confirmed."
    },
    "confirm_url": {
      "type": "string",
      "description": "Send this link to the user."
    },
    "expires_at": {
      "type": "string",
      "description": "ISO 8601 expiry (30 minutes)."
    },
    "next": {
      "type": "string",
      "description": "What to do next."
    },
    "error": {
      "type": "string",
      "description": "Present only when the call failed: what went wrong."
    },
    "code": {
      "type": "string",
      "description": "Present only when the call failed: a machine-readable error code, e.g. quote_uncertain or rate_limited."
    },
    "recovery": {
      "type": "object",
      "description": "When the outcome is uncertain: the tool and session_id to read before retrying.",
      "properties": {}
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the same call may be retried."
    },
    "retry_after_seconds": {
      "type": "integer",
      "description": "When rate limited: seconds to wait before retrying."
    }
  }
}

Read what haggl.ai holds for the user's haggl ID: when it was created and the negotiations, offers and codes linked to it, newest first.

{
  "type": "object",
  "properties": {
    "haggl_id": {
      "type": "string",
      "description": "The user's haggl ID."
    }
  },
  "required": [
    "haggl_id"
  ]
}

{
  "type": "object",
  "properties": {
    "created_at": {
      "type": "string",
      "description": "ISO 8601 time the haggl ID was created."
    },
    "last_used_at": {
      "type": "string",
      "description": "ISO 8601 time it was last used."
    },
    "consent": {
      "type": "object",
      "description": "The consent on record: version, time and channel.",
      "properties": {}
    },
    "offers": {
      "type": "array",
      "description": "Negotiations linked to this haggl ID, newest first.",
      "items": {
        "type": "object",
        "description": "A negotiation.",
        "properties": {
          "session_id": {
            "type": "string",
            "description": "Session id."
          },
          "vendor_id": {
            "type": "string",
            "description": "Vendor id."
          },
          "status": {
            "type": "string",
            "description": "Session status."
          },
          "started_at": {
            "type": "string",
            "description": "ISO 8601 start time."
          },
          "discount_pct": {
            "type": [
              "number",
              "null"
            ],
            "description": "Discount offered, in percent."
          },
          "coupon": {
            "type": [
              "object",
              "null"
            ],
            "description": "The code issued for an accepted offer.",
            "properties": {
              "code": {
                "type": "string",
                "description": "Discount code for the merchant checkout."
              },
              "url": {
                "type": "string",
                "description": "Link that applies the code."
              },
              "expires_at": {
                "type": "string",
                "description": "ISO 8601 expiry."
              }
            }
          }
        }
      }
    },
    "record": {
      "type": [
        "object",
        "null"
      ],
      "description": "What the record holds: verified purchases by category and offer counts.",
      "properties": {}
    },
    "error": {
      "type": "string",
      "description": "Present only when the call failed: what went wrong."
    },
    "code": {
      "type": "string",
      "description": "Present only when the call failed: a machine-readable error code, e.g. quote_uncertain or rate_limited."
    },
    "recovery": {
      "type": "object",
      "description": "When the outcome is uncertain: the tool and session_id to read before retrying.",
      "properties": {}
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the same call may be retried."
    },
    "retry_after_seconds": {
      "type": "integer",
      "description": "When rate limited: seconds to wait before retrying."
    }
  }
}

Have the merchants on haggl.ai in one shopping category (for example travel) bid for the user at once, from their haggl ID record, without new proof. Works once the record holds a verified purchase in that category (from an earlier offer with signed email proof); otherwise it says so and returns no bids. Each bid is a merchant's own offer, funded by the merchant, with an accept_url; show the user each one with its personalized_price_notice, and accept only with their approval.

{
  "type": "object",
  "properties": {
    "haggl_id": {
      "type": "string",
      "description": "The user's haggl ID."
    },
    "query": {
      "type": "string",
      "description": "What the user is after, e.g. \"hotel in Barcelona, 4 nights in December\". Sets the category when category is omitted."
    },
    "category": {
      "type": "string",
      "description": "Optional: the brand index category, e.g. \"travel\"."
    }
  },
  "required": [
    "haggl_id"
  ]
}

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "description": "The shopping category."
    },
    "label": {
      "type": "string",
      "description": "Category name."
    },
    "unlocked": {
      "type": "boolean",
      "description": "Whether the record holds a verified purchase in this category; when false, bids is empty."
    },
    "bids": {
      "type": "array",
      "description": "Merchants' offers. Show each with its personalized_price_notice; accept only with the user's approval.",
      "items": {
        "type": "object",
        "description": "A bid.",
        "properties": {
          "vendor_id": {
            "type": "string",
            "description": "Vendor id."
          },
          "merchant": {
            "type": "string",
            "description": "Merchant name."
          },
          "discount_pct": {
            "type": [
              "number",
              "null"
            ],
            "description": "Discount in percent."
          },
          "personalized_price_notice": {
            "type": "string",
            "description": "Show word for word."
          },
          "session_id": {
            "type": "string",
            "description": "Session id of this offer."
          },
          "offer_version": {
            "type": "integer",
            "description": "Offer version to accept."
          },
          "accept_url": {
            "type": "string",
            "description": "Where to accept, once the user approves."
          }
        }
      }
    },
    "note": {
      "type": "string",
      "description": "Why there are no bids, when locked."
    },
    "how_it_works": {
      "type": "array",
      "description": "The flow, step by step.",
      "items": {
        "type": "string"
      }
    },
    "error": {
      "type": "string",
      "description": "Present only when the call failed: what went wrong."
    },
    "code": {
      "type": "string",
      "description": "Present only when the call failed: a machine-readable error code, e.g. quote_uncertain or rate_limited."
    },
    "recovery": {
      "type": "object",
      "description": "When the outcome is uncertain: the tool and session_id to read before retrying.",
      "properties": {}
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the same call may be retried."
    },
    "retry_after_seconds": {
      "type": "integer",
      "description": "When rate limited: seconds to wait before retrying."
    }
  }
}

Delete the user's haggl ID and unlink the offers linked to it. Only when the user asks. Codes already issued keep working at the merchant until they expire.

{
  "type": "object",
  "properties": {
    "haggl_id": {
      "type": "string",
      "description": "The user's haggl ID."
    }
  },
  "required": [
    "haggl_id"
  ]
}

{
  "type": "object",
  "properties": {
    "deleted": {
      "type": "boolean",
      "description": "True once the haggl ID is deleted."
    },
    "offers_unlinked": {
      "type": "integer",
      "description": "How many offers were unlinked."
    },
    "error": {
      "type": "string",
      "description": "Present only when the call failed: what went wrong."
    },
    "code": {
      "type": "string",
      "description": "Present only when the call failed: a machine-readable error code, e.g. quote_uncertain or rate_limited."
    },
    "recovery": {
      "type": "object",
      "description": "When the outcome is uncertain: the tool and session_id to read before retrying.",
      "properties": {}
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the same call may be retried."
    },
    "retry_after_seconds": {
      "type": "integer",
      "description": "When rate limited: seconds to wait before retrying."
    }
  }
}