# Get offer details

Read a listing’s purchase URL, seller, price, coupon terms and stated product information.

## What this endpoint does

Endpoint

```
POST https://mcp.gaisho.co/v1/tools/get_offer
```

Inspect the actual listing the shopper may buy. Use it to connect a price to the right seller and purchase URL, and to read what that listing says about specifications, package contents, coupon conditions and purchase terms.

- Check which seller and URL belong to an offer in a product shortlist.
- Investigate warranty, dimensions, ingredients or included accessories.
- Read available shipping and return information before recommending a listing.

## Before you call

- Supply offer_ids returned by search_products, get_product or find_deals. A product ID is not a substitute for an offer ID.
- Request one to eight listings per call. Keep the IDs and their originating products together in your application.
- Some find_deals options have a purchase URL but no stored offer_id. Do not invent an ID for those options; follow the returned URL.

Send a JSON object as the request body and authenticate with Authorization: Bearer <API key>. Amounts are in USD unless the result explicitly says otherwise.

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| offer_ids | string[] | Required | Offer IDs returned by search, product details or comparisons. 1–8 items. |

## Example request

Set GAISHO_API_KEY in your server or local environment. These examples use a JSON POST request; Python uses the standard library and JavaScript uses Node.js fetch. The 60-second client timeout in Python and JavaScript is configurable, not a service latency guarantee.

cURL

```
curl --fail-with-body 'https://mcp.gaisho.co/v1/tools/get_offer' \
  -H "Authorization: Bearer $GAISHO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "offer_ids": [
    "OFFER_ID_FROM_SEARCH"
  ]
}'
```

Python

```
import json
import os
import urllib.error
import urllib.request

arguments = json.loads(r'''{
  "offer_ids": [
    "OFFER_ID_FROM_SEARCH"
  ]
}''')
request = urllib.request.Request(
    "https://mcp.gaisho.co/v1/tools/get_offer",
    data=json.dumps(arguments).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + os.environ["GAISHO_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=60) as response:
        payload = json.load(response)
    print(json.dumps(payload, indent=2))
except urllib.error.HTTPError as error:
    print(error.read().decode("utf-8"))
    raise
```

JavaScript

```
// Node.js 18+; keep this code and the key on your server.
const response = await fetch("https://mcp.gaisho.co/v1/tools/get_offer", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GAISHO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "offer_ids": [
    "OFFER_ID_FROM_SEARCH"
  ]
}),
  signal: AbortSignal.timeout(60_000),
});
const body = await response.text();
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${body}`);
}
const payload = JSON.parse(body);
console.log(payload);
```

## Common request patterns

### Inspect two purchase options

Each entry identifies an individual listing, even if both sell the same product.

JSON request body

```
{
  "offer_ids": [
    "OFFER_ID_FROM_SEARCH",
    "SECOND_OFFER_ID_FROM_SEARCH"
  ]
}
```

## Response fields

The HTTP response contains tool and summary. Product information is carried in summary text; there is no separate structured result array. Treat its wording as readable content, not a fixed column schema.

| Field | Type | Description |
| --- | --- | --- |
| tool | string | The tool called: get_offer. |
| summary | string | Details of the requested listings, including purchase links and seller information. |

## Example response

Examples are illustrative and may omit optional detail fields. Prices are not live quotes; identifiers and example.com URLs are placeholders to replace, not usable product records.

HTTP 200 · illustrative, shortened

```
{
  "tool": "get_offer",
  "summary": "Offer: OFFER_ID_FROM_SEARCH\nExample cordless vacuum — $179.99\nSeller: Example Store\nPurchase link: https://example.com/vacuum\nListing states: one vacuum, charger and crevice tool.\nReturns: see the retailer’s stated terms."
}
```

## How to read the result

- summary is a text report about the requested listings. It contains the available purchase, seller and listing details rather than a separate offers array.
- Coupon conditions belong to a specific offer. Check eligibility and whether a discount is already included before using the quoted amount.
- A listing may omit shipping, warranty or return details. Missing information does not establish free shipping, a warranty or a right to return.

## Empty results and errors

| Situation | How to handle it |
| --- | --- |
| An offer ID is unknown | Use an ID returned by a current search or product-detail response; do not send a model name in offer_ids. |
| Price or availability has changed | Use the details returned for that listing and confirm the retailer’s final checkout terms. |
| You need a seller assessment | Pass the seller identifier or seller URL to vet_seller; product ratings are not seller ratings. |

A successful request can return no candidates, missing information or an unavailable assessment. Check the result before recommending a product. For request failures, use the error code and message; retrying the same invalid input will not fix it.

- [Error handling and retries](https://gaisho.co/docs/api#errors): HTTP statuses, structured errors, rate limits and quota responses.

## What to call next

- [Check a seller](https://gaisho.co/docs/api/vet_seller): Assess a seller or online store and return a trust assessment with supporting facts.
- [Check a price](https://gaisho.co/docs/api/vet_price): Assess whether a USD price is reasonable for a stated product or shopping requirement.

- [Use this tool through MCP](https://gaisho.co/docs/mcp/get_offer): The same capability through the other connection.
- [REST API conventions](https://gaisho.co/docs/api): Authentication, response envelopes and request handling.