Drivethru Stripe

SKILL.md

---
name: drivethru-stripe
description: Look up products in the Stripe catalog and create a Stripe Checkout Session that returns a hosted checkout URL. Use whenever the user needs to browse what's for sale, bill a customer, collect a one-time payment, or start a subscription via a Stripe-hosted page.
version: 0.2.0
emoji: 💳
homepage: https://stripe.com/docs/api/checkout/sessions
metadata:
  openclaw:
    requires:
      env: [STRIPE_SECRET_KEY]
      bins: [python3]
    primaryEnv: STRIPE_SECRET_KEY
    envVars:
      STRIPE_SECRET_KEY:
        required: true
        description: >
          Stripe secret API key (starts with `sk_test_` for test mode or `sk_live_` for live mode).
          Create one at https://dashboard.stripe.com/apikeys. The skill makes server-side API calls
          and will not work with a publishable key (`pk_...`).
    install:
      uv:
        - stripe>=10.0.0
---

# Stripe Checkout & Product Lookup

This skill does two things against the Stripe API:

1. **List/search products** in the Stripe product catalog — returns name, description, image, prices, and metadata.
2. **Create a [Stripe Checkout Session](https://stripe.com/docs/api/checkout/sessions/create)** and return the hosted payment URL the customer should be redirected to.

A typical flow: call `list_products.py` to find the right `price_...` id(s), then pass them to `create_checkout_session.py` as `line_items`.

## Required credentials

The agent host MUST expose **`STRIPE_SECRET_KEY`** in the environment before this skill is invoked.

- Test mode key: `sk_test_...` (use during development; charges are not real)
- Live mode key: `sk_live_...` (real money — only after explicit user confirmation)

If `STRIPE_SECRET_KEY` is missing, stop and tell the user to set it. Do not prompt the user to paste the key into chat — secrets must come from the environment.

Optional environment variables:

| Variable                  | Purpose                                                                |
| ------------------------- | ---------------------------------------------------------------------- |
| `STRIPE_API_VERSION`      | Pin a Stripe API version (defaults to the account's pinned version).   |
| `STRIPE_DEFAULT_SUCCESS_URL` | Fallback `success_url` when the user does not provide one.          |
| `STRIPE_DEFAULT_CANCEL_URL`  | Fallback `cancel_url` when the user does not provide one.           |

## When to use

- "What products do we sell?" / "List our Stripe catalog" / "Find the price of X"
- "Create a checkout link for X"
- "Bill the customer $N for Y"
- "Start a subscription to price `price_...`"
- "Generate a Stripe payment page for these items"

## When NOT to use

- The user wants to charge a saved card directly → use the PaymentIntents API instead (different skill).
- The user wants to issue a refund, manage a subscription's lifecycle, or read reports → out of scope here.
- The user wants to *create* or *edit* a product → out of scope; use the Stripe dashboard or a separate skill.

## Scripts

| Script                                | Purpose                                                       |
| ------------------------------------- | ------------------------------------------------------------- |
| `scripts/list_products.py`            | Query products (list / search / by id) + their prices         |
| `scripts/create_checkout_session.py`  | Create a Checkout Session and return the hosted checkout URL  |

---

## Listing products

Call `scripts/list_products.py` with an optional JSON filter on stdin. With no input, it returns the first 10 active products.

### Input schema (all fields optional)

```json
{
  "query": "shirt",
  "ids": ["prod_abc", "prod_def"],
  "active": true,
  "limit": 10,
  "starting_after": "prod_xyz",
  "include_inactive_prices": false
}
```

- `query` — free-text search against product name. If the string contains a `:`, it is passed through as a raw [Stripe Search](https://stripe.com/docs/search) query (e.g. `metadata['sku']:'A-100' AND active:'true'`). Search results may lag writes by up to a minute.
- `ids` — retrieve specific products by id (skips list/search). Up to ~50 is reasonable.
- `active` — defaults to `true`. Pass `false` to include archived products, or `null` for both.
- `limit` — 1–100, defaults to 10.
- `starting_after` — pagination cursor (returned as `next_starting_after`). Only applies to plain list mode.
- `include_inactive_prices` — defaults to `false`. Each returned product's `prices` array only contains active prices unless this is `true`.

### Example invocation

```bash
echo '{"query": "shirt", "limit": 5}' | python3 scripts/list_products.py
```

### Output

```json
{
  "products": [
    {
      "id": "prod_NabcXYZ",
      "name": "Cotton T-shirt",
      "description": "100% cotton, unisex",
      "image": "https://files.stripe.com/.../shirt-front.png",
      "images": ["https://files.stripe.com/.../shirt-front.png"],
      "metadata": {"sku": "TS-001", "color": "navy"},
      "active": true,
      "default_price": "price_1Nabc...",
      "prices": [
        {
          "id": "price_1Nabc...",
          "unit_amount": 1500,
          "currency": "usd",
          "recurring": null,
          "nickname": null,
          "active": true
        }
      ]
    }
  ],
  "has_more": false,
  "next_starting_after": null
}
```

- `unit_amount` is in the smallest currency unit (cents for USD).
- `image` is the first entry from `images` for convenience; use `images` if you need them all.
- `metadata` is the product's free-form key/value map set in the Stripe dashboard.
- When `has_more` is true, pass `next_starting_after` back as `starting_after` to get the next page.

When the user asks about pricing for a product, prefer the `default_price` if set; otherwise, surface all `prices` so they can pick.

---

## Creating a Checkout Session

Call `scripts/create_checkout_session.py` with a JSON payload on stdin. The script prints a JSON object with `url`, `id`, and `expires_at` on success.

### Input schema

```json
{
  "mode": "payment | subscription | setup",
  "line_items": [
    {"price": "price_123", "quantity": 1},
    {
      "price_data": {
        "currency": "usd",
        "unit_amount": 1500,
        "product_data": {"name": "Custom T-shirt", "description": "Size M"}
      },
      "quantity": 2
    }
  ],
  "success_url": "https://example.com/success?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url":  "https://example.com/cancel",
  "customer_email": "optional@example.com",
  "client_reference_id": "optional-internal-id",
  "metadata": {"order_id": "1234"},
  "allow_promotion_codes": true
}
```

- `mode` defaults to `"payment"` (one-time). Use `"subscription"` when any line item references a recurring price.
- Each `line_items[*]` entry MUST contain either `price` (existing Stripe Price ID) OR `price_data` (inline price), plus `quantity`.
- `unit_amount` is in the smallest currency unit (cents for USD).
- `success_url` is required by Stripe. Use `{CHECKOUT_SESSION_ID}` to receive the session id back as a query param.

### Example invocation

```bash
echo '{
  "mode": "payment",
  "line_items": [{"price": "price_1Nabc...", "quantity": 1}],
  "success_url": "https://example.com/success?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://example.com/cancel"
}' | python3 scripts/create_checkout_session.py
```

Successful output:

```json
{
  "url": "https://checkout.stripe.com/c/pay/cs_test_...",
  "id": "cs_test_a1B2c3D4...",
  "expires_at": 1716595200,
  "mode": "payment",
  "livemode": false
}
```

Return the `url` to the user — that is the link they (or their customer) should open to complete payment.

### Errors

The script exits non-zero and prints a JSON `{"error": {...}}` object on failure. Common cases:

- `auth_error` — `STRIPE_SECRET_KEY` is missing, malformed, or revoked.
- `invalid_request` — bad `price` id, currency mismatch, missing `success_url`.
- `validation_error` — the input JSON does not satisfy the schema.

Surface the human-readable `message` to the user and suggest the obvious fix. Do not retry on `auth_error` or `validation_error`.

## Safety

- Always confirm the **mode** (test vs live) and **total amount** with the user before creating a session in live mode.
- Never log the full `STRIPE_SECRET_KEY`. The script reads it from the environment and never echoes it.
- Treat the returned `url` as sensitive-ish: anyone with the link can pay. Share it only with the intended customer.

## References

See [`references/checkout_options.md`](references/checkout_options.md) for the less-common Checkout Session fields (shipping, tax, automatic_payment_methods, etc.).