> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guppyapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Examples

> How partners use Guppy for multi-merchant purchases, reservations, appointments, and procurement

This page shows practical, end-to-end examples of how a partner would integrate Guppy for various workflows.

Each example follows the same pattern:

* Create an intent with **objective + conditions + guardrails**
* Listen for **events** (webhook)
* If needed, handle **user action required**
* Read the **result** (and optionally fetch **receipt/proof**)

***

## Example 1: Buy an item across retailers (below price by date)

Goal: “Buy PS5 Pro if it’s in stock at Target/BestBuy/Walmart for under \$800, any time before Feb 1.”

### Step 1 - Resolve product (no URLs)

```bash theme={null}
POST /resolve/products
Authorization: Bearer GUPPY_SECRET_KEY
Content-Type: application/json
```

```json theme={null}
{
  "query": "PS5 Pro",
  "allowed_merchants": ["target", "bestbuy", "walmart"],
  "limit": 5
}
```

Pick a `product_id` from the returned candidates (optionally confirm with the user).

### Step 2 - Create intent

```bash theme={null}
POST /intents
Authorization: Bearer GUPPY_SECRET_KEY
Content-Type: application/json
Idempotency-Key: buy_user123_ps5pro_under800_before_2026-02-01
```

```json theme={null}
{
  "external_user_id": "user_123",
  "type": "purchase",
  "objective": {
    "product": {
      "product_id": "prod_ps5pro_us_001",
      "quantity": 1
    }
  },
  "conditions": {
    "availability": "in_stock",
    "max_price_cents": 80000,
    "currency": "USD"
  },
  "guardrails": {
    "allowed_merchants": ["target", "bestbuy", "walmart"],
    "expires_at": "2026-02-01T00:00:00Z",
    "retry_policy": "safe"
  },
  "payment": {
    "payment_method_id": "pm_...",
    "max_charge_cents": 82000
  },
  "metadata": {
    "source": "assistant_v1"
  }
}
```

### Typical event sequence

```json theme={null}
{ "type": "intent.created", "intent_id": "int_..." }
```

```json theme={null}
{
  "type": "intent.waiting",
  "intent_id": "int_...",
  "data": { "reason": "OUT_OF_STOCK" }
}
```

```json theme={null}
{ "type": "intent.executing", "intent_id": "int_..." }
```

If checkout requires an OTP/3DS confirmation:

```json theme={null}
{
  "type": "execution.needs_user_action",
  "intent_id": "int_...",
  "data": {
    "action_type": "otp",
    "instructions": "Enter the code sent to your phone to confirm the purchase."
  }
}
```

Partner prompts the user, then resumes:

```bash theme={null}
POST /intents/int_.../resume
Authorization: Bearer GUPPY_SECRET_KEY
Content-Type: application/json
```

```json theme={null}
{
  "user_action": {
    "type": "otp",
    "completed": true
  }
}
```

Finally:

```json theme={null}
{
  "type": "intent.succeeded",
  "intent_id": "int_...",
  "data": {
    "purchase": {
      "merchant": "target",
      "total_charged_cents": 79999,
      "currency": "USD"
    }
  }
}
```

***

## Example 2: Restaurant reservation (watch cancellations)

Goal: “Table for 4 Fri or Sat between 7–9pm. Watch cancellations. Give up if not confirmed by Thursday.”

### Step 1 - Resolve venue (no URLs)

```bash theme={null}
POST /resolve/venues
Authorization: Bearer GUPPY_SECRET_KEY
Content-Type: application/json
```

```json theme={null}
{
  "query": "Restaurant Name",
  "location": { "city": "San Francisco" },
  "allowed_providers": ["resy", "opentable"]
}
```

Pick a `venue_id` (and provider) from the returned candidates.

### Step 2 - Create intent

```json theme={null}
{
  "external_user_id": "user_123",
  "type": "reservation",
  "objective": {
    "reservation": {
      "provider": "resy",
      "venue_id": "ven_sf_nopa_001",
      "party_size": 4
    }
  },
  "conditions": {
    "time_windows": [
      {
        "start": "2026-01-16T19:00:00-08:00",
        "end": "2026-01-16T21:00:00-08:00"
      },
      {
        "start": "2026-01-17T19:00:00-08:00",
        "end": "2026-01-17T21:00:00-08:00"
      }
    ]
  },
  "guardrails": {
    "expires_at": "2026-01-15T23:59:00-08:00",
    "retry_policy": "safe"
  }
}
```

***

## Example 3: Passport / DMV appointment (earliest slot within 30 miles)

Goal: “Book the earliest appointment within 30 miles. Keep watching cancellations until booked.”

### Step 1 - Resolve facilities (no URLs)

```bash theme={null}
POST /resolve/appointment-facilities
Authorization: Bearer GUPPY_SECRET_KEY
Content-Type: application/json
```

```json theme={null}
{
  "kind": "passport",
  "country": "US",
  "location": { "lat": 37.7749, "lng": -122.4194, "radius_miles": 30 }
}
```

Pick a `facility_id` from the returned candidates.

### Step 2 - Create intent

```json theme={null}
{
  "external_user_id": "user_123",
  "type": "reservation",
  "objective": {
    "appointment": {
      "kind": "passport",
      "facility_id": "fac_us_passport_sf_003"
    }
  },
  "conditions": {
    "date_range": { "start": "2026-01-13", "end": "2026-02-28" },
    "strategy": "earliest_available"
  },
  "guardrails": {
    "expires_at": "2026-02-28T23:59:59Z",
    "retry_policy": "safe"
  }
}
```

### What the partner app does

* Listen for `execution.needs_user_action` to collect missing identity fields or confirmations.
* Once `intent.succeeded` arrives, show the user the booked slot.
* Optionally fetch proof:

```bash theme={null}
GET /intents/int_.../receipt
Authorization: Bearer GUPPY_SECRET_KEY
```

***

## Example 4: SMB replenishment (avoid double ordering, net terms)

Goal: “Reorder when inventory \< 10. Net-30 only.”

### Create intent

```bash theme={null}
POST /intents
Idempotency-Key: replenish_sku_coffee_5lb_threshold_10
```

```json theme={null}
{
  "external_user_id": "biz_456",
  "type": "purchase",
  "objective": {
    "procurement": {
      "item": { "name": "Coffee Beans 5lb", "sku": "coffee_5lb" },
      "quantity": 2
    }
  },
  "conditions": {
    "trigger": {
      "kind": "inventory_below",
      "sku": "coffee_5lb",
      "threshold": 10
    }
  },
  "guardrails": {
    "retry_policy": "safe"
  },
  "payment": {
    "billing_terms": "net-30"
  },
  "metadata": {
    "inventory_system": "erp",
    "warehouse": "sf_warehouse"
  }
}
```

### What the partner app does

* De-dupe create calls with `Idempotency-Key` so a retry can’t create duplicate orders.
* Use webhook events to update internal order state (pending → executing → succeeded).
* On success, fetch receipt/proof for accounting:

```bash theme={null}
GET /intents/int_.../receipt
Authorization: Bearer GUPPY_SECRET_KEY
```

***

## Integration checklist (what you build on your side)

* **API client**: call `POST /intents`, `GET /intents/{id}`, `POST /intents/{id}/cancel`, `POST /intents/{id}/resume`
* **Webhook receiver**: store `event_id` for de-duplication and update intent state
* **User-action UI**: handle `execution.needs_user_action` and call `resume`
* **Receipt storage**: download/store proof artifacts when needed (support, disputes, compliance)