Billing API | 3scale: Free & Enterprise API Management Platform

The Billing API complements the Account Management API and allows you to access invoicing information for all users of the API.

Currently the API is read-only. You can access all the invoices that it issued to accounts, filter them by month, state or account or view single one of them. Changing state or adding line-items is not currently supported. Please note that order of the elements is not significant and may change in future versions.

current version: 0.1
version string for HTTP_ACCEPT header: application/vnd.3scale.finance-v0.1+xml

Prerequisities

Only accessible if Finance features are enabled
authenticate by provider_key

Versioning

The current version of this API is v2.0.

Servers

API calls must go to your administration domain location – usually this takes the form “http://developer-admin.yoursite.com/”. Ask your account representative if you are not sure of the URL).

Note: these domains are different from the domain used by the service management API.

Resources and URLs

Currently, all resources are read-only and the Billing API is only able to list invoices by different filters or fetch one by ID. Both may or may not be scoped by a buyer account.

Invoices List

URLs:

not scoped: GET /api/invoices.xml
scoped per customer: GET /api/accounts/{ACCOUNT_ID}/invoices.xml (use user managment API to get the account IDs)

Parameters:

provider_key – required
month return only invoices issued for given month (expected format is YYYY-MM)
-state – can be either of
- open – line items can be added to that invoice (for now only by web interface)
- pending – no items can be added, the PDF has been generated and the invoice is waiting to be charged for
- paid – sucessfully paid
- unpaid – charging failed at least once
- cancelled – the invoice was explicitely cancelled and is out of normal life-cycle

Examples:

GET /api/invoices.xml?month=2011-03 – all invoices from March 2011
GET /api/accounts/42/invoices.xml?state=unpaid – all unpaid invoices of Account with ID 42
GET /api/accounts/84/invoices.xml?state=cancelled&month=1984-10&page=2 – second page of cancelled invoices of Account with ID 84 from October 1984

Returns:

 <invoices version="0.1">
   <pagination per_page="10" total_entries="26" total_pages="3" current_page="2"/>
   <invoice version="0.1">
       ...
   </invoice>
    ...
 </invoices>

Comments:

see below for single invoice XML structure

Single Invoice

URLs:

not scoped: GET /api/invoices/{ID}.xml
scoped per customer: GET /api/accounts/{ACCOUNT_ID}/invoices/{ID}.xml (use user managment API to get the account IDs)

Parametres:

provider_key – required

Returns:

 <invoice version="0.1">
    <id>6</id>
    <state>pending</state>
    <paid_at></paid_at>
    <due_on>2011-04-07</due_on>
    <issued_on>2011-04-01</issued_on>
    <currency>EUR</currency>
    <cost>124436.7</cost>
    <period>
      <from>2011-03-01</from>
      <to>2011-03-31</to>
    </period>
    <provider>
      <id>16</id>
      <org_name>Random Org</org_name>
      <address></address>
      <city>Paris</city>
      <state></state>
      <country>FR</country>
      <phone></phone>
    </provider>
    <buyer>
      <id>36</id>
      <org_name>ApiTester</org_name>
      <address>Somewhere 123</address>
      <city>Barcelona</city>
      <state>Catalonia</state>
      <country>ES</country>
      <phone></phone>
    </buyer>
    <line-items>
      <line-item>
        <id>26</id>
        <name>Hits</name>
        <description></description>
        <quantity>1244367</quantity>
        <cost>124436.7</cost>
      </line-item>
    </line-items>
  </invoice>

Comments:

all dates are in YYYY-MM-DD format