Billing Invoices & History

Getting the billing invoices and history from Stripe enables you to present this information to your customers.

 

Invoices vs History

There are 2 differences between invoices and history:

  1. Invoices contain more details
  2. History only contains actual transaction history with amounts greater than 0

 

Get billing history

You can use the following endpoint within your custom pages in order to get billing history, which means the actual transaction history. (If you subscribe to a free plan, you won't have billing history)

Summary

  • Endpoint: /api/v2/billing_history
  • Method: GET
  • Required User Type: TA

Response

A successful response will return an array of objects.

Each of the objects represents billing history in descending order by creation time containing the following tags:

  • amount - This amount is in your currency and in the smallest currency unit (e.g. cent)
  • status - The status of the transaction
    • succeededpendingfailed
  • currency - Three-letter ISO currency code, in lowercase

Example

Request

/api/v2/billing_history

Response Data

[
{
amount:2000,
amount_refunded: 0,
created: 1577319914,
currency: "usd",
statement_descriptor: null
status: "succeeded"
},
...
]

 

Get billing invoices

You can use the following endpoint within your custom pages in order to get billing invoices.

Summary

  • Endpoint: /api/v2/billing_invoices
  • Method: GET
  • Required User Type: TA
    • TA can only query invoices for current tenant

Response

A successful response will return an array of objects.

Each of the objects represents an invoice in reverse chronological order containing the following tags:

  • date - Billing date, in Epoch time format
  • number - Invoice number
  • paid - Whether payment was successfully collected for this invoice
  • period_end - End time of the invoice, in Epoch time format
  • period_start - Start time of the invoice, in Epoch time format
  • total - Total amount in your currency in the smallest currency unit (e.g. cent)
  • line_items - Array of individual line items that make up the invoice, in reverse chronological order.
    • amount - amount in your currency in the smallest currency unit (e.g. cent)
    • currency - Three-letter ISO currency code, in uppercase
    • period_end - End time of the line item, in Epoch time format
    • period_start - Start time of the line item, in Epoch time format
    • description - Description for the line item

Example

Request

/api/v2/billing_invoices

Response Data

[
{
date: 1593121893,
id: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
line_items: [
{
amount: 1000,
currency: "USD",
description: " Plan description",
period_end: 1595713827,
period_start: 1593121827
},
...
],
number: "xxxxxxx-0001",
paid: true,
period_end: 1593121827
period_start: 1590443427,
total:10
},
...
]