URL: /code/integrations/stripe · Id: `page:/code/integrations/stripe`

# Stripe

> Your agents put a checkout on every offer, take a pilot’s first payment and refund when asked; each payment credits the Play that earned it.

Your agents put a checkout on every [offer](https://startupbuilder.dev/business/nouns/offer), take a pilot’s first payment and refund when asked; each payment credits the [Play](https://startupbuilder.dev/business/nouns/play) that earned it.

```text title="Run it · Ask"
Put a checkout link on my 90-day pilot at $99 a month, and show me the page.
```

```ts title="Run it · SDK"
import { $ } from 'startup-builder'

const result = await $.try.Offer.publish({ offer: 'offers/pilot-90-day', checkout: 'link' })
```

```json title="Run it · Response"
{
  "$type": "Offer",
  "mode": "try",
  "stored": false,
  "offer": "offers/pilot-90-day",
  "price": {
    "amount": 99,
    "currency": "USD",
    "per": "month",
    "for": "3 months"
  },
  "checkout": "https://pay.leaseline.app/b/pilot-90-day",
  "onPaid": "Order.paid credits the Play that started the Deal"
}
```

- **Connect:** Nothing to connect, 1 grant
- **Runs through:** [Your account](/code/integrations#three-ways)
- **First run:** Put a checkout on your pilot offer, free on your account
- **Sites:** None, it holds your records

## Connect once
1. Nothing to connect: your startup’s own Stripe connected account opens with your first paid offer (hub [Stripe](https://startupbuilder.dev/systems/integrations/stripe)).
2. To bring an existing Stripe account’s customers and history in, call `Integration.connect` with `system: 'billing'`; it imports read-only.

| Grant | What it unlocks | Scope |
| --- | --- | --- |
| Read your existing account | Customers, Subscriptions and charges imported once, read-only | `read_only` |

| To | Do this |
| --- | --- |
| Pause | `Integration.pause` stops new checkouts at once; payments already made settle as usual. |
| Reconnect | `Integration.reconnect` re-approves an imported account in place, keeping its cursor, so no charge imports twice. |
| Disconnect | `Integration.revoke` ends the import of an existing account; your startup’s own connected account stays, because your customers pay through it. |

## What your agents do
| Ask | Verb | Runs through | Price |
| --- | --- | --- | --- |
| Put a checkout link on the 90-day pilot. | [`Offer.publish`](https://startupbuilder.dev/business/nouns/offer/publish) | Your account | Free |
| Take Northgate’s first payment for the pilot. | [`Order.pay`](https://startupbuilder.dev/business/nouns/order/pay) | Your account | Free |
| Add Northgate’s second portfolio to their subscription. | [`Subscription.resize`](https://startupbuilder.dev/business/nouns/subscription/resize) | Your account | Free |
| Refund the second month to Cedar Hollow, with the reason. | [`Order.refund`](https://startupbuilder.dev/business/nouns/order/refund) | Your account | Free |
| Show me this month’s payouts and fees. | [`Transaction.list`](https://startupbuilder.dev/business/nouns/transaction/list) | Your account | Free |

Calls on your own account are free.

## What it holds
| Noun | The account’s object | When | Which side leads |
| --- | --- | --- | --- |
| [Customer](https://startupbuilder.dev/business/nouns/customer) | `customer` | A buyer pays for the first time | Your records |
| [Offer](https://startupbuilder.dev/business/nouns/offer) | `product` | You publish an offer | Your records |
| [Price](https://startupbuilder.dev/business/nouns/price) | `price` | You publish an offer | Your records |
| [Invoice](https://startupbuilder.dev/business/nouns/invoice) | `invoice` | A Subscription bills | The account |
| [Subscription](https://startupbuilder.dev/business/nouns/subscription) | `subscription` | A buyer subscribes | The account |
| [Transaction](https://startupbuilder.dev/business/nouns/transaction) | `balance transaction` | Money moves | The account |
| [Dispute](https://startupbuilder.dev/business/nouns/dispute) | `dispute` | A buyer disputes a charge | The account |

## Events and webhooks
| Direction | Event |
| --- | --- |
| Emits | `Offer.published`, `Order.paid`, `Order.refunded`, `Subscription.resized` |
| Hears `checkout.session.completed` | Becomes `Order.paid` |
| Hears `invoice.paid` | Becomes `Subscription.renewed` |
| Hears `charge.dispute.created` | Becomes `Order.disputed` |
| Hears `charge.refunded` | Becomes `Order.refunded` |

Any Event can wake a Workflow, and a Watch delivers it to your endpoint, signed ([Events and webhooks](/code/events)).

## Limits
| What | Limit | Call |
| --- | --- | --- |
| An imported account | Reads only: new checkouts always run on your startup’s own connected account | Every call |
| Refunds | Up to what the Order paid, with the reason; each one posts its reversing Entries | [`Order.refund`](https://startupbuilder.dev/business/nouns/order/refund) |
| Disputes | Stripe sets a deadline on each; your agent drafts the evidence from the Order’s records the day it opens | Every call |

## What try does here
Returns the checkout, the amount and the Entries it would post; nothing is charged. A `sk_test_` key runs the same calls against your Stripe test account.

## How long a connection lasts
A connection lasts for as long as your startup runs: the connected account carries no sign-in that runs out, and an imported account lasts until you revoke it.

The platform asks you to reconnect 7 days before it runs out; until you do, a call that needs it refuses with [`needs-reauth`](/code/refusals#needs-reauth).

## Plays and strategies
| Kind | Where |
| --- | --- |
| Plays | [Paid pilot](/plays/paid-pilot), [Annual prepay](/plays/annual-prepay), [Risk-reversal offers](/plays/risk-reversal-offers), [Usage upsell](/plays/usage-upsell) |
| Strategies | [Hands-on](/strategy/hands-on), [Paid](/strategy/paid), [Launch and search](/strategy/launch-and-search) |

## Used by
No Workflow, agent task or Service acts through it yet: your agents call it directly.

## Reference

| Call | Path | Price |
| --- | --- | --- |
| [`Offer.publish`](https://startupbuilder.dev/business/nouns/offer/publish) | `POST /offers/publish` | Free |
| [`Order.pay`](https://startupbuilder.dev/business/nouns/order/pay) | `POST /orders/pay` | Free |
| [`Subscription.resize`](https://startupbuilder.dev/business/nouns/subscription/resize) | `POST /subscriptions/resize` | Free |
| [`Order.refund`](https://startupbuilder.dev/business/nouns/order/refund) | `POST /orders/refund` | Free |
| [`Transaction.list`](https://startupbuilder.dev/business/nouns/transaction/list) | `GET /transactions/list` | Free |