# Swipefast API

Swipefast is a checkout and funnel platform for solo sellers. This file is the
complete developer surface, written for machine consumption.

Base URL: https://swipefast.jacob-98c.workers.dev
Auth: every endpoint takes `Authorization: Bearer <key>`. Keys look like
`sf_live_…` and live in the seller's Settings page.
Machine-readable spec: /developers/openapi.json
Human docs: /developers

MCP server: POST /api/mcp — the same account, spoken as Model Context Protocol,
authenticated with the same Bearer key. Tools are scoped to the calling seller and
none of them takes a user id. Setup and the tool list: /developers/mcp

## Endpoints

### GET /api/v1/products

Every product on your account, with its price, address and status.

`pricing_type` is `onetime` or `subscription`; subscriptions also carry `billing_interval` (`month` or `year`).

Response example:
```json
{
  "data": [
    {
      "id": "prd_a1b2c3",
      "name": "The Launch Playbook",
      "slug": "launch-playbook",
      "price_cents": 9900,
      "currency": "usd",
      "pricing_type": "onetime",
      "billing_interval": null,
      "status": "live"
    }
  ]
}
```

### GET /api/products/{productId}/funnel

The add-ons, upsells and every post-purchase email attached to one product.

Path params:
- productId (string, required): The product's id, from List your products.

Works with your key or a signed-in dashboard session.

Response example:
```json
{
  "bumps": [
    {
      "id": "bmp_1",
      "headline": "Add the Swipe File Vault — $27",
      "price_cents": 2700,
      "active": 1
    }
  ],
  "upsells": [
    {
      "id": "ups_1",
      "headline": "Upgrade to the full implementation call",
      "price_cents": 20000,
      "active": 1
    }
  ],
  "downsells": [],
  "emails": [
    {
      "position": 1,
      "send_day": 0,
      "subject": "You're in — here's your access",
      "body": "…"
    }
  ]
}
```

### GET /api/v1/orders

Your latest 100 orders, newest first, each with its line items. Test orders are never included.

`status` is `paid`, `refunded`, or `authorized` (card held while the buyer decides on an upsell).

`items[].kind` is `main`, `bump`, `upsell`, or `discount` (discounts are negative). `downsell` appears only on orders taken before downsells were retired.

Orders carry the campaign that produced them: `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`.

Response example:
```json
{
  "data": [
    {
      "id": "ord_x1y2z3",
      "product_id": "prd_a1b2c3",
      "customer_email": "buyer@example.com",
      "customer_name": "Alex Buyer",
      "total_cents": 12600,
      "currency": "usd",
      "status": "paid",
      "utm_source": "newsletter",
      "utm_campaign": "july-launch",
      "created_at": "2026-07-20T14:03:22.181Z",
      "items": [
        {
          "kind": "main",
          "label": "The Launch Playbook",
          "amount_cents": 9900
        },
        {
          "kind": "bump",
          "label": "Add the Swipe File Vault — $27",
          "amount_cents": 2700
        }
      ]
    }
  ]
}
```

### POST /api/v1/orders

Create an order from your own code — an external checkout, an import, an automation. It settles immediately.

Body (JSON):
- productSlug (string, required): The product's slug, from List your products.
- email (string, required): The buyer's email.
- name (string): The buyer's name.
- bumpIds (string[]): Ids of add-ons to include.
- affiliateCode (string): Credit this partner with the sale.

Fires the `order.paid` webhook and any matching automations, exactly like a checkout sale.

Response example:
```json
{
  "ok": true,
  "orderId": "ord_x1y2z3",
  "totalCents": 9900
}
```

### GET /api/metrics/{productId}

Revenue, orders, average order, add-on and upsell rates, refunds — plus monthly series for charts.

Path params:
- productId (string, required): The product's id.

`mrrByMonth` and `churnByMonth` are filled for subscription products only.

Test orders never count.

Response example:
```json
{
  "product": {
    "id": "prd_a1b2c3",
    "name": "The Launch Playbook",
    "pricingType": "onetime"
  },
  "summary": {
    "revenueCents": 2313900,
    "orders": 230,
    "aovCents": 100600,
    "bumpTakeRate": 21,
    "upsellTakeRate": 8,
    "activeSubscriptions": 0,
    "mrrCents": 0,
    "refunds": 3,
    "refundedCents": 29900,
    "refundRate": 1.3,
    "views": 4100,
    "conversionRate": 5.6,
    "customers": 224
  },
  "revenueByMonth": [
    {
      "month": "2026-06",
      "value": 412300
    }
  ],
  "mrrByMonth": [],
  "churnByMonth": []
}
```

### POST /api/cron/daily

Charges subscription renewals that have come due, retries declined cards, nudges checkouts that stalled, and settles payment holds a buyer never finalised. Point a once-a-day schedule at this — nothing else calls it.

Safe to run more than once a day — nothing is charged twice and a buyer is only ever nudged once.

Response example:
```json
{
  "ok": true,
  "rebills": {
    "charged": 12,
    "chargedCents": 58800,
    "retried": 1,
    "canceled": 0
  },
  "recovery": {
    "sent": 3,
    "recovered": 1
  },
  "holdsSettled": 2
}
```

## Webhooks

Connect a webhook in Integrations and every event POSTs to your URL as JSON,
with the event name repeated in the `x-swipefast-event` header. Return any
2xx to acknowledge. Payloads always include `event` and `sentAt`.

### order.paid — Sale completed

A checkout settles — including held orders once the buyer decides on the upsell.

```json
{
  "event": "order.paid",
  "orderId": "ord_x1y2z3",
  "product": "The Launch Playbook",
  "productId": "prd_a1b2c3",
  "email": "buyer@example.com",
  "totalCents": 12600,
  "affiliate": "ryanh",
  "accessUrl": "https://your-course.com/access",
  "supportEmail": "help@you.com",
  "sentAt": "2026-07-20T14:03:24.001Z"
}
```

### order.refunded — Order refunded

You refund an order. Any subscription born from it is cancelled, and its commission is voided.

```json
{
  "event": "order.refunded",
  "orderId": "ord_x1y2z3",
  "product": "The Launch Playbook",
  "email": "buyer@example.com",
  "totalCents": 12600,
  "sentAt": "2026-07-21T09:12:00.410Z"
}
```

### upsell.accepted — Upsell taken

A buyer says yes to the post-purchase upsell.

```json
{
  "event": "upsell.accepted",
  "orderId": "ord_x1y2z3",
  "upsell": "Upgrade to the full implementation call",
  "amountCents": 20000,
  "email": "buyer@example.com",
  "sentAt": "2026-07-20T14:04:01.812Z"
}
```

### subscription.rebilled — Renewal collected

A subscription's renewal charge went through.

```json
{
  "event": "subscription.rebilled",
  "subscriptionId": "sub_m4k3r",
  "product": "Maker Club Membership",
  "email": "member@example.com",
  "amountCents": 4900,
  "sentAt": "2026-08-21T09:00:04.120Z"
}
```

### subscription.payment_failed — Renewal failed

A renewal charge was declined. Swipefast retries in 3 days; after 4 failed tries the subscription cancels.

```json
{
  "event": "subscription.payment_failed",
  "subscriptionId": "sub_m4k3r",
  "product": "Maker Club Membership",
  "email": "member@example.com",
  "amountCents": 4900,
  "attempt": 1,
  "nextTryDays": 3,
  "sentAt": "2026-08-21T09:00:04.560Z"
}
```

### subscription.canceled — Subscription cancelled

You cancel a subscription. `subscription.paused` and `subscription.resumed` fire the same shape for those actions.

```json
{
  "event": "subscription.canceled",
  "subscriptionId": "sub_m4k3r",
  "product": "Maker Club Membership",
  "email": "member@example.com",
  "mrrCents": 4900,
  "sentAt": "2026-07-21T10:00:12.230Z"
}
```

### affiliate.paid — Partner paid

You record a commission payout to a partner.

```json
{
  "event": "affiliate.paid",
  "affiliate": "ryanh",
  "name": "Ryan H",
  "email": "ryan@example.com",
  "amountCents": 12000,
  "commissionCount": 3,
  "payoutId": "pay_9f8e7d",
  "sentAt": "2026-07-21T11:30:00.000Z"
}
```

### funnel.email.sync — Email handed over

A seller pushes their post-purchase emails to your tool — one event per email.

```json
{
  "event": "funnel.email.sync",
  "productId": "prd_a1b2c3",
  "productSlug": "launch-playbook",
  "product": "The Launch Playbook",
  "position": 1,
  "sendDay": 0,
  "subject": "You're in — here's your access",
  "body": "…full email body…",
  "sentAt": "2026-07-19T16:21:00.551Z"
}
```