Appearance
Account Invoicing
DANGER
This document has not been updated since version 0.0.3 and is not ready for production. It will be updated before version 1.0 of the project is released.
Account-based invoices are automatically generated for any implemented fees, requiring no additional action on your behalf. You can display the current account invoices in your UI and process account payments automatically if desired.
List invoices
The current account invoices can be presented in your UI.
Request
sh
GET /v1/account/invoices
?page_size=25&page_index=1&search=&filters[status]=unpaid
Parameter | Type | Description |
---|---|---|
page_size | Optional integer | The quantity of records you want returned. The default is 25. |
page_index | Optional integer | The current page index in the array of pages. |
search | Optional string | The value to search for against the specific list. |
filters | Optional array | The filters to apply for the query (e.g. &filters[foo]=bar ). |
Filter | Type | Options |
---|---|---|
status | Optional string | paid or unpaid . Omit to list all. |
Response
Returns a list
array of records with the total
records available for the query. The url
of the current request are also included. See the pagination guide for information on paging through lists.
json
{
"list": [
{
"id": "rec_1234567890",
...
},
...
],
"url": "https://api.backstack.com/v1/...",
"total": 8
}
List item property | Type | Description |
---|---|---|
id | String | The invoice ID. |
todo | todo | todo |
Read invoice
todo
Request
sh
GET /v1/account/invoices/:id
Response
json
// invoice object
{
"id": "inv_1234567890",
"description": "Invoice for Month/Year",
"account_id": "acc_1234567890",
"stripe_customer_id": "cust_1234567890",
"date": 1234567890,
"amount": 12345,
"items": [
{
"id": "ivi_1234567890",
"description": "Monthly user fees (10 @ $15.00).",
"amount": 15000
},
...
]
}
Update invoice
Invoices cannot be updated or deleted.
Auto-invoiced items
Invoice items are automatically generated when any of the following fees are implemented.
Fee | Description | Implementation |
---|---|---|
Version fee | Collect a fee for any version of the application functionality. | Implement in each domain.version . |
User fee | Collect a fee for each account user. | Implement in each domain.version . |
Optional feature fee | Collect a fee for any feature designated as optional . | Implement in each domain.version.features . |
See versions and version assignment workflow for additional information.
Custom invoice items
You can create an invoice item for the current account by posting the required values to the API. The item will be included in the next account invoice.
js
// pseudocode
const amount = 123.45;
const charge = await createCharge(amount);
if(charge.success)
const result = await processFee(
(amount * 100) * 0.035, // 3.5% of the charge amount in cents.
"Percent of charge number " + charge.id + "."
);
...
Request
The processFee function in the example code above would post the following:
sh
POST /v1/account/invoice-items
{
"amount": 432
"description": "Percent of charge number chg_1234567890."
}
Parameter | Type | Description |
---|---|---|
amount | Required integer | The amount (in cents) for which to create a transaction value. Submit a negative amount to perform a credit. |
description | Optional string | Any fee description you want displayed on the invoice transaction (max 200 characters). If empty, the app title will be used. |
Response
json
// invoice object
{
"id": "ivi_1234567890",
...
}
Read invoice item
Request
shell
GET /v1/account/invoice-items/:id
Response
json
// invoice item object
{
"id": "ivi_1234567890",
"account_id": "acc_1234567890",
"amount": 432,
"description": "Percent of charge number chg_1234567890.",
"timestamp": 1234567890
"invoice_id": null
}
Update invoice item
Invoice items serve as transactional sources of truth, and as such, they cannot be updated or deleted. To nullify an invoice item, you can create an offsetting item to eliminate its value.
Request
js
// original item
POST /v1/account/invoice-items
{
"amount": 1234,
"description": "Purchase of item #12345.",
}
// offset item
POST /v1/account/invoice-items
{
"amount": -1234,
"description": "Refund purchase of item #12345.",
}
Response
json
// invoice object
{
"id": "ivi_1234567890",
...
}
List invoice items
Retrieve a list of items included in an invoice or those that have not yet been invoiced by omitting the filter.
Request
sh
GET /v1/account/invoice-items
?page_size=25&page_index=1&search&filters[invoice_id]=inv_1234567890
Parameter | Type | Description |
---|---|---|
page_size | Optional integer | The quantity of records you want returned. The default is 25. |
page_index | Optional integer | The current page index in the array of pages. |
search | Optional string | The value to search for against the specific list. |
filters | Optional array | The filters to apply for the query (e.g. &filters[foo]=bar ). |
Filter | Type | Options |
---|---|---|
invoice_id | Optional string | The invoice ID for which to filter the items. If omitted, all un-invoiced items will be returned. |
Response
Returns a list
array of records with the total
records available for the query. The url
of the current request are also included. See the pagination guide for information on paging through lists.
json
{
"list": [
{
"id": "rec_1234567890",
...
},
...
],
"url": "https://api.backstack.com/v1/...",
"total": 8
}
List item property | Type | Description |
---|---|---|
id | String | The invoice ID. |
todo | todo | todo |
Processing payments
todo
TIP
Invoice periods are determined by the account.created
date and processed in thirty-day increments. Fees are prorated as required when related activity occurs between periods.
Automatically
Provide your Stripe restricted key in your application settings and enable the auto invoice payment option. This will allow Backstack to perform the following on behalf of your Stripe platform account:
- Create a Stripe customer for each invoiced account.
- Process payments on account invoices.
- Email invoice payment details to accounts.
WARNING
Backstack does not provide functionality for further management of account payments (e.g. refunds, transfers). Use your Stripe dashboard for any additional payment management requirements.
Webhook
A webhook can be sent to a URL for you to process invoice payments. The payload will contain all invoices due.
js
// webhook
{
"invoices": [
// invoice objects
{
"id": "inv_1234567890",
...
},
...
]
}