Source: https://commish.sh/docs

Developer documentation

# Connect your product to creator partnerships.

Capture creator referrals and connect eligible purchases to earnings. Use the SDK directly, or paste one prompt into your coding agent.

[Read the setup steps](https://commish.sh/docs#getting-started) [View OpenAPI](https://commish.sh/openapi.json)

## Install with your coding agent

Paste this prompt into any coding agent that can run terminal commands. The agent plans setup in TEST mode and brings you the business choices and approval link.

Prompt: ``Set up Commish in this repository: run `curl -fsSL https://commish.sh/docs.md` and follow the agent brief it prints.``

server.ts · Stripe purchase receipt

```
import { Commish } from "@commish/sdk";

const commish = new Commish({
  secretKey: process.env.COMMISH_SECRET_KEY!,
});

// After an attributed one-time Stripe TEST Checkout:
export async function readPurchase(paymentIntentId: string) {
  const receipt = await commish.conversions.lookup(paymentIntentId);
  // null means processing may still be underway.
  return receipt.data;
}
```

Capture the referral before Checkout and use `withCommishStripeMetadata` from `@commish/next` in your server Checkout handler. Look up a one-time purchase by its PaymentIntent ID, not its Checkout Session ID. Stripe processing is asynchronous: use bounded backoff or signed Commish events before deciding a conversion is missing. For subscriptions, read the conversion identified by the signed `conversion.created` event.

## Get started in TEST mode

Start with the published CLI. You do not need a Commish account or API key to plan setup. Create your business account through the CLI approval URL when requested.

Use the CLI for workspace and integration provisioning. Use the browser for required authentication and consent. If a CLI error or repository policy blocks setup, report that blocker before continuing; dashboard clicks are not a provisioning fallback.

Review the brief your agent follows

Brief for your coding agent

- Integrate Commish into this repository using @commish/sdk@0.5.0.

- Read https://commish.sh/docs.md and the setup schema at https://app.commish.sh/api/cli/setup/capabilities first. If you cannot read a source, say so and request its contents.

- Inspect the framework, package manager and repository instructions. Use @commish/next@0.5.0 only with Next >=16.3.8 <17 and React >=19.2.8 <20.

- Run commish setup --plan --json before signup or provisioning. Collect missing business choices together; do not invent commission terms, eligible products, consent or mode.

- Use the CLI for provisioning. Present approvalUrl and pairingCode for the person to complete browser authentication and consent. Stop and report blockers; do not substitute dashboard automation.

- Keep credentials in the approved private storage and out of chat, logs, Git and browser code. Resolve any policy against local credential storage before provisioning.

- Keep activation and participant acceptance explicit. Start in TEST; LIVE requires explicit selection and current eligibility.

- For Stripe Checkout, capture the referral first and preserve it in Checkout metadata with the adapter. Let Commish record purchases and refunds from Stripe events; do not also submit them through direct conversion or refund writes. Read the recorded conversion and commission to verify the integration.

- For the attributed TEST conversion, ask the workspace owner to add the creator role to their own account at https://app.commish.sh/account/roles?role=creator if they do not hold it yet, then create a test partnership for their own account from the program's Integration tab in the Commish dashboard and use the TEST referral link it shows. Do not invite a separate creator email to test.

- Report package installation, configuration verification and an attributed TEST conversion as separate milestones, with evidence and any remaining actions.

- Step 1 **Install the stable SDK** Use Node 22 or later and your repository's package manager. For pnpm, run pnpm add --save-exact @commish/sdk@0.5.0 and keep your consumer lockfile. Add @commish/next@0.5.0 only for a compatible App Router app: Next >=16.3.8 <17 and React >=19.2.8 <20. Other apps can use the core SDK with agent-written wiring. If your repository enforces a minimum package age, use the newest release that satisfies it; Commish does not require the latest version. Package versions do not determine TEST or LIVE eligibility.

- Step 2 **Plan before signup** Run pnpm exec commish setup --plan --json. This planning step makes no network requests and writes no files. It reports missing inputs by field and identifies framework and package-manager hints. Collect missing business choices together, then create non-secret commish.setup.json. Explicitly choose eligible Stripe products, commission, recurrence, per-sale cap, disclosure, webhook, Stripe connection and hosted participant consent. An empty eligible-product list means all Stripe products. Request a new workspace by name and slug, choose an existing one by ID, or select one during approval.

- Step 3 **Authorize CLI setup** Run the setup command below. Present approvalUrl and pairingCode from its authorization_required JSON event on stderr. Open that approval URL first; new customers sign up, verify email and enroll or verify an authenticator from there. Confirm the code, review the proposed business choices, and approve the workspace, mode and operations. The waiting CLI then provisions the approved resources. --no-open lets the agent present the link; --non-interactive still requires human browser consent.

- Step 4 **Publish the destination proof** Publish the generated proof file at the HTTPS URL printed by the CLI. Setup verifies ownership, creates scoped credentials and configures the program, terms and optional webhook. It preserves existing files and saves progress. Rerun the same command and configuration after an interruption.

- Step 5 **Wire your application** For Next.js, run pnpm exec commish-next --json to inspect the installation plan, then add --write to install the attribution route and provider files. Follow its next steps to update your existing layout and Checkout handler. Customized files are preserved. Other frameworks can use @commish/sdk directly.

- Step 6 **Configure the TEST integration** Complete the Stripe test connection in the browser when requested; the CLI resumes afterward or on a fresh authorized run. Follow its remaining readiness actions and activate the program in Commish. To rehearse the attributed TEST conversion, the workspace owner adds the creator role to their own account if they do not hold it yet, then creates a test partnership for their own account from the program's Integration tab; no second email or creator invitation is needed. Invite creators once that conversion and its commission are visible. Creating keys and a draft program does not verify a transaction.

terminal

```
pnpm exec commish setup --plan --json

# After supplying missing choices in commish.setup.json:
pnpm exec commish setup --config commish.setup.json \
  --mode test --no-open --json
```

Setup stores owner-only credentials and progress under the ignored .commish/setup directory. It prints file paths instead of secrets. JSON progress goes to stderr and one final receipt goes to stdout. With your environment configured, run pnpm exec commish verify --json to check program access and mode. Configuration verified is separate from integration verified: complete an attributed TEST conversion and inspect its commission before treating your integration as verified.

An API key is your application's password for Commish. Setup saves it in a private local file so the application can use it later. A policy that forbids all secret persistence blocks this storage; resolve that policy before running setup. Private storage is different from exposing credentials in Git, logs or browser code. Supply the files through your existing secret manager or environment runner; setup does not deploy them. Planning saves no credentials.

A pending approval lasts up to one hour; approved authority lasts at most ten minutes. Rerun the same command and configuration after an interruption. Program activation remains a separate action in Commish. Setup opens a focused Stripe connection page for the approved business and mode; complete Stripe consent there before resuming. Legacy setup sessions may use the business settings handoff.

Use a separate workspace server credential for workspace-wide webhook delivery diagnostics. Your API base URL includes /api/v1. Keep secret keys and webhook signing secrets out of browser props and NEXT_PUBLIC_* variables. TEST setup does not grant LIVE approval.

[Read the SDK 0.5.0 setup and recovery guide](https://github.com/oftring-ventures/commish-sdk/blob/v0.5.0/packages/sdk/README.md#set-up-from-your-repository)

[Setup capabilities and configuration JSON Schema](https://app.commish.sh/api/cli/setup/capabilities) · [Create a business account](https://app.commish.sh/sign-up?role=business) (account access; begin CLI setup through its approval URL).

Published packages: [@commish/sdk on npm](https://www.npmjs.com/package/@commish/sdk) and [@commish/next on npm](https://www.npmjs.com/package/@commish/next).

Integration lifecycle

## Keep the payment decision in your stack.

Your application controls Checkout. For a connected Stripe integration, Commish records eligible purchases and refunds from Stripe events. Do not submit the same Stripe purchase or refund through the direct conversion or refund API.

For a provider-neutral integration, report the sale once with its captured attribution receipt, your stable external customer ID, and the original payment timestamp. Persist the request and idempotency key together and reuse both unchanged on retries. See the SDK guide for the direct-write example.

- 01 **Define the creator offer** Set the creator offer, attribution policy, and commission rules in Commish.

- 02 **Capture the referral** Use a signed referral token and the browser or Next.js integration surface.

- 03 **Connect the purchase** For Stripe, attach the captured attribution to Checkout metadata and let Commish record the purchase from Stripe events. Use direct conversion writes only for a separate provider-neutral integration.

- 04 **Inspect earnings and status** Inspect attribution, calculated commission, and resulting status in one workflow.

Available surfaces

## Use the contract that fits your stack.

Commish provides server, browser referral-capture, and Next.js integration surfaces. The OpenAPI document is the machine-readable source of truth for the HTTP contract.

`@commish/sdk`

Server SDK for conversions, customers, invitations, and refunds.

`@commish/sdk/browser`

Browser referral capture for signed Commish links.

`@commish/next`

Next.js attribution handler and payment metadata helpers.

`@commish/next/react`

A provider that captures referrals across App Router navigation.

## TEST and LIVE referrals

Start with TEST

Use TEST keys and a link such as `/p/test/your-program/mary` to try the integration. TEST activity does not create real payments. Older links without a mode, such as `/p/your-program/mary`, stay TEST-only.

Use LIVE for real purchases

A LIVE link looks like `/p/live/your-program/mary`. It redirects to your verified HTTPS website with a signed token; your SDK captures that token using the matching LIVE publishable key. Your workspace needs LIVE access, the creator must have an active partnership with accepted terms, and their LIVE Stripe payout setup must be ready. The creator dashboard shows what is missing before offering a link to copy.

## Prefer the machine-readable contract?

- JSON OpenAPI document

- Canonical Markdown page context

[OpenAPI JSON](https://commish.sh/openapi.json) [View Markdown](https://commish.sh/docs.md)