Skip to content

EXAMPLES.md

Latest commit

 

History

History
629 lines (513 loc) · 10.7 KB

EXAMPLES.md

File metadata and controls

629 lines (513 loc) · 10.7 KB

MCP Server Creem - Usage Examples

This document provides detailed examples of using the MCP Server for Creem.io.

Table of Contents

Setup

1. Get Your API Key

  1. Visit Creem Dashboard
  2. Click on "Developers" in the top navigation
  3. Click the eye icon to reveal your API key
  4. Copy your API key

2. Configure Environment

Create a .env file or set environment variables:

export CREEM_API_KEY="your-api-key-here"
export CREEM_TEST_MODE="true"  # Use test mode for development

Product Management

Example 1: Create a One-Time Product

{
  "name": "Premium eBook",
  "description": "Comprehensive guide to SaaS growth",
  "price": 2900,
  "currency": "USD",
  "billing_type": "one-time",
  "tax_category": "ebook",
  "image_url": "https://example.com/ebook-cover.jpg"
}

Response:

{
  "id": "prod_abc123xyz",
  "object": "product",
  "name": "Premium eBook",
  "description": "Comprehensive guide to SaaS growth",
  "price": 2900,
  "currency": "USD",
  "billing_type": "one-time",
  "status": "active",
  "created_at": "2025-11-10T12:00:00Z"
}

Example 2: Create a Monthly Subscription

{
  "name": "Pro Plan",
  "description": "Professional tier with all features",
  "price": 4900,
  "currency": "USD",
  "billing_type": "recurring",
  "billing_period": "every-month",
  "tax_category": "saas"
}

Example 3: Create an Annual Subscription

{
  "name": "Enterprise Plan",
  "description": "Annual enterprise subscription",
  "price": 49900,
  "currency": "USD",
  "billing_type": "recurring",
  "billing_period": "every-year",
  "tax_category": "saas"
}

Example 4: List All Products

{
  "page_number": 1,
  "page_size": 50
}

Checkout Sessions

Example 5: Simple Checkout

{
  "product_id": "prod_abc123xyz"
}

Response:

{
  "id": "ch_xyz789abc",
  "checkout_url": "https://creem.io/payment/prod_abc123xyz?session=ch_xyz789abc",
  "status": "pending"
}

Example 6: Checkout with Pre-filled Customer Info

{
  "product_id": "prod_abc123xyz",
  "customer_email": "customer@example.com",
  "customer_name": "John Doe",
  "success_url": "https://myapp.com/welcome"
}

Example 7: Checkout with Tracking ID and Metadata

{
  "product_id": "prod_abc123xyz",
  "request_id": "order-2025-001",
  "metadata": {
    "user_id": "user_12345",
    "plan_type": "pro",
    "source": "website",
    "campaign": "summer-sale"
  }
}

Example 8: Seat-Based Billing Checkout

{
  "product_id": "prod_abc123xyz",
  "units": 5,
  "customer_email": "team@company.com",
  "metadata": {
    "company_name": "Acme Corp",
    "team_size": 5
  }
}

Example 9: Checkout with Discount Code

{
  "product_id": "prod_abc123xyz",
  "discount_code": "LAUNCH50",
  "customer_email": "customer@example.com"
}

Subscription Management

Example 10: Get Subscription Details

{
  "subscription_id": "sub_xyz789"
}

Response:

{
  "id": "sub_xyz789",
  "object": "subscription",
  "status": "active",
  "product": {
    "id": "prod_abc123",
    "name": "Pro Plan",
    "price": 4900
  },
  "customer": {
    "id": "cust_123",
    "email": "customer@example.com"
  },
  "next_transaction_date": "2025-12-10T12:00:00Z",
  "created_at": "2025-11-10T12:00:00Z"
}

Example 11: Update Subscription Seats

First, get the subscription to find the item ID:

{
  "subscription_id": "sub_xyz789"
}

Then update the seats:

{
  "subscription_id": "sub_xyz789",
  "items": [
    {
      "id": "sitem_abc456",
      "units": 10
    }
  ]
}

Example 12: Upgrade Subscription

{
  "subscription_id": "sub_xyz789",
  "product_id": "prod_enterprise123",
  "update_behavior": "proration-charge"
}

Update Behaviors:

  • proration-charge-immediately: Charge the difference now and start new billing cycle
  • proration-charge: Add credit for unused time, charge difference on next invoice
  • proration-none: Wait until next billing cycle to switch

Example 13: Cancel Subscription

{
  "subscription_id": "sub_xyz789"
}

Customer Management

Example 14: Get Customer by Email

{
  "email": "customer@example.com"
}

Example 15: Get Customer by ID

{
  "customer_id": "cust_123456"
}

Example 16: List All Customers

{
  "page_number": 1,
  "page_size": 100
}

Example 17: Generate Customer Portal Link

{
  "customer_id": "cust_123456"
}

Response:

{
  "customer_portal_link": "https://creem.io/my-orders/login/magic-link-token"
}

License Key Management

Example 18: Activate License on First Device

{
  "key": "MYAPP-ABC123-XYZ789-DEF456",
  "instance_name": "johns-macbook-pro"
}

Response:

{
  "id": "lic_xyz123",
  "key": "MYAPP-ABC123-XYZ789-DEF456",
  "status": "active",
  "activation": 1,
  "activation_limit": 3,
  "instance": [
    {
      "id": "inst_abc789",
      "name": "johns-macbook-pro",
      "status": "active",
      "created_at": "2025-11-10T12:00:00Z"
    }
  ]
}

Example 19: Validate License on App Startup

{
  "key": "MYAPP-ABC123-XYZ789-DEF456",
  "instance_id": "inst_abc789"
}

Response:

{
  "status": "active",
  "key": "MYAPP-ABC123-XYZ789-DEF456",
  "activation": 1,
  "activation_limit": 3
}

Example 20: Deactivate License (Device Transfer)

{
  "key": "MYAPP-ABC123-XYZ789-DEF456",
  "instance_id": "inst_abc789"
}

Discount Codes

Example 21: Create Percentage Discount

{
  "code": "SUMMER50",
  "type": "percentage",
  "value": 50,
  "max_redemptions": 100,
  "expires_at": "2025-08-31T23:59:59Z"
}

Example 22: Create Fixed Amount Discount

{
  "code": "WELCOME10",
  "type": "fixed",
  "value": 1000,
  "currency": "USD",
  "max_redemptions": 500
}

Example 23: Get Discount Details

{
  "code": "SUMMER50"
}

Response:

{
  "id": "disc_xyz123",
  "code": "SUMMER50",
  "type": "percentage",
  "value": 50,
  "max_redemptions": 100,
  "redemptions": 23,
  "expires_at": "2025-08-31T23:59:59Z"
}

Example 24: Delete Discount

{
  "discount_id": "disc_xyz123"
}

Complete Workflows

Workflow 1: SaaS Subscription Flow

Step 1: Create Product

{
  "name": "Pro Plan",
  "price": 2900,
  "currency": "USD",
  "billing_type": "recurring",
  "billing_period": "every-month"
}

Step 2: Create Checkout Session

{
  "product_id": "prod_abc123",
  "customer_email": "user@example.com",
  "success_url": "https://myapp.com/onboarding",
  "metadata": {
    "user_id": "internal_user_12345"
  }
}

Step 3: Customer Pays (handled by Creem) Customer visits checkout_url and completes payment.

Step 4: Monitor via Webhooks Set up webhook to receive subscription.paid event:

{
  "eventType": "subscription.paid",
  "object": {
    "id": "sub_xyz789",
    "status": "active",
    "metadata": {
      "user_id": "internal_user_12345"
    }
  }
}

Step 5: Grant Access Use metadata to identify user and grant access in your app.

Workflow 2: Software License Management

Step 1: Customer Purchases (Product with License Key Feature)

Step 2: Customer Receives License Key License key is automatically generated: MYAPP-ABC123-XYZ789-DEF456

Step 3: Customer Activates License

{
  "key": "MYAPP-ABC123-XYZ789-DEF456",
  "instance_name": "device-12345"
}

Step 4: Validate on Each App Launch

{
  "key": "MYAPP-ABC123-XYZ789-DEF456",
  "instance_id": "inst_abc789"
}

Step 5: Transfer to New Device Deactivate old device:

{
  "key": "MYAPP-ABC123-XYZ789-DEF456",
  "instance_id": "inst_abc789"
}

Activate new device:

{
  "key": "MYAPP-ABC123-XYZ789-DEF456",
  "instance_name": "new-device-67890"
}

Workflow 3: Seat-Based Team Subscription

Step 1: Initial Purchase (5 Seats)

{
  "product_id": "prod_team_plan",
  "units": 5,
  "customer_email": "admin@company.com"
}

Step 2: Company Grows, Add More Seats

Get subscription:

{
  "subscription_id": "sub_company123"
}

Update to 10 seats:

{
  "subscription_id": "sub_company123",
  "items": [
    {
      "id": "sitem_xyz456",
      "units": 10
    }
  ]
}

Step 3: Downsize, Reduce Seats

{
  "subscription_id": "sub_company123",
  "items": [
    {
      "id": "sitem_xyz456",
      "units": 7
    }
  ]
}

Workflow 4: Product Launch with Discount

Step 1: Create Discount Code

{
  "code": "LAUNCH50",
  "type": "percentage",
  "value": 50,
  "max_redemptions": 200,
  "expires_at": "2025-12-31T23:59:59Z"
}

Step 2: Create Checkout with Discount

{
  "product_id": "prod_new_feature",
  "discount_code": "LAUNCH50",
  "customer_email": "earlybird@example.com"
}

Step 3: Monitor Usage

{
  "code": "LAUNCH50"
}

Check redemptions field to see how many times it's been used.

Testing

Using Test Mode

Set CREEM_TEST_MODE=true to use the test environment:

  • Base URL: https://test-api.creem.io
  • Test card: 4242 4242 4242 4242
  • Any CVV and future expiration date
  • No real charges are made

Test Card Numbers

Successful Payment:

  • 4242 4242 4242 4242

Use any:

  • Future expiration date
  • Any 3-digit CVV

Error Handling

Common Error Responses

Invalid API Key (401):

{
  "error": "Creem API Error (401): Unauthorized"
}

Product Not Found (404):

{
  "error": "Creem API Error (404): Product not found"
}

Invalid Parameters (400):

{
  "error": "Creem API Error (400): Missing required field: product_id"
}

Best Practices

  1. Always Use Metadata: Track internal IDs for easy reconciliation
  2. Handle Webhooks: Don't rely only on redirect URLs
  3. Test Mode First: Always test in test mode before production
  4. Store Instance IDs: Save license instance IDs for validation
  5. Monitor Subscriptions: Regularly check subscription statuses
  6. Customer Portal: Give customers self-service options
  7. Secure API Keys: Never expose API keys in client-side code

Additional Resources