Billing

Manage your subscription, view usage, and access billing resources.

Get Subscription

Retrieve current subscription details.

GET /billing/subscription

Response

{
  "success": true,
  "data": {
    "status": "active",
    "plan": "pro",
    "currentPeriodStart": "2024-01-01T00:00:00.000Z",
    "currentPeriodEnd": "2024-02-01T00:00:00.000Z",
    "cancelAtPeriodEnd": false
  }
}

Response Fields

Field	Type	Description
status	string	Subscription status (active, canceled, past_due)
plan	string	Current plan (free, pro, enterprise)
currentPeriodStart	string	Start of current billing period
currentPeriodEnd	string	End of current billing period
cancelAtPeriodEnd	boolean	Whether subscription cancels at period end

Get Usage

Retrieve current billing period usage.

GET /billing/usage

Response

{
  "success": true,
  "data": {
    "emailsUsed": 4500,
    "emailsLimit": 10000,
    "searchesUsed": 890,
    "searchesLimit": 5000,
    "storageUsed": 256000000,
    "storageLimit": 1000000000
  }
}

Usage Fields

Field	Type	Description
emailsUsed	number	Emails received this period
emailsLimit	number	Maximum emails allowed
searchesUsed	number	Search queries this period
searchesLimit	number	Maximum searches allowed
storageUsed	number	Storage used in bytes
storageLimit	number	Storage limit in bytes

Create Checkout Session

Start a subscription upgrade.

POST /billing/checkout

Request Body

{
  "plan": "pro",
  "successUrl": "https://app.momail.io/billing/success",
  "cancelUrl": "https://app.momail.io/billing/cancel"
}

Response

{
  "success": true,
  "data": {
    "url": "https://checkout.stripe.com/pay/cs_test_..."
  }
}

Redirect the user to the returned URL to complete payment.

Create Portal Session

Access the customer portal to manage payment methods and invoices.

POST /billing/portal

Request Body

{
  "returnUrl": "https://app.momail.io/settings"
}

Response

{
  "success": true,
  "data": {
    "url": "https://billing.stripe.com/session/..."
  }
}

Plans Overview

Feature	Free	Pro	Enterprise
Monthly Price	$0	$29	Custom
Emails per Month	100	10,000	Unlimited
API Rate Limit	20/min	100/min	500/min
Search Queries	100/month	5,000/month	Unlimited
Storage	1 GB	50 GB	Unlimited
Support	Community	Email	Priority
Custom Domain	1	10	Unlimited
Webhooks	Limited	Full	Full

See Pricing for complete plan details.

Code Examples

cURL

# Get subscription
curl https://api.momail.io/v1/billing/subscription \
  -H "X-API-Key: your_key"

# Get usage
curl https://api.momail.io/v1/billing/usage \
  -H "X-API-Key: your_key"

# Create checkout session
curl -X POST https://api.momail.io/v1/billing/checkout \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "pro",
    "successUrl": "https://app.momail.io/billing/success",
    "cancelUrl": "https://app.momail.io/billing/cancel"
  }'

# Create portal session
curl -X POST https://api.momail.io/v1/billing/portal \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{"returnUrl": "https://app.momail.io/settings"}'

JavaScript

// Check subscription and usage
const [sub, usage] = await Promise.all([
  fetch('https://api.momail.io/v1/billing/subscription', {
    headers: { 'X-API-Key': 'your_key' }
  }).then(r => r.json()),
  fetch('https://api.momail.io/v1/billing/usage', {
    headers: { 'X-API-Key': 'your_key' }
  }).then(r => r.json())
]);

console.log(`Plan: ${sub.data.plan}`);
console.log(`Emails: ${usage.data.emailsUsed}/${usage.data.emailsLimit}`);

// Upgrade to Pro
const checkout = await fetch('https://api.momail.io/v1/billing/checkout', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    plan: 'pro',
    successUrl: window.location.origin + '/billing/success',
    cancelUrl: window.location.origin + '/billing/cancel'
  })
}).then(r => r.json());

window.location.href = checkout.data.url;