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

# Integrations overview

> Connect Pocketsflow to external stores and platforms using the API and webhooks.

You can connect Pocketsflow to almost any external store, platform, or internal
tool using two building blocks:

1. **The HTTP API** — to create checkout sessions and read/write data.
2. **Webhooks** — to react when something happens (a sale completes, a
   subscription renews, a refund is issued).

This section shows how to combine them into a working integration, with a
complete [WooCommerce](/integrations/woocommerce) example and a
[generic pattern](/integrations/custom-platforms) you can adapt to any platform.

## The building blocks

<Columns cols={2}>
  <Card title="API keys" icon="key" href="/api-reference/introduction">
    Authenticate server-to-server with a `pk_live_…` / `pk_test_…` key.
  </Card>

  <Card title="Checkout sessions" icon="cart-shopping" href="https://api.pocketsflow.com/docs">
    `POST /checkout/sessions` returns a hosted URL to redirect buyers to.
  </Card>

  <Card title="Webhooks" icon="bolt" href="/api-webhooks/events">
    Subscribe to events like `order.completed` and `customer.created`.
  </Card>

  <Card title="Metadata" icon="tags" href="/integrations/custom-platforms">
    Attach your own IDs so you can correlate Pocketsflow orders with yours.
  </Card>
</Columns>

## Example repositories

Clone a complete, runnable example — a checkout embed plus a signature-verifying
webhook receiver — and adapt it to your platform.

<Columns cols={2}>
  <Card title="Subscriptions example" icon="github" href="https://github.com/pocketsflow/subscriptions-example">
    Embed a subscription checkout and handle the subscription lifecycle webhooks.
  </Card>

  <Card title="One-time products example" icon="github" href="https://github.com/pocketsflow/one-time-products-example">
    Embed a product checkout and handle `order.completed` / `order.refunded` webhooks.
  </Card>
</Columns>

## The standard pattern

Almost every "sell through my own store / platform" integration follows the
same five steps:

<Steps>
  <Step title="Create an API key">
    In the dashboard, go to **Developers → API keys** and create a key. Store it
    as a secret on your server.
  </Step>

  <Step title="Map your products to Pocketsflow products">
    Each item you sell maps to a Pocketsflow `productId`. Create products in the
    dashboard or via `POST /products`, and store the resulting `productId`
    alongside your own product records.
  </Step>

  <Step title="Create a checkout session at purchase time">
    When a buyer checks out, call `POST /checkout/sessions` with the `productId`,
    your `successUrl` / `cancelUrl`, and a `metadata` object containing **your**
    order id. Redirect the buyer to the `url` you get back.
  </Step>

  <Step title="Let the buyer pay on Pocketsflow">
    Pocketsflow hosts the checkout and handles payment, tax, and receipts. After
    payment the buyer is redirected to your `successUrl`.
  </Step>

  <Step title="Confirm the sale with a webhook">
    Register a webhook for `order.completed`. When it fires, verify the
    signature, read your order id back out of `metadata`, and mark the order
    paid in your system.
  </Step>
</Steps>

## Why metadata matters

The `metadata` you pass when creating a checkout session is **echoed back** on
the resulting order and in every related webhook payload. This is how you
correlate a Pocketsflow order with the order in your own system — without it,
you'd have no reliable way to know which of your orders a webhook refers to.

```json theme={null}
// Request: POST /checkout/sessions
{
  "productId": "65a1b2c3d4e5f6a7b8c9d0e1",
  "successUrl": "https://store.example.com/thank-you",
  "cancelUrl": "https://store.example.com/cart",
  "metadata": { "external_order_id": "WC-1043" }
}
```

```json theme={null}
// Later: the order.completed webhook payload echoes it back
{
  "order": { "id": "...", "amount": 4900, "currency": "usd" },
  "customer": { "email": "buyer@example.com" },
  "metadata": { "external_order_id": "WC-1043" }
}
```

## Develop and test locally

Build against a `pk_test_…` key first so no real money moves, then promote to
`pk_live_…`. To receive webhooks on your machine, expose your local server with
a tunnel (ngrok, cloudflared) and register the public URL as a webhook endpoint.
The full walkthrough — keys, first call, tunnel, signature verification, and a
go-live checklist — is in [Developer setup](/development).

<Tip>
  Building the integration with an AI editor? Start with the
  [MCP setup guide](/ai-tools/mcp) so the agent can call the API as your
  account, and give it these docs as context — see
  [Claude Code](/ai-tools/claude-code), [Cursor](/ai-tools/cursor), and
  [Windsurf](/ai-tools/windsurf).
</Tip>

## Common questions

<AccordionGroup>
  <Accordion title="How do I match a webhook to my order?">
    Read your own id back out of `metadata` (for example
    `metadata.external_order_id`). It's echoed on the order and every related
    webhook. Never rely on ordering or timing.
  </Accordion>

  <Accordion title="What if a webhook is missed?">
    Treat webhooks as the source of truth, but reconcile as a backstop: list
    recent orders via the API and match on your `metadata` id. Keep handlers
    idempotent so a re-send is safe.
  </Accordion>

  <Accordion title="Can I integrate a platform not listed here?">
    Yes — the [custom platforms](/integrations/custom-platforms) pattern (create
    a checkout session, redirect, confirm via webhook) works for any store,
    membership site, or no-code tool.
  </Accordion>
</AccordionGroup>

## Pick a guide

<Columns cols={2}>
  <Card title="WooCommerce" icon="bag-shopping" href="/integrations/woocommerce">
    A complete, step-by-step WooCommerce integration with PHP examples.
  </Card>

  <Card title="Any other platform" icon="puzzle-piece" href="/integrations/custom-platforms">
    The generic redirect + webhook pattern, with Node and PHP examples.
  </Card>

  <Card title="Developer setup" icon="terminal" href="/development">
    Keys, test mode, first API call, and local webhook testing.
  </Card>

  <Card title="MCP setup guide" icon="plug" href="/ai-tools/mcp">
    Build and operate your store with an AI agent.
  </Card>
</Columns>