---
name: shopstack-checkout
description: Use Shopstack to onboard a verified personal account or a developer with independently scoped end users, inspect optional Link connectivity, and run asynchronous online checkouts while displaying status, activity, and mechanical intent. Trigger for buying products, automating checkout, integrating Shopstack into an agent, or managing developer-owned shopping users.
---

# Shopstack Checkout

Use Shopstack as the checkout execution layer. Keep account verification, user ownership, protected payment input, and final payment approval at their typed boundaries.

## Install

For the JavaScript client and CLI:

```bash
npm install shopstack
npm install -g shopstack
```

For MCP clients, configure the local stdio server:

```json
{
  "mcpServers": {
    "shopstack": {
      "command": "npx",
      "args": ["-y", "shopstack-mcp"]
    }
  }
}
```

Never ask the model to print or relay a Shopstack API key. The CLI and MCP server save verified keys in the private local Shopstack profile file.

## Choose the account shape

- Use a personal account for `Shopstack -> user`.
- Use a developer account for `Shopstack -> developer -> user1, user2, ...`.
- A developer management key creates and manages users but cannot run a user's checkout.
- Every developer-owned user receives an independent user API key and profile.

Start verified CLI signup:

```bash
shopstack signup
```

The command prompts for email and Personal or Developer account type. The user
must open the time-limited verification link. No account or API key exists
before verification. The CLI generates and privately stores its retry and
polling capabilities before the request, polls signup, saves the verified key
with mode `0600`, and prints none of those credentials. Rerunning
`shopstack signup` automatically resumes the matching pending attempt after an
interruption; `shopstack signup resume SIGNUP_ID` remains an explicit helper.

After developer signup, create an end user:

```bash
shopstack users create --external-id customer-123 --profile customer-123
```

Use `shopstack profiles list` and `shopstack profiles use NAME` to select a local profile without exposing its key.

## Choose payment connectivity

Link is currently the only persistent payment provider, and it is optional:

```bash
shopstack connect list
shopstack connect link
```

Include `payment_provider: "link"` only when the active user's Link connection reports checkout-ready. Otherwise omit `payment_provider`. Shopstack will run until card entry and request one protected checkout-scoped card through the SDK or no-echo CLI prompt.

Never put card data in MCP arguments, natural-language messages, model output, logs, or ordinary CLI flags.

## Create and monitor a checkout

Supply the canonical customer schema unchanged:

```json
{
  "item_url": "https://merchant.example/product",
  "instructions": "Buy one in blue",
  "customer": {
    "email": "buyer@example.com",
    "name": "Example Buyer",
    "phone": "+12125550100",
    "shipping_address": {
      "line1": "1 Example Street",
      "line2": "Apartment 2",
      "suburb": "Manhattan",
      "city": "New York",
      "region": "NY",
      "postal_code": "10001",
      "country": "US"
    }
  },
  "maximum_amount": "75.00",
  "currency": "USD"
}
```

Run it with:

```bash
shopstack checkout run --file checkout.json
```

Or create with MCP, then call `poll_checkout`. Display these authoritative fields to the user when they change:

- `status`: one of exactly `queued`, `started`, `help_required`, `approval_required`, `submitting`, `complete`, `failed`, `cancelled`;
- `presentation_revision`: the monotonic revision for user-visible checkout state;
- `activity`: bounded present-tense display text;
- `intent.name`, `intent.phase`, and `intent.updated_at`: bounded mechanical action progress with no arguments or reasoning;
- `required_input`: a typed handoff such as protected payment-card input;
- `approval`: the exact amount-bound approval request when present.

The CLI and JavaScript client subscribe with a one-time checkout-scoped
WebSocket capability. Each valid notification means the presentation revision
changed; the client then fetches the canonical checkout before displaying or
acting on it. The notification is not checkout state truth and never grants
payment authority. The capability belongs in the WebSocket subprotocol, never
the URL, logs, model context, or messages. If WebSocket delivery is unavailable,
the client falls back to bounded HTTP waiting and then fixed polling.

MCP and manual integrations poll every two seconds for `queued`, `started`, and
`submitting`; every five seconds for `help_required` and `approval_required`;
stop at `complete`, `failed`, or `cancelled`.

The optional `live_view_url` is a private owner-viewer capability. Show it only
to the initiating user. Do not store it in browser storage, analytics, logs,
model context, or ordinary messages.

## Respond at typed boundaries

- Use `GET/POST /v1/checkout/{id}/messages` only for ordinary missing information.
- Use protected SDK/CLI payment input when `required_input.type` is `payment_card`.
- Use only the dedicated payment-approval endpoint from a separately scoped trusted backend.
- MCP and messages cannot approve payment and expose no approval tool.
- Never infer approval from a user's conversational message.
- Cancel with the typed cancellation operation if the user withdraws the request.

Use the checkout's canonical current representation as state truth. Events are ordered evidence, not a replacement state machine. Preserve idempotency keys on retried mutations.