Premium Features and Plan Requirements

Use this guide when you need to answer three practical questions quickly:

Which features are available on my current plan?
Which endpoints require a paid or premium subscription?
What changes do I need to make when upgrading from the free tier?

Plan Matrix

This matrix focuses on feature availability. For request quotas and minute limits, see the Rate Limiting Guide.

Feature	Free Trial	Hobby / Starter	Professional	Business / Enterprise
Core REST price endpoints	Yes	Yes	Yes	Yes
Commodity catalog and metadata	Yes	Yes	Yes	Yes
Historical price lookups	Trial access	Paid access	Yes	Yes
Currency conversion (`currency=EUR`, `currency=GBP`)	Trial access	Paid access	Yes	Yes
`/v1/prices/all` market snapshot	Trial access	No	Yes	Yes
Marine fuels endpoints	Trial access	No	Yes	Yes
Cushing storage intelligence	Trial access	No	Yes	Yes
ICE Brent and futures datasets	Trial access	No	Yes	Yes
Drilling intelligence and energy-intelligence datasets	Trial access	No	No	Yes
WebSocket streaming	Trial access	No	No	Yes
Webhooks and automation workflows	Trial access	Plan-dependent	Yes	Yes
Priority support / higher SLA expectations	No	No	Limited	Yes

Premium Endpoints by Capability

Professional and Above

These pages document features that require at least a premium plan in normal production use:

Business and Enterprise

These capabilities are intended for higher-tier customers who need upstream and operational intelligence:

Access Requirements

All premium features use the same authentication model as the core API:

Authorization: Token YOUR_API_KEY

Premium access is enforced by the account tied to that API key. You do not need a separate hostname or a different auth scheme after upgrading.

Commercial Use and Redistribution

Premium access does not automatically grant public display, raw-data resale, redistribution, or downstream productization rights. Review Data Usage Policy before exposing data outside internal workflows.

Typical Upgrade Path

From Free Trial to Paid

When a trial ends, the most common next step is moving to a paid REST plan:

Keep the same integration and auth header
Review any rate-limit changes in Rate Limiting
Check whether your code relies on trial-only access to premium endpoints
Replace trial-only assumptions with plan-aware tests

From REST-Only to Premium Data

When enabling premium datasets:

Add handling for 403 or 402 style access-denied responses during rollout
Update onboarding or internal docs to list newly available endpoints
Verify dashboards and background jobs use only features your production key can access

Example: Detecting Tier-Locked Features

curl "https://api.oilpriceapi.com/v1/prices/all" \
  -H "Authorization: Token YOUR_API_KEY"

If your key does not include the required plan, expect an access-denied response with upgrade guidance.

{
  "status": "error",
  "error": {
    "code": "INSUFFICIENT_PLAN",
    "message": "This endpoint requires a higher-tier subscription.",
    "required_tier": "professional"
  }
}

The exact shape may vary by endpoint, but integrations should treat plan failures as non-retryable until the account is upgraded.

Data Freshness by Capability

Data freshness differs by product line:

Capability	Typical Freshness Pattern
Spot and benchmark prices	Intraday, often every few minutes
Historical price ranges	Returned from stored history
Futures and marine fuels	Intraday, source-dependent
Storage and drilling intelligence	Daily or weekly, source-dependent
WebSocket events	Near real time after publication

For source-specific expectations, see Data Freshness and the relevant endpoint page.

Development and Testing

When testing premium features in staging or CI:

Use a dedicated API key for the exact plan you want to exercise
Keep free-tier and premium-tier tests separate
Do not assume trial access matches long-term paid entitlements
Mock INSUFFICIENT_PLAN responses in client libraries and UI tests