Skip to content

Subscriptions

Account Scope Required, please include X-Auth-Account header with your Account ID. Scope: billing:read.

List Subscriptions

This currently returns all active or suspended subscriptions.

GET /api/subscriptions

sites lists live WordPress sites only. Domains, mail and cPanel hosting bill on their own subscriptions and return sites: []; use product to tell them apart. For deleted sites, use List Sites.

Params (optional)
  • page: Integer | page number (default: 1)
  • per_page: Integer | records per page (default: 50, max: 100)
Returned Params
  • subscriptions: Array
    • id: String
    • status: String
    • created_at: DateTime
    • updated_at: DateTime
    • price: Object
      • amount_cents: Integer
      • term: String
    • run_rate: Object | deprecated, use annual_run_rate. The hosting price for one term, as a money object; 0 for domains and mail
      • cents: Integer
      • currency_iso: String | from the account's billing plan
    • annual_run_rate: Object | the yearly cost at today's catalog price, for hosting, domains and mail. Promotion codes are not applied
      • cents: Integer
      • currency_iso: String
    • sites: Array
      • id: String
      • name: String
      • created_at: DateTime
      • updated_at: DateTime
      • primary_domain: String
      • location: String
      • package: String
      • dunning_suspended: Boolean
      • pending_delete: Boolean | always false here — sites awaiting deletion are excluded from sites
      • delete_scheduled_at: DateTime | always null here, for the same reason
    • product: Object
      • id: String
      • name: String

View Subscription

GET /api/subscriptions/:id

Returned Params
  • subscription: Object
    • id: String
    • status: String
    • created_at: DateTime
    • updated_at: DateTime
    • price: Object
      • amount_cents: Integer
      • term: String
    • run_rate: Object | deprecated, use annual_run_rate. The hosting price for one term, as a money object; 0 for domains and mail
      • cents: Integer
      • currency_iso: String | from the account's billing plan
    • annual_run_rate: Object | the yearly cost at today's catalog price, for hosting, domains and mail. Promotion codes are not applied
      • cents: Integer
      • currency_iso: String
    • sites: Array
      • id: String
      • name: String
      • created_at: DateTime
      • updated_at: DateTime
      • primary_domain: String
      • location: String
      • package: String
      • dunning_suspended: Boolean
      • pending_delete: Boolean | always false here — sites awaiting deletion are excluded from sites
      • delete_scheduled_at: DateTime | always null here, for the same reason
    • product: Object
      • id: String
      • name: String

Upcoming Charges

What will be added to the workspace's next invoice. Requires X-Auth-Account and the billing:read scope.

GET /api/billing/upcoming_charges

What you get depends on your role:

  • A billing manager of the billing workspace (the one that pays) sees the charges of every workspace billed through it, plus headroom and payment.
  • A billing manager of a workspace billed through another sees only that workspace's own rows. headroom and payment are null, and warnings is empty.
  • Anyone else gets 403 not_authorized.
Returned Params
  • currencies: Array | one entry per currency with charges, sorted by currency
    • currency: String
    • subtotal_cents: Integer | the net of lines and credits together
    • tax_estimate_cents: Integer | lines and credits only; rows whose price already includes tax are not counted
    • total_cents: Integer
    • estimated_invoice_on: String | date, or null when estimate_reason is after_setup
    • estimate_reason: String | now (an invoice is being created now), bank_transfer, payment_method_missing, next_run (invoiced at the next scheduled run) or after_setup (nothing is ready to invoice yet)
    • sections: Object
      • lines: Array | charges on the next invoice
      • credits: Array | credits on the next invoice
      • waiting: Array | charges waiting for their order to finish setting up
      • under_review: Array | charges held for review
      • invoicing_now: Array | charges already on an invoice being created
  • headroom: Object | null unless you see the billing workspace, or when the workspace cannot order on invoice right now
    • currency: String
    • available_cents: Integer | the room left to order on invoice, never below 0
  • payment: Object | null in the child workspace view
    • mode: String | card or bank_transfer
    • default_payment_method_present: Boolean
    • payable_days: Integer | days to pay an invoice; null for card
  • warnings: Array<String> | payment_method_missing: a card payer has charges to invoice and no default payment method

Each entry in a sections array has this shape. Only lines and credits count toward the totals.

Charge row
  • account: Object | the workspace the charge belongs to
    • id: String
    • name: String
  • description: String
  • currency: String
  • amount_cents: Integer | negative for a credit
  • discount_cents: Integer
  • net_cents: Integer | amount_cents minus discount_cents
  • tax_estimate_cents: Integer
  • tax_behavior: String | null when not set
  • quantity: Integer
  • period_start: DateTime
  • period_end: DateTime
  • order_id: String
  • kind: String | order_line, seat_change, seat_credit, early_cancellation or reversal
  • state: String | pending, or batching in invoicing_now
  • created_at: DateTime
Errors
  • 400 missing_account | no X-Auth-Account
  • 403 not_authorized | you are not a billing manager of this workspace