Billing API

Overview

The Billing API allows you to manage your subscription, view invoices, and update payment methods programmatically. All billing is handled securely through Stripe.

The table below is sourced from the billing source of truth, GET /billing/plans — generated at build time and refreshed live in your browser — so it never drifts from the product. If the request fails it falls back to the last committed values.

Plan	Price / mo	Requests / mo	Rate limit	Highlights
Developer	$19	10,000	60 / rolling 60s	Real-time prices, 1-year history, email support
Starter	$49	50,000	60 / rolling 60s	Webhooks, 5-year history
ProfessionalPopular	$99	100,000	60 / rolling 60s	Futures, WebSocket, market brief, priority support
Scale	$299	1,000,000	60 / rolling 60s	Everything in Professional + drilling intelligence, Slack support

Synced from the billing API (/billing/plans). Sign up or manage plans at oilpriceapi.com/pricing. Free tier: 200 requests/month. 7-day free trial with 10,000 requests.

Need a custom SLA or volume beyond Scale? Contact us for Enterprise.

Endpoints

Get Available Plans

GET /billing/plans

Response:

{
  "plans": [
    {
      "id": "developer",
      "name": "Developer",
      "price_monthly": 1900,
      "price_yearly": 19000,
      "currency": "usd",
      "request_limit": 10000,
      "features": ["all_commodities", "historical_data"]
    }
  ]
}

Get Current Subscription

GET /billing/subscriptions/current

Response:

{
  "subscription": {
    "id": "sub_123",
    "plan": "professional",
    "status": "active",
    "current_period_start": "2025-01-01T00:00:00Z",
    "current_period_end": "2025-02-01T00:00:00Z",
    "cancel_at_period_end": false,
    "usage": {
      "requests_used": 45000,
      "requests_limit": 100000,
      "percent_used": 45
    }
  }
}

Create Subscription

POST /billing/subscriptions

Request Body:

{
  "plan_id": "professional",
  "billing_period": "monthly"
}

Change Plan

POST /billing/subscriptions/change_plan

Request Body:

{
  "new_plan_id": "professional"
}

Plan changes are prorated. Upgrades take effect immediately; downgrades take effect at the next billing period.

Cancel Subscription

POST /billing/subscriptions/cancel

Cancels at end of current billing period. You retain access until then.

Reactivate Subscription

POST /billing/subscriptions/reactivate

Reactivates a subscription scheduled for cancellation.

Payment Methods

List Payment Methods

GET /billing/payment_methods

Update Payment Method

PATCH /billing/payment_methods/update

Request Body:

{
  "payment_method_id": "pm_card_visa_123"
}

Create Setup Intent

POST /billing/intents/setup

Returns a Stripe Setup Intent for adding a new payment method.

Invoices

List Invoices

GET /billing/invoices

Response:

{
  "invoices": [
    {
      "id": "inv_123",
      "amount": 7900,
      "currency": "usd",
      "status": "paid",
      "period_start": "2025-01-01",
      "period_end": "2025-01-31",
      "pdf_url": "https://invoice.stripe.com/..."
    }
  ]
}

Usage Tracking

Get Current Usage

GET /billing/usage

Response:

{
  "period": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-02-01T00:00:00Z"
  },
  "requests": {
    "used": 45000,
    "limit": 100000,
    "remaining": 55000
  },
  "daily_breakdown": [
    { "date": "2025-01-15", "requests": 1500 },
    { "date": "2025-01-16", "requests": 1800 }
  ]
}

Customer Portal

For self-service billing management, redirect users to Stripe's Customer Portal:

POST /billing/customer-portal/sessions

Response:

{
  "url": "https://billing.stripe.com/session/..."
}

Redirect users to this URL for:

Update payment method
View invoice history
Download invoices
Cancel subscription

Credit Packs (Pay-as-you-go)

For users who exceed their monthly limits:

List Available Credit Packs

GET /billing/credit_packs

Purchase Credits

POST /billing/credit_purchases

Request Body:

{
  "pack_id": "10k_requests",
  "quantity": 1
}

Webhook Events

Subscribe to billing webhooks for real-time updates:

Event	Description
`subscription.created`	New subscription started
`subscription.updated`	Plan changed
`subscription.cancelled`	Subscription cancelled
`invoice.paid`	Payment successful
`invoice.payment_failed`	Payment failed
`usage.limit_warning`	80% of limit reached
`usage.limit_exceeded`	100% of limit reached

Questions?

Contact support@oilpriceapi.com for billing questions or custom Enterprise pricing.