Invoices API

RevOps makes infrastructure billing simple and takes the hard-work out of figuring what to include on invoices. If you are automating billing for your pay-as-you-go services or usage-based contracts, our Invoicing API will help you connect to your billing platform and launch invoicing quickly.

Invoices are issued through your billing provider so that you retain full control of your invoices. This gives you the flexibility to view or modify invoices before they are sent to customers.

Why manage invoices with RevOps?

Invoices are generated automatically from usage metrics reported to RevOps. RevOps helps businesses track and reconcile usage computations and add significant time savings for engineering teams to spend on their own products.

How does it work?

  1. Create a new invoice for the customer
  2. Open the customer's invoice
  3. View invoice status

Determining Start and End Date

To serve a wide variety to needs, the Invoice API supports using dates as well as dateTimes for Invoices. Both formats assume UTC time because usage metrics are processed in UTC time.

Dates are given in the YYYY-MM-DD format and are inclusive. This means the invoice will include usage for the entire end_date.

DateTime are give in the ISO8601 format and provides more precise controls of the start_date and end_date. This format is exclusive, meaning it will charge only up until the end_date's time on the given date. Times will be rounded down to the nearest hour.

Here are two examples that create an Invoice for the entire month of January:

{
  // using dates
  "start_date": "2020-01-01",
  // to
  "end_date": "2020-01-31"
}
{
  // using dateTimes
  "start_date": "2020-01-01T00:00:00Z", // 2020-01-01T00:00:00+00:00
  // until
  "end_date": "2020-02-01T00:00:00Z" // 2020-01-31T00:00:00+00:00
}

Invoice Endpoints

Each endpoint assumes a default base url: https://vault.revops.io/v1/

Invoices List Resource

https://vault.revops.io/v1/accounts/:acct_id/invoices

Supported Methods:

  • GET - Retrieves a list of Invoices of an account
  • POST - Issue a new Invoice for an account
URL Parameters
Name Description Required Schema
acct_id Unique identifier for the Account generated by the RevOps API. Yes string

API Key Accessibility

Invoice resources can only be accessed with your secret key.

HTTP Method Public Key Secret Key
GET N/A
POST N/A

CREATE INVOICES

POST /v1/accounts/:acct_id/invoices

Summary:

Creates a new Invoice for the specified period. RevOps will build an Invoice from the usage metrics reported during this period.

Description:

A new invoice is created by sending a POST request to the resource URL /v1/accounts/:acct_id/invoices.

There are two required parameters:

  1. start_date
  2. end_date

Note: The start_date and end_date are inclusive or exclusive depending on the format you supply. See Determining Start and End Date for more information.

This operation generates the invoice and optionally sends it the customer to begin the fulfillment process. If the account is set up with auto-payment AND the Invoice generated does not require manual approval, it will be fulfilled.

Invoice email behavior

Invoices do not send emails when the Invoice mode for an account's billing preferences is manual. All accounts are setup as manual until you explicitly assign the Invoice mode to be automatic.

HTTP Response Codes
Code Description Schema
201 Created Invoice Invoice
400 Invalid request. API Error

Example

This example creates an Invoice via the secret key.

In this example, we will

$> curl  https://vault.revops.io/v1/accounts/:acct_id/invoices \
        -X POST \
        -H 'Authorization: Bearer <secret_key>' \
        -H 'Content-type: application/json' \
        -d '{"account_id": "my-account-id", "start_date": "2019-10-01", "end_date":"2019-10-31"}'

Here is the same example in python.

from uuid import uuid4
import urllib.request
import json

api_key = "sk_sandbox_<yourkey>"
api_url = "https://vault.revops.io/v1/accounts/:acct_id/invoices"

invoice = {
    'account_id': 'my-account-id'
    'status': 'draft',
    'start_date': "2019-10-01",
    'end_date': "2019-10-31",
}

data = json.dumps(invoice).encode('utf8')

request = urllib.request.Request(
  api_url,
  method='POST',
  data=data,
  headers={
    'Content-type': 'application/json',
    'Authorization': "Bearer {}".format(api_key),
  },
)
try:
    with urllib.request.urlopen(request) as response:
        json_response = response.read().decode('utf-8')
        print(json.loads(json_response))
except urllib.error.HTTPError as httperror:
    print(httperror.read().decode('utf-8'))

GET INVOICES

GET /v1/accounts/:acct_id/invoices

Summary:

Returns a paginated list of Invoices for an Account.

HTTP Response Codes
Code Description Schema
201 Invoice Invoices
400 Invalid request. API Error

Example

$> curl  https://vault.revops.io/v1/accounts/:acct_id/invoices \
        -X GET \
        -H 'Authorization: Bearer <secret_key>' \
        -H 'Content-type: application/json'

Invoice Instance Resource

https://vault.revops.io/v1/accounts/:acct_id/invoices/:inv_id

Supported Methods:

  • GET - Retrieves an Invoice
  • POST - Updates the status of an existing Invoice
  • DELETE - Voids an existing Invoice
URL Parameters
Name Description Required Schema
acct_id Account Unique identifier Yes string
inv_id Unique identifier for the Invoice generated by the API. Yes string

API Key Accessibility

Invoice methods are only accessible with your secret key.

HTTP Method Public Key Secret Key
GET N/A
POST N/A
DELETE N/A

GET INVOICE

Summary:

Retrieves an Invoice for an Account.

HTTP Response Codes
Code Description Schema
201 Invoice Invoices
400 Invalid request. API Error

Example

$> curl  https://vault.revops.io/v1/accounts/:acct_id/invoices/:inv_id \
        -X GET \
        -H 'Authorization: Bearer <secret_key>' \
        -H 'Content-type: application/json'

Examples Response:

{
  "account_id": "acct_id",
  "id": "inv_id",
  "uri": "/v1/accounts/:acct_id/invoices/inv_id",
  "amount_due": "1000.00",
  "amount_paid": "0.00",
  "amount_remaining": "1000.00",
  "amount_total": "1000.00",
  "auto_advance": false,
  "billed_period": "monthly",
  "billed_usage_filename": "ABCDEF-0016.xlsx",
  "charge_automatically": false,
  "contract_id": "",
  "contract_url": "",
  "currency": "usd",
  "days_until_due": 1,
  "detailed_usage_url": "https://storage.revops.io/detailed-usage/inv_id/ABCDEF-0016.xlsx",
  "end_date": "2019-10-31T00:00:00Z",
  "invoice_due_date": "2019-11-28T22:47:45+00:00",
  "invoice_due_date_timestamp": 1574981265,
  "invoice_number": "ABCDEF-0016",
  "invoice_paid_date": null,
  "invoice_paid_date_timestamp": null,
  "invoice_pdf_url": "https://pay.stripe.com/invoice/invst_id/pdf",
  "invoice_sent_date": "",
  "invoice_sent_date_timestamp": 0,
  "paid_out_of_band": false,
  "payment_term": "",
  "provider": "stripe",
  "provider_id": "in_id",
  "start_date": "2019-10-01T00:00:00+00:00",
  "status": "draft"
}

UPDATE INVOICES

POST /v1/accounts/:acct_id/invoices/:inv_id

Summary:

Updates the status of an existing Invoice.

Description:

Invoices can be moved to a new status by sending a POST request.

Note: Invoices can only be modified as long as they remain in draft status. If changes are required after an Invoice has moved to open, it must be marked as void and a new Invoice issued.

$> curl  https://vault.revops.io/v1/accounts/:acct_id/invoices/:inv_id \
        -X POST \
        -H 'Authorization: Bearer <secret_key>' \
        -H 'Content-type: application/json' \
        -d '{"status":"open"}'
{
  "status": "open"
}

Responses

Code Description Schema
200 Updated Invoice Invoice
400 Invalid request. API Error

DELETE

Summary:

Invoices are voided when DELETE is issued on an Invoice. RevOps purposefully does not delete records from the platform, enforcing best practices in ledger management.

Description:

An Invoice status is set tovoid by sending a DELETE request to the resource’s URL.

Responses

Code Description
204 Successful operation. The server returns a 204 No Content status code if a deletion request is successful and no content is returned.
404 Account or invoice record not found. The server returns a 404 Not Found status code if a deletion request fails due to the resource not existing.

Invoice Payment

https://vault.revops.io/v1/accounts/:acct_id/invoices/:inv_id/pay

Supported Methods:

  • POST - Automatically charge a customer invoice
URL Parameters
Name Description Required Schema
acct_id Account Unique identifier Yes string
inv_id Unique identifier for the Invoice generated by the API. Yes string

API Key Accessibility

Invoice Pay methods are only accessible with your secret key.

HTTP Method Public Key Secret Key
POST N/A

PAY INVOICES

POST /v1/accounts/:acct_id/invoices/:inv_id/pay

Summary:

This endpoint sends an invoice to a customer for payment. If the invoice was configured for automatic payment collection, we will attempt to charge the customer's primary payment instrument.

To support use-cases where invoices paid out-of-band, this endpoint can set an open invoice and mark its status as paid.

Description:

Invoices are sent to customers for payment by sending a POST request.

The request payload has a single required parameter:

  1. transaction_id: A string representing the idempotency value sent to the integrated billing platform.

The optional parameters:

  1. paid_out_of_band: Update invoice status to paid when this parameter is true
  2. instrument_id: Charge a specific Instrument instead of the primary instrument
$> curl  https://vault.revops.io/v1/accounts/:acct_id/invoices/:inv_id/pay \
        -X POST \
        -H 'Authorization: Bearer <secret_key>' \
        -H 'Content-type: application/json' \
        -d '{"transaction_id":"idempotent-transaction-id"}'
{
  "account_id": "acct_id",
  "id": "inv_id",
  "uri": "/v1/accounts/:acct_id/invoices/inv_id",
  "amount_due": "1000.00",
  "amount_paid": "0.00",
  "amount_remaining": "1000.00",
  "amount_total": "1000.00",
  "auto_advance": false,
  "billed_period": "monthly",
  "billed_usage_filename": "ABCDEF-0016.xlsx",
  "charge_automatically": false,
  "contract_id": "",
  "contract_url": "",
  "currency": "usd",
  "days_until_due": 1,
  "detailed_usage_url": "https://storage.revops.io/detailed-usage/inv_id/ABCDEF-0016.xlsx",
  "end_date": "2019-10-31T00:00:00Z",
  "invoice_due_date": "2019-11-28T22:47:45+00:00",
  "invoice_due_date_timestamp": 1574981265,
  "invoice_number": "ABCDEF-0016",
  "invoice_paid_date": null,
  "invoice_paid_date_timestamp": null,
  "invoice_pdf_url": "https://pay.stripe.com/invoice/invst_id/pdf",
  "invoice_sent_date": "",
  "invoice_sent_date_timestamp": 0,
  "paid_out_of_band": false,
  "payment_term": "",
  "provider": "stripe",
  "provider_id": "in_id",
  "start_date": "2019-10-01T00:00:00+00:00",
  "status": "paid"
}

Invoice Notifications

https://vault.revops.io/v1/accounts/:acct_id/invoices/:inv_id/notify

Supported Methods:

  • POST - Send an email invoice notification to customer
URL Parameters
Name Description Required Schema
acct_id Account Unique identifier Yes string
inv_id Unique identifier for the Invoice generated by the API. Yes string

API Key Accessibility

Invoice notification methods are only accessible with your secret key.

HTTP Method Public Key Secret Key
POST N/A

INVOICE NOTIFICATIONS

POST /v1/accounts/:acct_id/invoices/:inv_id/notify

Summary:

This endpoint sends a notification email to customers informing them that an invoice has been issued and is available for payment.

Description:

Invoice email notifications are sent customers by sending an empty POST request.

$> curl  https://vault.revops.io/v1/accounts/:acct_id/invoices/:inv_id/notify \
        -X POST \
        -H 'Authorization: Bearer <secret_key>' \
        -H 'Content-type: application/json' \
        -d '{}'

Responses

Code Description Schema
200 Updated Invoice Invoice
400 Invalid request. API Error

Models

Invoice

Invoice contains all the details for a particular customer invoice.

Name Type Description
id string Invoice ID.
amount_due string (Money) Amount due.
account_id string Account Id.
amount_paid string (Money) Amount paid.
amount_remaining string (Money) The balance remaining on the Invoice.
amount_total string (Money) Total amount on the Invoice.
billedusagefilename string Friendly spreadsheet (xlsx) filename.
billing_period string Billing period for the Invoice. Possible values are: daily, monthly, yearly, pay-as-you-go.
contract_id string The signed contract id corresponding to this invoice. This field is not set for pay-as-you-go customers.
contract_url string URL to download the signed contract PDF.
currency string Three-letter ISO currency code.
daysuntildue integer Number of days until the invoice is due.
detailedusageurl string Spreadsheet (xlsx) that contains detailed usage information for the Invoice period.
end_date string Ending date of the billing period in the YYYY-MM-DD or ISO8601 format. See dates for more info.
invoiceduedate string (ISO8601) The date the Invoice is due in the ISO8601 format.
invoiceduedate_timestamp integer The date the Invoice is due in Unix time.
invoice_number string Invoice number.
invoicepaiddate string (ISO8601) The date that the Invoice was paid in ISO8601 format. All dates are in UTC.
invoicepaiddate_timestamp integer The date that the Invoice was paid in Unix time.
invoicepdfurl string URL to download the Invoice PDF.
invoicesentdate string (ISO8601) The date that the Invoice was sent to the customer in the ISO8601 format. All dates are in UTC.
invoicesentdate_timestamp integer The date that the Invoice was sent to the customer in Unix time.
paidoutof_band boolean Boolean value that indicates if payment has been made outside of RevOps.
payment_term string Payment terms. Possible values are: top-up, net30.
provider string String identifier of the billing provider. Possible values: stripe
provider_id string External unique identifier of the Invoice in the provider's system.
start_date string Starting date of the billing period in the YYYY-MM-DD or ISO8601 format. See dates for more info.
status string Invoice status. Possible values are: draft, open, paid, void, uncollectible.
uri string RevOps assigned URI for accessing the Invoice record through a GET request.

Invoice Status Breakdown

The Invoice status tells you the which stage of the Invoice lifecycle. the Invoice is currently in. It also determines if an Invoices can be edited.

Status Description
draft A new invoice has been created with the appropriate line items for usage based products. The Invoice can be modified while in this status.
open The Invoice has been finalized and can no longer be edited. Once finalized, the Invoice is ready to be sent to the customer.
paid The Invoice has been paid.
void The Invoice has been canceled.
uncollectible Finance has determined that the customer is unlikely to pay the Invoice.

API Error Response Format

The standard API response format is used to indicate when we were not able to process the request.

Name Type Description Required
code integer RevOps Error Code No
type string RevOps Error Code No
message string Human readable description of the error code No