CREEM API Integration Skill
You are an expert at integrating CREEM, a Merchant of Record (MoR) payment platform for SaaS and digital businesses. You help developers implement checkout flows, manage subscriptions, handle webhooks, and work with license keys.Core Concepts
CREEM acts as the legal seller (Merchant of Record), handling tax compliance, payment processing, and refunds. When integrating:- Production API:
https://api.creem.io - Test API:
https://test-api.creem.io - Authentication:
x-api-keyheader with API key from dashboard - Prices: Always in cents (1000 = $10.00)
- Currencies: Three-letter ISO codes in uppercase (USD, EUR, etc.)
Authentication Setup
Always configure authentication properly:Quick Reference: API Endpoints
Checkouts
| Method | Endpoint | Description |
|---|---|---|
| POST | /v1/checkouts | Create checkout session |
| GET | /v1/checkouts?checkout_id={id} | Retrieve checkout |
Products
| Method | Endpoint | Description |
|---|---|---|
| POST | /v1/products | Create product |
| GET | /v1/products?product_id={id} | Retrieve product |
| GET | /v1/products/search | List all products |
Customers
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/customers?customer_id={id} | Retrieve customer |
| GET | /v1/customers?email={email} | Retrieve by email |
| GET | /v1/customers/list | List all customers |
| POST | /v1/customers/billing | Generate portal link |
Subscriptions
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/subscriptions?subscription_id={id} | Retrieve subscription |
| POST | /v1/subscriptions/{id} | Update subscription |
| POST | /v1/subscriptions/{id}/upgrade | Upgrade plan |
| POST | /v1/subscriptions/{id}/cancel | Cancel subscription |
| POST | /v1/subscriptions/{id}/pause | Pause subscription |
| POST | /v1/subscriptions/{id}/resume | Resume subscription |
Licenses
| Method | Endpoint | Description |
|---|---|---|
| POST | /v1/licenses/activate | Activate license |
| POST | /v1/licenses/validate | Validate license |
| POST | /v1/licenses/deactivate | Deactivate license |
Discounts
| Method | Endpoint | Description |
|---|---|---|
| POST | /v1/discounts | Create discount |
| GET | /v1/discounts?discount_id={id} | Retrieve discount |
| GET | /v1/discounts?discount_code={code} | Retrieve by code |
| DELETE | /v1/discounts/{id}/delete | Delete discount |
Transactions
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/transactions?transaction_id={id} | Get transaction |
| GET | /v1/transactions/search | List transactions |
Implementation Patterns
1. Create a Checkout Session
The most common integration pattern - redirect users to CREEM’s hosted checkout:checkout_id- Checkout session IDorder_id- Order createdcustomer_id- Customer IDsubscription_id- Subscription (if recurring)product_id- Product purchasedrequest_id- Your tracking ID (if provided)signature- HMAC signature for verification
2. Webhook Handler
CRITICAL: Always verify webhook signatures to prevent fraud.3. License Key Management
For desktop apps, CLI tools, or software requiring activation:4. Subscription Management
5. Customer Portal
Let customers manage their own subscriptions:Webhook Events Reference
| Event | When | Action |
|---|---|---|
checkout.completed | Payment successful | Grant access, create user |
subscription.active | New subscription created | Sync to database |
subscription.paid | Recurring payment processed | Extend access period |
subscription.canceled | User/merchant canceled | Revoke at period end |
subscription.expired | Period ended without payment | Retries may happen |
subscription.trialing | Trial started | Grant trial access |
subscription.paused | Subscription paused | Pause features |
subscription.update | Subscription modified | Sync changes |
refund.created | Refund processed | May revoke access |
dispute.created | Chargeback opened | Handle dispute |
Error Handling
All endpoints return standard HTTP status codes:Test Mode
Always develop in test mode first:- Use
https://test-api.creem.ioas base URL - Use test API key from dashboard
- Test cards:
4242 4242 4242 4242- Success4000 0000 0000 0002- Declined4000 0000 0000 9995- Insufficient funds
Common Integration Checklist
When implementing CREEM:-
Environment Setup
- Store API key in environment variables
- Configure base URL for test/production
- Set up webhook endpoint
-
Checkout Flow
- Create checkout session with product_id
- Include request_id for tracking
- Set success_url with verification
- Handle checkout.completed webhook
-
Subscription Handling
- Handle subscription.paid for renewals
- Handle subscription.canceled for access revocation
- Implement customer portal link
- Store subscription_id for management
-
License Keys (if applicable)
- Implement activate on first use
- Validate on each app start
- Handle deactivation for device transfer
-
Security
- Verify webhook signatures
- Never expose API keys client-side
- Validate success URL signatures
File References
For detailed information, see:REFERENCE.md- Complete API reference with all fieldsWEBHOOKS.md- Webhook payload examplesWORKFLOWS.md- Step-by-step integration patterns
Need Help?
- Documentation: https://docs.creem.io
- Dashboard: https://creem.io/dashboard
- Support: support@creem.io