Acme API - Billing

API Billing and Subscription Endpoints Overview: Manage billing information, subscriptions, invoices, and payment methods.

Description: Get current subscription details for the organization.
Parameters: None required (uses authenticated org context)
Response:
  - plan (string): Current plan name (free, starter, professional, enterprise)
  - status (string): active, trialing, past_due, canceled
  - current_period_start (string): ISO 8601 date
  - current_period_end (string): ISO 8601 date
  - seats_used (integer): Number of active seats
  - seats_limit (integer): Maximum seats for plan

Description: Upgrade to a higher plan tier.
Parameters:
  - plan (string, required): Target plan name
  - billing_cycle (string, optional): monthly or annual, default monthly
Response:
  - plan (string): New plan name
  - effective_date (string): When the upgrade takes effect
  - prorated_amount (number): Prorated charge for current period

Description: List all invoices for the organization.
Parameters:
  - status (string, optional): Filter by paid, open, void
  - limit (integer, optional): Number of invoices to return, default 10
Response:
  - invoices (array): List of invoice objects
  - total (integer): Total invoice count

Description: Get details for a specific invoice.
Parameters:
  - invoice_id (string, required): Invoice identifier
Response:
  - id (string): Invoice ID
  - amount (number): Total amount
  - currency (string): Three-letter currency code
  - status (string): Payment status
  - line_items (array): Itemized charges
  - created_at (string): Invoice date

Description: Add a new payment method.
Parameters:
  - type (string, required): card or bank_account
  - token (string, required): Payment processor token
Response:
  - id (string): Payment method ID
  - type (string): Method type
  - last4 (string): Last 4 digits
  - is_default (boolean): Whether set as default