API Reference

Authentication

All API requests require authentication using an API key. Include your API key in theX-API-Keyheader.

curl -X GET "https://api.croissantlabs.com/v1/subscribers/user_123" \
  -H "X-API-Key: mx_live_your_api_key" \
  -H "Content-Type: application/json"

Base URL

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent JSON format.

{
  "error": "INVALID_RECEIPT",
  "message": "The receipt could not be validated",
  "code": 400
}

Receipts

Validate and process purchase receipts from the App Store and Google Play.

{
  "appUserId": "user_123",
  "platform": "ios",
  "receipt": "base64_encoded_receipt_data",
  "productId": "com.app.premium_monthly"
}

{
  "success": true,
  "subscriber": {
    "id": "sub_abc123",
    "appUserId": "user_123",
    "entitlements": ["premium"],
    "activeSubscriptions": [{
      "productId": "com.app.premium_monthly",
      "expiresAt": "2024-02-15T00:00:00Z",
      "isActive": true
    }]
  }
}

Subscribers

Manage subscriber data, entitlements, and subscription status.

{
  "subscriber": {
    "id": "sub_abc123",
    "appUserId": "user_123",
    "email": "user@example.com",
    "entitlements": {
      "premium": {
        "isActive": true,
        "expiresAt": "2024-02-15T00:00:00Z",
        "productId": "com.app.premium_monthly"
      }
    },
    "subscriptions": [{
      "productId": "com.app.premium_monthly",
      "status": "active",
      "platform": "ios",
      "expiresAt": "2024-02-15T00:00:00Z"
    }],
    "attributes": {
      "custom_key": "custom_value"
    }
  }
}

{
  "attributes": {
    "referral_code": "FRIEND123",
    "signup_source": "website"
  }
}

{
  "success": true,
  "attributes": {
    "referral_code": "FRIEND123",
    "signup_source": "website"
  }
}

Entitlements

Define what features users get access to with their purchases.

{
  "entitlements": [
    {
      "id": "ent_123",
      "identifier": "premium",
      "displayName": "Premium Access",
      "description": "Full access to all premium features"
    },
    {
      "id": "ent_456",
      "identifier": "pro",
      "displayName": "Pro Features",
      "description": "Advanced features for power users"
    }
  ]
}

{
  "appUserId": "user_123",
  "entitlementId": "premium",
  "expiresAt": "2024-12-31T23:59:59Z"
}

{
  "success": true,
  "entitlement": {
    "identifier": "premium",
    "isActive": true,
    "expiresAt": "2024-12-31T23:59:59Z",
    "grantedManually": true
  }
}

Offerings

Configure which products to show users on your paywall.

{
  "current": {
    "id": "offering_default",
    "identifier": "default",
    "packages": [
      {
        "id": "pkg_monthly",
        "packageType": "MONTHLY",
        "product": {
          "id": "prod_123",
          "storeProductId": "com.app.premium_monthly",
          "price": 9.99,
          "priceString": "$9.99",
          "currencyCode": "USD",
          "title": "Premium Monthly",
          "description": "Full access, billed monthly"
        }
      },
      {
        "id": "pkg_annual",
        "packageType": "ANNUAL",
        "product": {
          "id": "prod_456",
          "storeProductId": "com.app.premium_annual",
          "price": 79.99,
          "priceString": "$79.99",
          "currencyCode": "USD",
          "title": "Premium Annual",
          "description": "Full access, billed yearly (save 33%)"
        }
      }
    ]
  },
  "all": {
    "default": { /* ... */ },
    "sale_offering": { /* ... */ }
  }
}

Products

Manage products that map to App Store and Google Play products.

{
  "products": [
    {
      "id": "prod_123",
      "identifier": "premium_monthly",
      "displayName": "Premium Monthly",
      "type": "subscription",
      "storeProductIdApple": "com.app.premium_monthly",
      "storeProductIdGoogle": "premium_monthly",
      "entitlements": ["premium"]
    }
  ]
}

{
  "identifier": "premium_annual",
  "displayName": "Premium Annual",
  "type": "subscription",
  "storeProductIdApple": "com.app.premium_annual",
  "storeProductIdGoogle": "premium_annual",
  "entitlementIds": ["premium"]
}

{
  "product": {
    "id": "prod_789",
    "identifier": "premium_annual",
    "displayName": "Premium Annual",
    "type": "subscription",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Webhooks

Receive real-time notifications for subscription and purchase events.

{
  "id": "evt_123456",
  "type": "subscription.renewed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "subscriber": {
      "appUserId": "user_123",
      "email": "user@example.com"
    },
    "subscription": {
      "productId": "com.app.premium_monthly",
      "platform": "ios",
      "expiresAt": "2024-02-15T00:00:00Z"
    },
    "revenue": {
      "amount": 9.99,
      "currency": "USD"
    }
  }
}

import { verifyWebhookSignature } from '@croissantpay/react-native/server';

app.post('/webhooks/croissantpay', (req, res) => {
  const signature = req.headers['x-croissantpay-signature'];
  const isValid = verifyWebhookSignature(
    req.body,
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook
  const { type, data } = req.body;
  // ...
});

Rate Limits

API requests are rate limited based on your plan: