Chapter 20. Billing API

The Billing API provides a way to automate common billing processes.

All the endpoints of the Billing API can be found in the Admin Portal under Documentation (?) > 3scale API Docs > Billing API.

The Billing API requires a valid access token which meets the following requirements:

  • it should belong to either an admin user of the provider account, or a member user with "Billing" permissions
  • it should include "Billing API" scope

Note that when an invoice ID is required as a parameter, it refers to the invoice ID, and not the Friendly invoice ID.

The XML response of the API endpoints is mostly self-explanatory, and the fields of the Invoice represent the same information as in the web and PDF representation.

Some notable fields of the response:

  • creation_type: can have the following values: 'manual' for invoices created manually or 'background' for invoices created by the 3scale automated billing process
  • provider: the details of the API provider (the admin account), corresponds to the Issued by section of the invoice.
  • buyer: the details of the developer account, corresponds to the Issued to section of the invoice.

The XML representation of the invoice also includes the list of Line Items under the line-items field.

For some line items (typically the ones created automatically) apart from the expected name, description, quantity and cost (price), you can see the following:

  • type: the type of the line item, can have the following values:

    • LineItem::PlanCost – for line items for fixed plan costs
    • LineItem::VariableCost – for line items for variable costs
  • metric_id: for variable costs line items – the ID of the metric that the cost is associated with
  • contract_id: the ID of the service or application that the cost is associated with