Account invoicing

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

GET /v1/account/invoices
?page_size=25&page_index=1&search=&filters[status]=unpaid

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.

{
  "list": [ 
    {
      "id": "rec_1234567890",
      ...
    },
    ...
  ],
  "url": "https://api.backstack.com/v1/...",
  "total": 8 
}

Read invoice

Request

GET /v1/account/invoices/:id

Response

// 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.

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.

// psuedocode
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:

POST /v1/account/invoice-items
{ 
  "amount": 432
  "description": "Percent of charge number chg_1234567890."
}

Response

// invoice  object
{
  "id": "ivi_1234567890",
  ...
}

Read invoice item

Request

GET /v1/account/invoice-items/:id

Response

// 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

// 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

// 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

GET /v1/account/invoice-items
?page_size=25&page_index=1&search&filters[invoice_id]=inv_1234567890

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.

{
  "list": [ 
    {
      "id": "rec_1234567890",
      ...
    },
    ...
  ],
  "url": "https://api.backstack.com/v1/...",
  "total": 8 
}

Processing payments

todo

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.

Webhook

A webhook can be sent to a URL for you to process invoice payments. The payload will contain all invoices due.

// webhook
{
  "invoices": [
    // invoice objects
    {
      "id": "inv_1234567890",
      ...
    },
    ...
  ]
}