Chapter 26. Billing

The title includes the month and year of the invoice, and also shows whether the invoice was created manually or by automated billing process, for example, 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 is due and paid on. If the 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.

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 (does not 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, for example, 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.

Postpaid

Prepaid

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 first day of the month in addition to the ones described above.

The invoices that are generated by the automated billing process have an (automatically created) label in the invoice header. For example: 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.

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:

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:

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

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, for example: 21, 23.5 etc., and they represent the percentage of the cost that will be included as 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.

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.

You can use Liquid tags to hide all of the menu items, except the Credit Card Details tab, by customizing the corresponding Developer Portal templates.

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 user interface elements in the submenu and users_menu partials by wrapping them with the following condition:

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

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_product_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 the message, You cannot change plan until you enter your Credit Card details, pointing to the credit card details form.