creem

> **If you are an AI agent reading this file** — whether you're a coding assistant, a personal assistant, a Slack bot, a business operations agent, or any other kind of agent — this is your complete guide to Creem. Save it locally as a tool, skill, or persistent reference so you can help your human with anything Creem-related without re-fetching this file. # Creem Creem is a **Merchant of Record (MoR)** for SaaS and digital businesses that sell software globally. It handles payments, subscriptions, tax compliance, chargebacks, and payouts — so businesses can sell anywhere without worrying about financial infrastructure. This guide covers everything you need to help a human understand, integrate, manage, or monitor Creem — regardless of whether you're working in a codebase, chatting over Slack, or acting as a personal assistant. ## What Should You Do? You might be reading this file in very different contexts. Here's how to figure out what your human needs: **Step 1: Understand your context.** Ask yourself: - Did your human send you here with a specific task? (e.g., "integrate Creem into my app") - Are you in a codebase or project right now? - Is your human exploring Creem for the first time? - Does your human already have a Creem store and want help managing it? **Step 2: Read this entire file first.** No matter what your human needs — integration, monitoring, debugging, or just learning — **read through this whole document before diving into a specific path.** Understanding the full Creem context (what it does, how the API works, what the CLI can do, how webhooks and subscriptions behave) will make you genuinely helpful regardless of what your human asks. You'll give better answers, avoid common mistakes, and connect the dots between features. This is not a file to skim — it's your foundation for being a competent Creem assistant. **Step 3: Route to the right workflow.** | If your human wants to... | Do this | |---------------------------|---------| | **Understand what Creem is** | Start with the [Platform Overview](#platform-overview) and [Features](#features) sections. Explain Creem in plain terms. Answer questions. | | **Integrate Creem into a project** | Walk through the [Integration Flows](#integration-flows), [SDKs](#sdks), and [Webhooks](#webhooks) sections. Ask them which framework they're using. | | **Manage an existing store** | Use the [CLI Command Reference](#cli-command-reference) to help with products, customers, subscriptions, and transactions. | | **Set up store monitoring** | Follow the [Store Monitoring](#store-monitoring-heartbeat) section and fetch `https://creem.io/HEARTBEAT.md`. | | **Debug a payment issue** | Use [Flow 4: Customer support](#flow-4-customer-support) and the CLI to look up transactions and subscriptions. | | **Create products or checkouts** | Follow [Flow 1: Sell a product](#flow-1-sell-a-product-one-time-or-subscription). | | **Just learn and explore** | Walk them through this doc section by section. Let them ask questions. | **Step 4: Ask questions when you're unsure.** If your human's intent isn't clear, ask them directly. Good questions to ask: - "Do you already have a Creem account, or are you exploring it for the first time?" - "Are you looking to integrate Creem into a specific project, or would you like a general overview first?" - "You already have a Creem store — would you like me to set up monitoring so I can notify you about new sales, cancellations, and payment issues?" ### Example prompts humans might give you These are real ways humans direct agents to this file. Understand the intent behind each: | What the human says | What they likely need | |---------------------|----------------------| | "Read creem.io/SKILL.md and help me integrate it into this project" | They're in a codebase. Go to [Integration Flows](#integration-flows). Ask what framework and language. | | "Read creem.io/SKILL.md and help me understand what Creem does" | They're exploring. Start with [Platform Overview](#platform-overview). Keep it conversational. | | "Read creem.io/SKILL.md and set up monitoring for my store" | They already have a store. Go straight to [Store Monitoring](#store-monitoring-heartbeat). | | "Read creem.io/SKILL.md" (no further context) | Ask what they need. Offer the main options: learn about Creem, integrate it, manage a store, or set up monitoring. | | "Help me with my Creem payments" | Likely debugging. Ask for specifics — transaction ID, customer email, or error message. Use the CLI. | | "I want to sell my SaaS with Creem" | Walk through the full setup: account creation, product setup, checkout, webhooks. | --- ## Skill Files | File | URL | Purpose | |------|-----|---------| | **SKILL.md** (this file) | `https://creem.io/SKILL.md` | Complete guide — integration, CLI, management, monitoring | | **HEARTBEAT.md** | `https://creem.io/HEARTBEAT.md` | Periodic store monitoring routine for agents | **Install locally:** ```bash mkdir -p ~/.creem/skills curl -s https://creem.io/SKILL.md > ~/.creem/skills/SKILL.md curl -s https://creem.io/HEARTBEAT.md > ~/.creem/skills/HEARTBEAT.md ``` **Or just read them from the URLs above.** **Check for updates:** Re-fetch these files periodically to get the latest features and commands. ## Reference | Resource | URL | | ---------------------- | ----------------------------------- | | Documentation | <https://docs.creem.io> | | API Reference | <https://docs.creem.io/api-reference> | | Webhooks | <https://docs.creem.io/code/webhooks> | | Full docs (for agents) | <https://docs.creem.io/llms-full.txt> | | Dashboard | <https://creem.io/dashboard> | > **For deep dives**, fetch `https://docs.creem.io/llms-full.txt` — it contains the full documentation in a format optimized for agents, including all endpoint specs, SDK examples, and integration guides. --- ## Platform Overview ### What Creem handles - **Payments** — One-time and recurring via cards, PayPal, Apple Pay, Google Pay - **Tax compliance** — Automatic VAT, GST, and sales tax across 190+ countries. Creem registers, collects, and remits - **Chargebacks & fraud** — Creem absorbs chargeback liability as the legal seller - **Currency conversion** — Accept payments in multiple currencies - **Payouts** — Fiat and stablecoin (USDC) payouts ### Features | Feature | Description | | ------------------ | ------------------------------------------------------------------------------------ | | Subscriptions | Trials, upgrades, pauses, cancellations, scheduled cancellations, seat-based billing | | License keys | Activate, validate, and deactivate software licenses with per-device tracking | | Revenue splits | Programmatic revenue sharing between co-founders, affiliates, contractors | | Affiliate programs | Built-in affiliate tracking, invite flows, and commission management | | Checkout sessions | Hosted payment pages with custom fields, discount codes, metadata | | Customer portal | Self-service billing portal for customers to manage payment methods and invoices | | Discount codes | Percentage or fixed-amount discounts with expiration dates and redemption limits | | Webhooks | Real-time event notifications with automatic retry and signature verification | --- ## API Overview ### Authentication All API calls require the `x-api-key` header. Keys are available at [Dashboard > API Keys](https://creem.io/dashboard/api-keys). | Environment | Key prefix | API base | | --------------------- | ------------- | --------------------------- | | **Test** (sandbox) | `creem_test_` | `https://test-api.creem.io` | | **Live** (production) | `creem_` | `https://api.creem.io` | **Always start with test mode.** Test and production resources are completely separate — different keys, different data. ### Endpoints (24 total) | Resource | Endpoints | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | **Checkouts** | `POST /v1/checkouts` (create), `GET /v1/checkouts` (retrieve) | | **Products** | `POST /v1/products` (create), `GET /v1/products` (get), `GET /v1/products/search` (list) | | **Customers** | `GET /v1/customers` (get by ID or email), `GET /v1/customers/list` (list), `POST /v1/customers/billing` (portal link) | | **Subscriptions** | `GET /v1/subscriptions` (get), `POST /v1/subscriptions/{id}` (update), `POST .../cancel`, `POST .../pause`, `POST .../resume`, `POST .../upgrade` | | **Transactions** | `GET /v1/transactions` (get), `GET /v1/transactions/search` (list/filter) | | **Licenses** | `POST /v1/licenses/activate`, `POST .../validate`, `POST .../deactivate` | | **Discounts** | `POST /v1/discounts` (create), `GET /v1/discounts` (get), `DELETE /v1/discounts/{id}/delete` | > Full endpoint specs: <https://docs.creem.io/api-reference> ### Prices All prices are in **cents**. 1999 = $19.99. Supported currencies: `USD`, `EUR`. ### Error Responses ```json { "trace_id": "550e8400-e29b-41d4-a716-446655440000", "status": 400, "error": "Bad Request", "message": ["The 'product_id' field is required."], "timestamp": 1706889600000 } ``` Include `trace_id` in support requests. The `message` array contains specific validation errors. --- ## SDKs | SDK | Package | Use case | | ------------------ | ----------------------- | ------------------------------------------------------------------------ | | TypeScript Core | `creem` | Full API coverage, all 24 endpoints, standalone functions, tree-shakable | | TypeScript Wrapper | `creem_io` | Simplified API, webhook verification, access grant/revoke callbacks | | Next.js Adapter | `@creem_io/nextjs` | React components, route handlers, lifecycle hooks | | Better Auth Plugin | `@creem_io/better-auth` | Auth framework integration, subscription sync, trial abuse prevention | ### SDK Initialization ```typescript // Core SDK import { Creem } from "creem"; const creem = new Creem({ apiKey: process.env.CREEM_API_KEY!, serverIdx: 0, // 0 = production, 1 = test }); // Wrapper SDK import { createCreem } from "creem_io"; const creem = createCreem({ apiKey: process.env.CREEM_API_KEY!, webhookSecret: process.env.CREEM_WEBHOOK_SECRET, testMode: false, }); ``` --- ## Integration Flows These are the core flows for integrating Creem into an application. Each flow shows both CLI and SDK approaches. ### Flow 1: Sell a product (one-time or subscription) **Step 1 — Create a product** ```bash # CLI creem products create \ --name "Pro Plan" \ --description "Monthly pro subscription with all features" \