Skip to main content
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)

POST /resolve/products
Authorization: Bearer GUPPY_SECRET_KEY
Content-Type: application/json

{
  "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

POST /intents
Authorization: Bearer GUPPY_SECRET_KEY
Content-Type: application/json
Idempotency-Key: buy_user123_ps5pro_under800_before_2026-02-01

{
  "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

{ "type": "intent.created", "intent_id": "int_..." }

{
  "type": "intent.waiting",
  "intent_id": "int_...",
  "data": { "reason": "OUT_OF_STOCK" }
}

{ "type": "intent.executing", "intent_id": "int_..." }
If checkout requires an OTP/3DS confirmation: 
{
  "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: 
POST /intents/int_.../resume
Authorization: Bearer GUPPY_SECRET_KEY
Content-Type: application/json

{
  "user_action": {
    "type": "otp",
    "completed": true
  }
}
Finally: 
{
  "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)

POST /resolve/venues
Authorization: Bearer GUPPY_SECRET_KEY
Content-Type: application/json

{
  "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

{
  "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)

POST /resolve/appointment-facilities
Authorization: Bearer GUPPY_SECRET_KEY
Content-Type: application/json

{
  "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

{
  "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:
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

POST /intents
Idempotency-Key: replenish_sku_coffee_5lb_threshold_10

{
  "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:
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)