The sales machinery layer, fully scriptable.

01 · Overview

Base URL, auth, limits, errors

One base URL. One auth header. JSON in, JSON out.

https://api.gocushy.com/api/v1

Authentication

Every request carries your API key as a bearer token. Keys start with gc_ and come from your dashboard after signup. Keys are revocable per merchant.

curl https://api.gocushy.com/api/v1/me \
  -H "Authorization: Bearer gc_your_key"

{
  "account": {
    "id": "01J2QJ3M8XN4V6T9R3E7M1B0CD",
    "name": "Acme Courses",
    "email": "sam@example.com",
    "plan": "founding",
    "stripe_connected": true
  }
}

Conventions

• Money is integer cents — 4900 = NZ$49.00. Currency is a lowercase 3-letter ISO code.
• IDs are ULIDs — 26-character sortable strings.
• Timestamps are ISO 8601.
• Send Content-Type: application/json and Accept: application/json.

Rate limit

120 requests per minute per API key, across the whole /api/v1 surface. Exceed it and you get a 429. Back off and retry.

Errors

Errors are JSON, always with a human-readable message.

02 · MCP integration

The recommended path: let an agent drive

GoCushy is MCP-native. Connect the server and any MCP client — Claude Desktop, Claude Code, Cursor, ChatGPT, your own agents — gets 40+ tools that run a complete sales operation: products, offers, checkout copy, email follow-up, webhooks, affiliates, refunds. The REST API below is the same surface; MCP is just the fastest way to use it.

Local (stdio) — Claude Desktop, Claude Code, Cursor

One command, one env var. The package is @gocushy/mcp on npm.

GOCUSHY_API_KEY=gc_your_key npx -y @gocushy/mcp

Config JSON for Claude Desktop or Cursor (claude_desktop_config.json / .cursor/mcp.json):

{
  "mcpServers": {
    "gocushy": {
      "command": "npx",
      "args": ["-y", "@gocushy/mcp"],
      "env": { "GOCUSHY_API_KEY": "gc_your_key" }
    }
  }
}

Remote (Streamable HTTP) — ChatGPT and hosted agents

No install. The remote server is stateless and key-scoped per request. Three ways to authenticate:

• ChatGPT (OAuth) — add the connector with the URL https://mcp.gocushy.com/mcp (no key in it). ChatGPT runs the OAuth handshake and shows a GoCushy consent page — paste your gc_ key there. The connection is revocable any time by revoking the key in your dashboard.
• Key in the path — for clients that accept a URL-embedded key (Cursor, custom agents): https://mcp.gocushy.com/mcp/gc_your_key
• Bearer header — https://mcp.gocushy.com/mcp with Authorization: Bearer gc_your_key

Step by step in ChatGPT

1. Check your plan. Custom MCP connectors need Plus, Pro, Team, Business or Enterprise. They are not available on the Free plan at all — no amount of looking will surface the menu.
2. Turn on Developer mode. Profile icon → Settings → Apps & Connectors → scroll to the bottom → Advanced settings → toggle Developer mode on. (On a Business/Enterprise workspace an admin does this instead, under Workspace settings → Permissions & roles. If you're on a work account and the toggle isn't there, you need your admin.)
3. Create the connector. Back in Apps & Connectors a Create button now appears. Name it GoCushy and use this URL exactly, including /mcp and with no key in it:
   MCP server URLCopy

   https://mcp.gocushy.com/mcp

4. Authenticate. Choose OAuth. ChatGPT runs the handshake and shows a GoCushy consent page — paste your gc_ API key there, not into ChatGPT's own fields.
5. Enable it in the chat. This is the step people miss. A connector being configured is not the same as it being on: open a new chat, and switch GoCushy on for that conversation. If ChatGPT says it has no GoCushy tools, this is almost always why.

ChatGPT's menus move — these steps were verified July 2026. If your screen doesn't match, search OpenAI's help centre for "developer mode MCP" rather than trusting this page, and tell us so we can fix it.

All 40+ tools

Every tool wraps a REST endpoint and returns JSON. The one thing an agent cannot do is complete Stripe identity verification — connect_payment returns a URL for the human, and that's the only human step.

03 · REST reference

Every endpoint, grouped

All paths are relative to https://api.gocushy.com/api/v1. All require the bearer key.

Account & Stripe

PayPal & Airwallex

Products

curl -X POST https://api.gocushy.com/api/v1/products \
  -H "Authorization: Bearer gc_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Launch Course",
    "description": "The complete 6-module launch system.",
    "price_cents": 4900,
    "currency": "usd",
    "delivery_url": "https://members.example.com/launch-course",
    "delivery_note": "Log in with the email you purchased with."
  }'

{
  "product": {
    "id": "01J2QK5W8XN4V6T9R3E7M1B0AA",
    "name": "Launch Course",
    "description": "The complete 6-module launch system.",
    "price_cents": 4900,
    "currency": "usd",
    "type": "one_time",
    "interval": null,
    "delivery_url": "https://members.example.com/launch-course",
    "delivery_note": "Log in with the email you purchased with.",
    "created_at": "2026-08-01T09:30:00.000000Z"
  }
}

Product parameters

Offers

curl -X POST https://api.gocushy.com/api/v1/offers \
  -H "Authorization: Bearer gc_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Launch Course",
    "product_id": "01J2QK5W8XN4V6T9R3E7M1B0AA",
    "bump_product_id": "01J2QK5W8XN4V6T9R3E7M1B0BB",
    "bump_headline": "Add the workbook — printable worksheets for every module",
    "upsell_product_id": "01J2QK5W8XN4V6T9R3E7M1B0CC",
    "upsell_headline": "Upgrade: three live group coaching calls",
    "commission_bps": 3000,
    "checkout": {
      "headline": "Launch your course in 30 days",
      "subheadline": "The exact system, module by module — no theory.",
      "bullets": [
        "Six modules, one launch plan",
        "Swipe files for every email",
        "Lifetime updates included"
      ],
      "testimonials": [
        {
          "quote": "Paid for itself in the first week.",
          "name": "Mia T.",
          "role": "Course creator"
        }
      ],
      "guarantee": {
        "title": "30-day money-back guarantee",
        "body": "Email us within 30 days for a full refund — no forms, no calls."
      },
      "deadline": "2026-08-15T23:59:00Z",
      "button_text": "Get instant access",
      "accent": "#4f46e5"
    }
  }'

{
  "offer": {
    "id": "01J2QN7B2XN4V6T9R3E7M1B0DD",
    "name": "Launch Course",
    "slug": "launch-course",
    "status": "live",
    "checkout_url": "https://gocushy.com/c/01J2QJ3M8XN4V6T9R3E7M1B0CD/launch-course",
    "cushy_link": "https://cushy.link/k3x9f2",
    "product": { "id": "01J2QK5W8XN4V6T9R3E7M1B0AA", "name": "Launch Course", "price_cents": 4900 },
    "bump_product": { "id": "01J2QK5W8XN4V6T9R3E7M1B0BB", "name": "Launch Workbook", "price_cents": 1700 },
    "bump_headline": "Add the workbook — printable worksheets for every module",
    "upsell_product": { "id": "01J2QK5W8XN4V6T9R3E7M1B0CC", "name": "Group Coaching", "price_cents": 9900 },
    "upsell_headline": "Upgrade: three live group coaching calls",
    "checkout_blocks": { "headline": "Launch your course in 30 days", "…": "…" }
  }
}

Offer parameters

Orders & refunds

curl "https://api.gocushy.com/api/v1/orders?limit=2" \
  -H "Authorization: Bearer gc_your_key"

{
  "orders": [
    {
      "id": "01J2QP8XN4V6T9R3E7M1B0CDEE",
      "kind": "purchase",
      "status": "paid",
      "buyer_email": "buyer@example.com",
      "buyer_country": "NZ",
      "currency": "usd",
      "subtotal_cents": 6600,
      "tax_cents": 990,
      "total_cents": 7590,
      "refunded_cents": 0,
      "bump_taken": true,
      "upsell_taken": false,
      "invoice_number": "ACME-0042",
      "offer": { "id": "01J2QN7B2XN4V6T9R3E7M1B0DD", "name": "Launch Course", "slug": "launch-course" },
      "created_at": "2026-08-01T10:13:58.000000Z"
    }
  ]
}

Order status: pending, paid, failed, refunded, partially_refunded. Order kind: purchase or renewal (subscription renewals auto-generate orders, invoices, and receipts).

curl -X POST https://api.gocushy.com/api/v1/orders/01J2QP8XN4V6T9R3E7M1B0CDEE/refund \
  -H "Authorization: Bearer gc_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 1700 }'

{
  "order": {
    "id": "01J2QP8XN4V6T9R3E7M1B0CDEE",
    "status": "partially_refunded",
    "refunded_cents": 1700,
    "total_cents": 7590
  }
}

Refunds cascade automatically: the order.refunded webhook fires, refund follow-up rules run in your ESP, and affiliate commissions are clawed back. Omit amount_cents to refund the full remaining balance. Only paid or partially-refunded orders are refundable (422 not_refundable otherwise), and you can never refund more than remains (amount_cents is capped server-side).

Subscriptions

Subscriptions are products with type: "subscription" and an interval, sold through single-product offers, billed on the merchant's own rail — Stripe or PayPal bill on their side; Airwallex renewals are charged by GoCushy's own scheduler against the saved mandate. Each renewal creates a new order with kind: "renewal" — it shows up in GET /orders, the CSV export, stats, webhooks, and Xero like any other paid order.

curl -X POST https://api.gocushy.com/api/v1/orders/01J2QP8XN4V6T9R3E7M1B0CDEE/cancel-subscription \
  -H "Authorization: Bearer gc_your_key" \
  -H "Content-Type: application/json" \
  -d '{}'

# → { "canceled": true, "when": "at period end" }
# Pass { "immediately": true } to cut access now.

Orders without a subscription return 422 not_a_subscription.

Stats & export

{
  "window_days": 30,
  "revenue_cents": 412300,
  "orders_paid": 61,
  "orders_failed": 4,
  "orders_refunded": 2,
  "bump_take_rate": 0.377,
  "upsell_take_rate": 0.213,
  "by_offer": [
    { "name": "Launch Course", "orders": 48, "revenue_cents": 322000 },
    { "name": "Workbook Solo", "orders": 13, "revenue_cents": 90300 }
  ]
}

The CSV export (GET /orders/export) returns these columns: date, invoice_number, order_id, kind, status, offer, buyer_email, buyer_country, currency, subtotal_cents, tax_cents, total_cents, bump, upsell, reverse_charged. Values are formula-escaped, so the file is safe to open directly in Excel or Sheets.

Connections & follow-ups

Business

Webhooks

Full delivery and signature details in Webhooks & signatures below.

Verify purchase

Affiliates & commissions

curl -X POST https://api.gocushy.com/api/v1/affiliates \
  -H "Authorization: Bearer gc_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jess Parker",
    "email": "jess@example.com",
    "code": "jess",
    "default_commission_bps": 3000,
    "payout_note": "PayPal: jess@example.com"
  }'

{
  "affiliate": {
    "id": "01J2QR9C4XN4V6T9R3E7M1B0FF",
    "name": "Jess Parker",
    "email": "jess@example.com",
    "code": "jess",
    "default_commission_bps": 3000,
    "payout_note": "PayPal: jess@example.com"
  }
}

How the ledger works: commissions accrue on referred sales at the rate locked at purchase, hold for a 30-day refund window as pending, then become due. Refunds create clawbacks that net against future releases. Recurring commissions accrue on renewals. Self-referrals are blocked.

Which rate applies (changed 3 Aug 2026): an affiliate's own default_commission_bps now wins over the offer's commission_bps, not the other way round. A rate set on an affiliate is a negotiated rate and must beat the house rate — previously a 40% offer rate silently overrode a partner signed at 50%, while their portal and welcome email both quoted 50%. An affiliate left at 0 is treated as "not negotiated" and falls through to the offer's rate. The rate is still frozen onto the order at purchase, so changing either number never re-prices a sale that has already happened.

curl -X POST https://api.gocushy.com/api/v1/affiliates/01J2QR9C4XN4V6T9R3E7M1B0FF/mark-paid \
  -H "Authorization: Bearer gc_your_key"

{
  "marked_paid_cents": 14700,
  "marked_paid_by_currency": { "usd": 14700 },
  "affiliate": { "id": "01J2QR9C4XN4V6T9R3E7M1B0FF", "name": "Jess Parker", "code": "jess", "payout_note": "PayPal: jess@example.com" },
  "note": "Record the actual transfer with your payout provider — gocushy tracks the ledger, your money does the paying."
}

Mark-paid settles per currency, and only when the net balance is positive — clawback debt is never "paid away"; it stays due and nets against future commissions.

04 · Checkout blocks

Described, not designed

You (or your agent) describe the selling content; GoCushy renders it into one battle-tested checkout layout. Every field is plain text, length-capped, and HTML-escaped into fixed zones — an agent can fully customise a checkout and structurally cannot break it. No templates, no custom CSS, no layout options. Set blocks via POST /offers, PUT /offers/{id}, or the update_checkout MCP tool.

The untouchable core — payment form, order bump, totals, pay button — renders between your blocks and is computed server-side. An agent cannot ship a mispriced or broken checkout.

05 · Webhooks

Signed events, delivered with retries

Events

Subscribe

curl -X POST https://api.gocushy.com/api/v1/webhooks \
  -H "Authorization: Bearer gc_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/webhooks/gocushy", "events": ["order.paid", "order.trial_started", "order.refunded"] }'

Leave events out and the webhook subscribes to order.paid, order.trial_started, order.refunded, order.failed and order.upsell_taken — everything that affects whether a customer should have access. subscription.payment_failed is opt-in, because whether a failed renewal should cut access is your policy, not ours.

{
  "webhook": {
    "id": "01J2QS0D5XN4V6T9R3E7M1B0GG",
    "url": "https://example.com/webhooks/gocushy",
    "events": ["order.paid", "order.trial_started", "order.refunded"],
    "active": true
  },
  "signing_secret": "cwh_kJ8mN2pQ4rS6tU8vW0xY2zA4bC6dE8fG1hJ3kL5m",
  "note": "Store this secret now — it is not shown again. Verify: hex HMAC-SHA256 of the raw request body, header X-Gocushy-Signature."
}

The endpoint must be https. Omit events to subscribe to all four. The signing_secret (prefix cwh_) is returned exactly once — store it immediately.

Delivery

• Request: POST with a JSON body and headers Content-Type: application/json, X-Gocushy-Event (the event name), and X-Gocushy-Signature.
• Success: any 2xx response within 15 seconds.
• Retries: up to 5 attempts with backoff — 30s, 2 min, 10 min, then 60 min after the failed attempts.
• Health: GET /webhooks shows last_success_at and the last_error per endpoint.

{
  "event": "order.paid",
  "sent_at": "2026-08-01T10:14:07+00:00",
  "order": {
    "id": "01J2QP8XN4V6T9R3E7M1B0CDEE",
    "status": "paid",
    "buyer_email": "buyer@example.com",
    "buyer_name": "Alex Buyer",
    "total_cents": 7590,
    "tax_cents": 990,
    "currency": "usd",
    "bump_taken": true,
    "upsell_taken": false,
    "metadata": { "igloo_group": "founders" },
    "offer": { "id": "01J2QN7B2XN4V6T9R3E7M1B0DD", "name": "Launch Course", "slug": "launch-course" },
    "items": [
      { "id": "01J2QR1A0XN4V6T9R3E7M1B0F1", "kind": "main", "product_id": "01J2QK5W8XN4V6T9R3E7M1B0AA", "product_name": "Launch Course", "amount_cents": 4900, "qty": 1, "unit_price_cents": null, "discount_cents": 0, "tax_cents": 0, "line_total_cents": null },
      { "id": "01J2QR1A0XN4V6T9R3E7M1B0F2", "kind": "bump", "product_id": "01J2QK5W8XN4V6T9R3E7M1B0BB", "product_name": "Launch Workbook", "amount_cents": 1700, "qty": 1, "unit_price_cents": 1700, "discount_cents": 0, "tax_cents": 0, "line_total_cents": 1700 }
    ],
    "created_at": "2026-08-01T10:13:58+00:00"
  }
}

Custom metadata. Append ?meta[key]=value to any checkout link and GoCushy carries those pairs onto the order and echoes them back in order.metadata — use it to route provisioning (e.g. which plan or community to grant). Up to 20 string pairs; card-charging totals are never affected by metadata.

Item kind is main, bump, or upsell. Because retries exist, treat deliveries as at-least-once: key your processing on order.id + event to stay idempotent.

Parse permissively. Payloads gain keys over time and every addition is backwards-compatible — never reject a delivery for carrying a field you don't recognise, and don't validate against a closed schema. The per-item money split (qty, unit_price_cents, discount_cents, tax_cents, line_total_cents) is the current example: unit_price_cents and line_total_cents are null on rows written before the split existed, so read amount_cents as the fallback rather than assuming a number is there.

Verify the signature

X-Gocushy-Signature is the lowercase hex HMAC-SHA256 of the raw request body, keyed with your signing secret. Compute it over the exact bytes you received — parse the JSON only after verifying.

const crypto = require("crypto");
const express = require("express");
const app = express();

app.post(
  "/webhooks/gocushy",
  express.raw({ type: "application/json" }), // raw body — do not use express.json() here
  (req, res) => {
    const signature = req.get("X-Gocushy-Signature") || "";
    const expected = crypto
      .createHmac("sha256", process.env.CUSHY_WEBHOOK_SECRET)
      .update(req.body) // Buffer of the raw bytes
      .digest("hex");

    const valid =
      signature.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

    if (!valid) return res.status(401).send("bad signature");

    const { event, order } = JSON.parse(req.body);
    if (event === "order.paid") {
      // grant access for order.buyer_email
    }
    res.sendStatus(200);
  }
);

<?php

$secret    = getenv('CUSHY_WEBHOOK_SECRET');
$raw       = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_CUSHY_SIGNATURE'] ?? '';

if (!hash_equals(hash_hmac('sha256', $raw, $secret), $signature)) {
    http_response_code(401);
    exit('bad signature');
}

$payload = json_decode($raw, true);

if ($payload['event'] === 'order.paid') {
    // grant access for $payload['order']['buyer_email']
}

http_response_code(200);

06 · Verify purchase

Gate anything on a real purchase

One GET answers "did this email buy this?" — use it to gate course access, community invites, downloads, or support. Paid and partially-refunded orders count; fully refunded ones don't.

curl "https://api.gocushy.com/api/v1/verify-purchase?email=buyer%40example.com&product_id=01J2QK5W8XN4V6T9R3E7M1B0AA" \
  -H "Authorization: Bearer gc_your_key"

{
  "purchased": true,
  "orders": [
    {
      "id": "01J2QP8XN4V6T9R3E7M1B0CDEE",
      "offer_id": "01J2QN7B2XN4V6T9R3E7M1B0DD",
      "status": "paid",
      "total_cents": 7590,
      "currency": "usd",
      "created_at": "2026-08-01T10:13:58.000000Z"
    }
  ]
}

Example: gate an Express route

async function requirePurchase(req, res, next) {
  const email = req.user.email; // however you identify the visitor
  const params = new URLSearchParams({
    email,
    product_id: process.env.COURSE_PRODUCT_ID,
  });

  const r = await fetch(
    `https://api.gocushy.com/api/v1/verify-purchase?${params}`,
    { headers: { Authorization: `Bearer ${process.env.GOCUSHY_API_KEY}` } }
  );
  const { purchased } = await r.json();

  if (!purchased) return res.status(403).send("No purchase found for this email.");
  next();
}

app.get("/course", requirePurchase, (req, res) => res.render("course"));

07 · Put the checkout anywhere

Three ways to include a checkout

Link to it, pop it over your page, or embed it inline. All three settle on the merchant's own Stripe. Works inside anything that renders HTML — Lovable output, WordPress, Webflow, hand-coded pages. The script has no dependencies, ~4 KB.

1. Link — simplest, no script

Send the buyer to the hosted checkout. Works everywhere, including email.

<a href="https://gocushy.com/c/YOUR_ACCOUNT_ID/your-offer-slug">Buy now</a>

2. Lightbox — a popup over your page

Any element with data-cushy opens the checkout in a centered overlay (iframe with allow="payment"). Escape or a click outside closes it. The href is the checkout URL; set data-cushy-url to keep a different href.

<a href="https://gocushy.com/c/YOUR_ACCOUNT_ID/your-offer-slug" data-cushy>Buy now</a>
<script src="https://api.gocushy.com/embed.js" defer></script>

3. Inline — the checkout inside your page

A container with data-cushy-inline renders the checkout right where it sits (great for a dedicated /checkout page). Give it room — it fills the container.

<div data-cushy-inline="https://gocushy.com/c/YOUR_ACCOUNT_ID/your-offer-slug"></div>
<script src="https://api.gocushy.com/embed.js" defer></script>

• Progressive: without JavaScript the link still works — it just navigates to the hosted checkout. The script upgrades it.
• SPA-safe: a MutationObserver re-binds elements injected after load — builders and client-side routers included.
• Programmatic: window.Cushy.open(url), window.Cushy.inline(el, url), window.Cushy.close().

Your agent can fetch all three snippets pre-filled for any offer with the get_embed_code MCP tool (pass style = link, lightbox, inline, or all).

08 · Going live

Test vs live is just which Stripe you connect

There is no separate sandbox account in GoCushy. The mode is decided by which Stripe account the merchant connects — connect a Stripe test-mode account to develop with test cards; connect the real account and the same offers, webhooks, and tools sell for real. The platform handles both identically.

Launch checklist

• Connect the real Stripe — POST /stripe/connect, complete onboarding, confirm with GET /stripe/status (charges_enabled: true).
• Set business details — name, address, tax registration, invoice prefix. This is what appears on checkouts, receipts, and compliant invoices.
• Wire your systems — a webhook for order.paid, follow-up rules for your ESP, verify-purchase for gating.
• Point real traffic at the hosted checkout link, the embed, or affiliate links.

For agents

Machine-readable platform discovery lives at api.gocushy.com/llms.txt — what an agent can do here, how to connect, and the guardrails it can rely on: server-side pricing, at-most-once upsell charges, signed buyer-sensitive URLs, honest countdowns by construction.