invitation.dev

invitation.dev / docs

docs

Developer onboarding for the referral API, remote MCP, browser tracking, and the Node client. This is a static docs surface: it does not mint keys, call the API, or provide a live demo account.

agentfeature-gated

Agent quickstart

Mint an agent-scoped key, paste the canonical MCP config, then inspect tools/list before asking an agent to create or inspect a program.

merchantstaging check

Merchant quickstart

Use an org-bound write key or the business console to create a draft, configure it, activate it, and validate one test conversion.

trackingsource + runtime

Integration paths

Install the browser tracker for referral sessions or the Node client for server-side conversions. The browser path needs a real target environment.

sdksource package

Node client

@invitation/node wraps campaign management, customer referrers, conversions, webhook delivery replay, HMAC verification, and the public directory reads.

# before you connect

Runtime gates

  • MCP requires FEATURE_AGENT_API=true; it is off by default and can return 404 when disabled.
  • Merchant campaign flows also need FEATURE_ORGS=true and FEATURE_CAMPAIGNS=true on the target web runtime.
  • Verify integrations in staging with testMode: true. Test conversions do not credit rewards or fire merchant webhooks.
  • A successful API mutation is not proof that the hosted tracker, public page, or reward path is live.

# agent quickstart

Install the MCP server

Create an API key with the agent scope, paste the config below into your MCP client, then call initialize and tools/list before using it. Merchant campaign tools require an org-bound key with write and org:campaigns.

~/.mcp.json
{
  "mcpServers": {
    "invitation": {
      "type": "http",
      "url": "https://api3.invitation.codes/api/mcp",
      "headers": {
        "Authorization": "Bearer invt_..."
      }
    }
  }
}

MCP uses streamable HTTP and one JSON-RPC message per POST. The stable endpoint is https://api3.invitation.codes/api/mcp; available tools still depend on the target deployment and feature flags.

Building an agent that earns on recommendations rather than one that manages a program? The tool-by-tool walkthrough, the disclosure requirement, and the earn loop are in the agent guide.

# merchant quickstart

Create and activate a campaign

The quickest path is the business console. The programmable path is the Node client: create a draft, update its validation settings, activate it with the returned campaign id, then provision customer referrers. Keep the campaign unactivated until the settings are reviewable.

install
pnpm add @invitation/node
# npm install @invitation/node
# yarn add @invitation/node
campaign.ts
import { InvitationNodeClient } from "@invitation/node";

const invitation = new InvitationNodeClient({
  apiKey: process.env.INVITATION_API_KEY!,
  baseUrl: "https://api3.invitation.codes",
});

const campaign = await invitation.campaigns.create({
  name: "Summer launch",
  websiteUrl: "https://example.com",
  rewardAmount: 500,
  rewardType: "fixed_coins",
  rewardTrigger: "purchase",
  doubleSided: true,
  refereeRewardAmount: 250,
});

await invitation.campaigns.activate(campaign.id);

# integrations

Choose a tracking path

Browser referral tracker

@invitation/tracker is a browser-only source package. It captures ?ref=CODE, stores the referral session in first-party cookies, and sends conversions to the API.

install
pnpm add @invitation/tracker
# npm install @invitation/tracker
# yarn add @invitation/tracker
browser.ts
import { InvitationTracker } from "@invitation/tracker";

const tracker = new InvitationTracker({ campaignId: "campaign-id" });
tracker.init();

// Verify the path without crediting rewards or firing webhooks.
await tracker.trackPurchase({
  orderId: "order_test_123",
  amount: 12900,
  currency: "USD",
  email: "customer@example.com",
  testMode: true,
});

The hosted script is https://api3.invitation.codes/api/v3/referral/tracker.js. It requires a real campaign and a deployed tracker runtime; this site does not run it.

Server-side conversion path

@invitation/node is the server-side client source package. Capture the browser session token, send a conversion with a stable order id, and verify the result in the campaign console.

conversion.ts
await invitation.conversions.track({
  campaignId: campaign.id,
  sessionToken: request.cookies.invt_session,
  conversionType: "purchase",
  email: "buyer@example.com",
  amount: 12900,
  currency: "USD",
  orderId: "order_test_123",
  testMode: true,
});

The package source is in this monorepo; registry publication and a live target are deployment concerns, not promises made by this page.

Integration status

  • SDK and tracker source packages are present; verify package publication before installing from a registry.
  • Stripe is a supported contract value, but still needs a separate staging proof of the merchant integration.
  • Shopify remains planned and is not a ready-to-run quickstart.
  • There is no public live demo or sandbox account attached to these docs.

# sdk reference

Provision participants and track conversions

Mode-2 participants

Provision your own customers as referrers without requiring them to create Invitation accounts first. Each row receives a participant URL. The participant and directory surfaces still need runtime verification on the target environment.

participants.ts
await invitation.referrers.createMany({
  campaignSlug: "summer-launch",
  customers: [
  { externalId: "cus_1001", email: "alex@example.com" },
  { externalId: "cus_1002", email: "pri@example.com", referralCode: "VIPPRI" },
  { email: "sam@example.com" },
  ],
});

const referrers = await invitation.referrers.list({ campaignSlug: "summer-launch" });
console.log(referrers[0].participantUrl); // /r/summer-launch/VIPPRI

Conversion tracking

Track purchases, signups, or custom events server-side. Capture the tracker session token and use testMode first so the integration check cannot credit rewards.

conversion.ts
await invitation.conversions.track({
  campaignId: campaign.id,
  sessionToken: request.cookies.invt_session,
  conversionType: "purchase",
  email: "buyer@example.com",
  amount: 12900,
  currency: "USD",
  orderId: "order_test_123",
  testMode: true,
});

Webhook verification

Every campaign webhook is signed with HMAC-SHA256. Store the whsec_ secret shown in the business console and verify the raw request body before processing.

webhook.ts
const event = invitation.webhooks.verify({
  rawBody: rawRequestBody,
  signature: request.headers["x-invitation-signature"],
  secret: process.env.INVITATION_WEBHOOK_SECRET!,
});

console.log(event.type); // sale.created, commission.approved, ...

# rest

Plain HTTP, market vocabulary

If you are not using MCP or the Node client, the partner REST layer at https://api3.invitation.codes/api/partner/v1 exposes the same procedures over plain HTTP. It deliberately speaks the market's vocabulary — /partners, /commissions, /track/lead, /track/sale, Bearer or Basic auth, cursor pagination — so an existing Rewardful, Tolt, FirstPromoter, or dub integration ports by changing the base URL and the key.

Full REST reference

Endpoint table, auth, request and response examples, pagination, and the complete error contract.

/docs/rest →

Same gates, same scopes

REST is a projection, not a second implementation. It is gated behind FEATURE_AGENT_API and enforces the identical key scopes — nothing is reachable over HTTP that is not reachable over MCP.

# machine readers

Start at /llms.txt and /.well-known/mcp.json. The API origin and referral manifest are also listed in the onboarding notes above. The partner REST layer serves its own OpenAPI 3.1 spec at /api/partner/v1/openapi.json — point a client generator at it directly. The existing native REST reference renders the human-readable contract without adding a Scalar dependency.