Chapter 18. Billing

The billing process creates invoices under the developer account, if it is subscribed to any paid services. The invoices are charged using the configured payment gateway.

18.1. Listing invoices

In the Audience > Billing > Earning by month section you can find an overview of your due and received payments, calculated as the sum of all invoices issued that month, depending on their state:

Total
all invoices excluding cancelled
In process
Open, Finalized and Pending invoices
Overdue
Failed and Unpaid invoices
Paid
Paid invoices

By clicking on a specific month you can list all invoices for that month.

You can also see the list of invoices by going to Audience > Billing > Invoices, where you can find invoices by their ID (friendly ID), the account name, and also filter by month and state.

The invoices of a specific developer account can also be found under X Invoices in the breadcrumbs of the account details page at Audience > Accounts > Listing > [selected account], where X is the number of invoices the account has.

18.2. Invoice view

If you click on the invoice friendly ID from the invoices list, you will see the details of the invoice.

18.2.1. Invoice details

The title includes the month and year of the invoice, and also shows whether the invoice was created manually or by automated billing process, e.g. Invoice for February 2018 (manually created).

The Details block below shows the friendly ID of the invoice, invoice state, dates when the invoice was finalized and issued, and when it’s due and paid on. If PDF has already been generated, the link to download the PDF will be also shown.

The Issued by and Issued to blocks shows the name and the address of the API provider and the developer account accordingly.

Below a block with line items will be shown, including calculations of the VAT/Sales Tax, total cost, and if the text in "Text to show if VAT/Sales Tax is 0%" was configured, it will also be shown here.

In the Transactions block of the invoice you can see the list of all credit card transactions attempts, including the status of the transaction, its timestamp, reference number, message provided by the payment gateway and the amount. You can find the transactions in your payment gateway administrator console using the reference number.

18.2.2. Editing invoices

If the invoice is in Open or Finalized state, you can edit some details of the invoice.

By clicking on the Edit link at the top right corner of the invoice view, you can change the friendly ID and the billing period.

You can also add and delete invoice line items (except calculated costs – total, VAT/sales tax, total with VAT/sales tax). To add a new line item, click on Add, and fill in Name, Quantity (doesn’t affect the cost), Description and Cost.

The links at the bottom of the invoice view can trigger actions on the invoice – different actions are available depending on the current state of the invoice, e.g. Generate PDF, Issue invoice Cancel invoice, Regenerate PDF, Charge, Mark as paid etc. These actions (except PDF-related) will change the state of the invoice.

18.3. Invoice states

The invoice can be in one of the following states:

Open
the invoice is created, but the automated calculations has not yet been finalized.
Finalized
the invoice has all the current billing period charges added to it.
Pending
the invoice has been issued to the developers and is awaiting payment.
Unpaid
the invoice has been charged unsuccessfully, but pending automatic retry.
Paid
the invoice has been charged successfully.
Failed
the invoice has been charged unsuccessfully, and automatic retry will not be attempted anymore.
Cancelled
has been cancelled by an admin.

18.4. Automated billing process

In 3scale, the billing process runs daily. It generates invoices, changing their states according to the billing flow, and performs charges using the configured payment gateway.

The billing flow is a bit different for Prepaid and Postpaid mode, and as billing in 3scale is based on calendar month, there are special events that happen on the 1st day of the month.

18.4.1. On the 1st day of each month

Postpaid

  • Bill variable cost for the previous month (the cost is included as a line item to the open invoice)
  • Finalize open invoices for the previous month
  • Bill fixed cost for the current month (create a new invoice for current month in Open state)

Prepaid

  • Bill fixed cost (current month)
  • Bill variable cost (previous month)

Notifications are sent to the API admins about the invoices finalized in the beginning of the month, so they can review the invoices and make necessary adjustments.

All actions that are performed every day also happen on the 1st day of the month in addition to the ones described above.

18.4.2. Every day

  • Bill expired trials and new contracts that haven’t yet been billed (invoices in Open state for the current month are created).
  • Prepaid only: Finalize all open invoices (state changes to Finalized).
  • Issue invoices (state changes to Pending).

    • The invoices are normally issued 2-3 days after they were finalized. The "Issued On" date of the invoice is set to current date, and the "Due On" date (when the invoice will be charged) is set to the Issued On + 2 days.
    • When the invoice is issued to the developers, they receive an email notification, and can see the issued invoice in the developer portal.
  • Charge invoices

    • The invoices in Unpaid and Pending states are charged, if the Due On date is today or earlier.
    • If the payment failed, the invoice state is changed to Unpaid. Charging will be retried again in 3 days. After 3 unsuccessful retries, the invoice state is changed to Failed, and charging is not retried anymore.
  • Notify about expired credit cards

    • the developer accounts whose credit cards are going to expire soon are sent email notifications.

18.4.3. Automatic and manual invoices

The invoices that are generated by the automated billing process have "(automatically created)" label in the invoice header (e.g. "Invoice for January 2019 (automatically created)").

The invoices that are generated manually are marked with "(manually created)" on the invoice details page.

The automated billing process may use existing invoices in "open" state for the current month to create additional line items, but only for automatically created invoices. The invoices created manually will not be updated by the automated billing process.

18.4.4. Mid-month upgrades

If an application (or account/service subscription) is upgraded in the middle of the month, the monthly cost is prorated according to the number of days left in the month. The limits configured on the application plan are not prorated.

If the application is upgraded from a free to a paid plan, the next time billing runs a new invoice will be generated including the prorated monthly cost.

When the application is upgraded from a paid plan to a more expensive paid plan, the behavior depends on several factors:

  • the mode of Billing: Prepaid or Postpaid
  • when the plan change is made

18.4.4.1. Prepaid billing

  1. If the application plan is changed on the same billing day (a billing day starts at 8am UTC) as is it was created, and so it has never been invoiced before, the fixed costs for the old plan are included to the invoice, and are discounted with a 'Refund' line item. The fixed costs for the old plan are also added to the invoice.

    Example: A customer signed up for the Plan A (200$) on the first day of the month, and upgraded to the Plan B (300$) on the same day. One invoice will be generated in this case, and it will contain the following line items:

    DescriptionCost

    Fixed fee ('Plan A')

    200

    Refund ('Plan A')

    -200

    Application upgrade ('Plan A' to 'Plan B')

    300

    Total

    300

    Note that if the customer signed up on another day of the month, the cost of and refund of 200 would be prorated.

  2. If the application plan is changed after the invoice was already issued for this application:

    • In case of an upgrade, the developer will be issued two invoices: one for the initial charge, and another one for the upgrade.

      Example: A customer signed up for the Plan A (200$) on the first day of the month, and then upgraded to the Plan B (300$) in the middle of the month. The following invoices will be generated:

      DescriptionCost

      Fixed fee ('Plan A')

      200

      Total

      200

      DescriptionCost

      Refund ('Plan A')

      -100

      Application upgrade ('Plan A' to 'Plan B')

      150

      Total

      50

      In the second invoice, the refunded cost (100$) and the new cost (150$) are prorated, as the upgrade is made in the middle of the billing period.

    • Refunding on application downgrade (change to a plan with a lower cost) is not supported at the moment.

18.4.4.2. Postpaid billing

In Postpaid billing mode a single invoice will be issued, and it will include the 'Refund' and 'Application upgrade' line items.

IMPORTANT: This behavior was introduced on April 20th, 2018 with the following changes:

  • A bug was fixed where the initial charge (for the initial application plan) was not included in the invoice when the application was upgraded on the same day as created.
  • Previously only one line item was added on application upgrade, including the difference between the cost of the new and the old plan. For example, in the scenario 2 described in Prepaid billing section above (application upgrades from Plan A – 200$, to Plan B – 300$), the second generated invoice would be:
DescriptionCost

Application upgrade ('Plan A' to 'Plan B')

50

Total

50

where 50$ is the difference between the prorated costs of the new and old plan for the rest of the month (150$ - 100$).

After April 20th, 2018, the calculations are reflected more clearly in the invoice (including refund and charge separately), while the total cost remains the same as before.

18.5. Enable/disable billing/charging per account

Automated billing process generates invoices for all developer accounts subscribed to paid services.

Charging can be enabled or disabled globally (see Billing and Charging settings ), however it is also possible to enable or disable both billing and charging per developer account. To do that, navigate to the account page and click the corresponding button (Enable / Disable) against:

  • Monthly billing is enabled/disabled
  • Monthly charging is enabled/disabled

If charging is disabled, and billing is enabled, the developer will be issued invoices, but will not be charged. This is useful in case you handle charging separately (e.g. with wire transfer).

If both are disabled, the developer will not be issued or charged.

If billing is disabled, and charging is enabled, the developer will not be issued any new invoices, but all the outstanding ones (Pending and Failed) will still be charged.

Here in the Billing Status block you can also see whether the credit card details are configured on the account. In case credit card details are configured, the month and the year of card expiration is shown. The presence of the credit card details may affect the developer portal flow on sign up and plan change (see more in Section 18.9, “Credit card flow”).

18.6. Plans with Trial Period

A trial period (in days) can be set for paid plans to delay the charging for the specified amount of days.

The trial period status will be shown for the application in the application listing ([Your_API_service] > Applications > Listing) in the State column as "live – trial expires in N days", and in the application details page in the Trial days left field.

During the trial period the application can use all the features and usage limits defined by the plan without restrictions.

Once the trial period is set, it is not possible to cancel or extend it. Upgrading to another plan will not reset the trial days counter.

10 days before the trial period expires, an email notification is sent to the developer account notifying about the upcoming trial expiration. The template of this email can be configured in Audience > Messages > Email Templates: "Application trial period expired for buyer" for the application plans, and "Service trial period expired for buyer" for service plans with trial period. The developer should either remain on the current plan, or switch to another plan, or contact the API provider if they decide to cancel the subscription.

Once the trial period is over, the next time automated billing runs (see Section 18.4, “Automated billing process”) the developer will be charged according to the costs set for the plan that the application or service are currently on. Note that the application will not be blocked or suspended after the trial period expires, and will continue to work.

Note that while a trial period technically can be set for free plans, it is not recommended as the feature loses its usefulness.

18.7. VAT rate/Sales Tax

Value-Added Tax (VAT) is a tax that is applied on goods and services sold within European Union. In other countries there is a similar tax, for example, Sales tax. API providers who charge their customers for using their API service often need to charge the tax as well and reflect it in the invoices to comply with the existing regulations.

3scale billing can automatically include VAT in the invoices, when configured.

18.7.1. Configure VAT rate field

VAT rate is the number (in percentage) that will be applied to the total cost in the invoice. To configure VAT rate, follow these steps in the Admin Portal, from the Dashboard:

  1. Go to Audience > Accounts > Fields Definitions.
  2. Click Create in the Account section.
  3. Select vat_rate in the [new field] drop-down list.
  4. Set a value for Label.
  5. Configure the checkboxes to indicate whether the field should be Required, Read only or Hidden for the developers.

    NOTE: the "Choices" field only accepts strings, so this field cannot be used.

  6. Click Create.

18.7.2. Configure VAT code field

VAT code is the VAT identification number. To configure the VAT code follow these steps in the Admin Portal, from the Dashboard:

  1. Go to Audience > Accounts > Fields Definitions.
  2. Click Create in the Account section.
  3. Select vat_code in the [new field] drop-down list.
  4. Set a value for Label.
  5. Configure the checkboxes to indicate whether the field should be Required, Read only or Hidden for the developers.
  6. Click Create.

18.7.3. Set VAT values for an account

Once VAT code and VAT rate fields are added, you can set the corresponding values under the developer account Edit form. Depending on the selected checkboxes in the fields definitions the fields can also be visible and/or editable by the developers in the developer portal.

VAT code can be any string.

VAT rate must be a number. Either integer or decimal numbers are accepted (e.g.: 21, 23.5 etc.) and they represent the percentage of the cost that will be included as VAT.

18.7.4. Invoices with VAT

When an invoice is generated for a developer account that has a non-zero VAT rate configured, the invoices will include the following line items:

_Total cost (without <VAT rate>)_ +
_<VAT rate> Amount_ +
_Total cost (<VAT rate> <VAT rate value>% included)_

<VAT rate> will be replaced with the Label set for the VAT rate field, and <VAT rate value> is the value configured for the account the invoice is issued for.

The VAT code will be included in the PDF version of the invoice with the label, specified in as the Label in the VAT code field definition. The value will correspond to the value set in the developer account details.

The fields vat_rate and vat_code can also be read and written by the 3scale Account Management API.

18.8. Developer portal view

The developers can manage their Credit Card information and see their invoices in the developer portal.

The Finance switch in Audience > Developer Portal > Feature Visibility has to be in Visible state for the developers to see the billing-related elements in the developer portal.

A logged-in user can update the credit card details at Settings > Credit Card Details. Depending on the payment gateway configured the form may be different, and the user may need to enter the billing address first.

*Note:* Credit card details are not stored in the 3scale API Management database, it is managed by the payment gateway. Only the last 4 digits of the credit card number, the expiration date and the reference provided by the payment gateway are stored in the 3scale API Management database.

A developer can only have one credit card card on the developer portal.

Credit card details cannot be deleted from the developer portal. The user of the developer account who wants to delete his credit card details would need to request the API provider to delete the credit card details from the system.

To see the invoices, the user can go to Settings > Invoices, and from there they can either show the details for each invoice, or download the invoice PDF.

18.9. Credit card flow

18.9.1. Sign up for a paid plan

When a developer signs up for a paid plan, they are requested to enter the credit card details before they are allowed to see the application credentials. Once the developer logs in to the developer portal for the first time, they will be redirected to the Credit Card Details page. Trying to access any other developer account page will result in a redirection to the Credit Card Details page again.

If you prefer, you can hide all the menu items except the Credit Card Details tab by customizing the corresponding developer portal templates with help of the Liquid tags.

The current_account Liquid drop exposes the method requires_credit_card_now? which returns true if the credit card details are missing, but are required (only if Billing is configured in the Admin Portal), and false otherwise.

You can hide any menu items and other UI elements in the submenu and users_menu partials by wrapping them with the following condition:

{% unless current_account.requires_credit_card_now? %}
...
{%  endunless %}

18.9.2. Upgrade from a free to a paid plan

For plan changes of the existing applications there are multiple options that can be configured, including changing the plan directly by the developer or requesting a plan change. In case the application is upgraded from a free to a paid plan, it is important to ensure that the developer enters the credit card details before being able to upgrade. This can be configured in [your_API_name] > Integration > Settings, Application Plan Changing section by the following setting:

Change plan directly if developer has credit card, otherwise:
- Only request a plan change
- Request Credit Card entry for paid plans

Select the first option if you want to only allow the developer to request the change, and perform the upgrade manually after the credit card details are entered.

Select the second option if you want the developer to be notified that credit card details need to be entered before upgrading to a paid plan. In the plan selector widget the developer will see a message "You cannot change plan until you enter your Credit Card details" pointing to the credit card details form.

18.10. "Billing address" field

When the developer enters the billing address on the Credit Card Details in the Developer Portal, this address is stored separately from the "legal" account address.

By default the legal address appears in the Invoices in the Issued to field. However, in case the developer does not have the legal address configured, but only the billing address, the latter will be used on the invoices (Note: the organization name is considered part of the address in this case).

By default the billing address is not visible in the Admin Portal or through the API, however you can add it as follows:

  1. Go to Audience > Accounts > Fields Definitions.
  2. Under the Account block click Create.
  3. Select 'billing_address' from the drop-down list, add the label, check the Read only checkbox and click Create.

Now the <billing_address> field appears in the XML model for Accounts in the Account Management API and Webhooks. The corresponding billing address will be visible as read-only in the Account and the Account edit pages of the Admin Portal.

Billing address can be changed by the developer in the Developer Portal (in the Credit Card Details section). The admin cannot change the billing address in the Admin Portal, but it is possible to do so with the Account Edit endpoint of the Account Management API using the following fields (as "additional fields"):

billing_address_name
billing_address_address1
billing_address_address2
billing_address_country
billing_address_city
billing_address_state
billing_address_zip
billing_address_phone