Billing API

HempData API uses Stripe for subscription billing. These endpoints let you programmatically create checkout sessions and manage subscriptions.

POST /v1/billing/checkout

Create a Stripe Checkout session to start a new subscription.

Request Body

Field	Type	Required	Description
`tier`	string	Yes	Subscription tier: `starter`, `professional`, or `enterprise`
`billing_period`	string	Yes	`monthly` or `annual` (annual saves 20%)
`email`	string	Yes	Customer email address
`success_url`	string	Yes	URL to redirect to after successful payment (must include `{CHECKOUT_SESSION_ID}` placeholder)
`cancel_url`	string	Yes	URL to redirect to if the customer cancels

Request Example

curl -X POST "https://api.hempdataapi.com/v1/billing/checkout" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "professional",
    "billing_period": "annual",
    "email": "compliance@yourcompany.com",
    "success_url": "https://yourapp.com/billing/success?session_id={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://yourapp.com/billing/cancel"
  }'

Response Example

{
  "success": true,
  "data": {
    "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_a1b2c3d4...",
    "session_id": "cs_live_a1b2c3d4e5f6g7h8",
    "tier": "professional",
    "billing_period": "annual",
    "amount": 14280,
    "currency": "usd",
    "description": "HempData API Professional — Annual ($119.00/mo billed annually)",
    "expires_at": "2026-03-18T11:00:00Z"
  },
  "meta": {
    "request_id": "req_bill_001"
  },
  "errors": []
}

Redirect the customer to the checkout_url to complete payment. The session expires after 1 hour.

POST /v1/billing/portal

Create a Stripe Customer Portal session for managing an existing subscription (update payment method, change plan, view invoices, cancel).

Request Body

Field	Type	Required	Description
`return_url`	string	Yes	URL to redirect to when the customer exits the portal

Request Example

curl -X POST "https://api.hempdataapi.com/v1/billing/portal" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "return_url": "https://yourapp.com/dashboard"
  }'

Response Example

{
  "success": true,
  "data": {
    "portal_url": "https://billing.stripe.com/p/session/bps_live_a1b2c3d4...",
    "expires_at": "2026-03-18T11:00:00Z"
  },
  "meta": {
    "request_id": "req_bill_002"
  },
  "errors": []
}

POST /v1/webhooks/stripe

Stripe sends billing events to this endpoint. You do not call this directly — it is configured in your Stripe dashboard.

Events Handled

Stripe Event	Action
`checkout.session.completed`	Activate subscription, provision API key
`customer.subscription.updated`	Update tier, rate limits
`customer.subscription.deleted`	Deactivate API key
`invoice.payment_succeeded`	Record payment, extend access
`invoice.payment_failed`	Send warning, grace period (7 days)

Tier Details

	Starter	Professional	Enterprise	Research
Monthly price	$49/mo	$149/mo	$499/mo	Free
Annual price	$39/mo	$119/mo	$399/mo	Free
Stripe Price ID (monthly)	`price_starter_monthly`	`price_pro_monthly`	`price_ent_monthly`	—
Stripe Price ID (annual)	`price_starter_annual`	`price_pro_annual`	`price_ent_annual`	—
States included	5 (your choice)	All 50 + DC	All 50 + DC	All 50 + DC
Rate limit	10 req/min	60 req/min	300 req/min	5 req/min
Webhooks	—	—	Included	—
Widget	—	Included	Included	—
CSV export	—	Included	Included	—
Changelog access	30 days	1 year	Unlimited	30 days
Support	Email	Priority email	Dedicated Slack	Community

Research Tier

The Research tier is free for:

Academic institutions (.edu email required)
Journalists (press credentials required)
Nonprofit policy organizations (501(c)(3) verification)

Apply through the dashboard. Research tier includes read-only access to all data with a 5 req/min rate limit. No webhook, widget, or CSV features.

Upgrading and Downgrading

Upgrades take effect immediately. You are charged a prorated amount for the remainder of the billing period.
Downgrades take effect at the end of the current billing period. You retain access to higher-tier features until then.
Cancellations take effect at the end of the current billing period.

Payment Methods

Stripe accepts:

Credit and debit cards (Visa, Mastercard, American Express, Discover)
ACH bank transfers (Enterprise tier only)

All prices are in USD. Invoices are available in the Stripe Customer Portal.