API Spec

Overview

Venn has defined four critical calls that your clients can issue. These are dubbed the "Spec" as they are the mechanism for sending data in your billing system. This was heavily inspired by Segment's Spec. It is also designed to be the outline for interacting with Venn across all clients and libraries. If you know the Venn Spec, you can implement it in any language of your choosing.

The recipient of these events is the Venn Agent.

Spec: Identify

At the core of Venn lies the IDENTIFY call. This call allows you to define a Customer which can be associated to billing events. Customers automatically get assigned an id but they also include an identifier that you assign when calling Identify. This ID usually maps to your own system of record's id such as user.id. You can also provide an optional set of traits which serves as metadata for the Customer..

Most importantly, Venn also needs to track what payment processor (e.g. Stripe) that this Customer is using. Because Venn, itself, is not a payment processor and will never store payment information, this helps link Venn and your payment processor. This information is stored in the billing_provider field and contains two keys: the type and the identifier. See the docs on [Billing Providers] for more details on how to define and configure them.

Identifies can be called as early as when your customer signs up for your product (usually this is as a User or Team entity in your database). We recommend identifying a customer after you have collected payment information and configured them in your billing provider. This will allow you to include this information in the billing_provider field as part of your initial Identify call.

If you choose to identify a customer before collecting payment information, billing_provider details can be added at a later time. Simply issue a second Identify call to a Customer with the same identifier and include the billing_provider details. Venn will update the Customer appropriately.

Identify payloads look roughly like this

{
  "traits": {
    "name": "Venn",
    "tier": "enterprise"
  },
  "identifier": "97980cfea0067",
  "billing_provider": {
    "type": "stripe",
    "identifier": "ABC"
  }
}

Spec: Charge

The CHARGE event tells the billing system to record a charge. This is used when you need to make an advance charge.

{
  "type": "charge",
  "customer_id": "abc",
  "timestamp": "2022-01-01 00:00:00.000Z",
  "event": "Seat Added",
  "properties": {
     "quantity": 1
  }
}

Spec: Usage

The USAGE event tells the billing system to record a quantity of usage. This is used when you need to bill in arrears.

{
  "type": "usage",
  "customer_id": "abc",
  "timestamp": "2022-01-01 00:00:00.000Z",
  "event": "Bandwidth Used",
  "properties": {
     "quantity": 500
  }
}

Spec: Reverse

The REVERSE event tells the billing system to revert a CHARGE. The event provided will determine which operation is reversed. The quantity provided will be applied a negative value.

If the charge cannot be reversed (i.e. the quantity results in a negative value), the operation is a no-op

{
  "type": "reverse",
  "customer_id": "abc",
  "timestamp": "2022-01-01 00:00:00.000Z",
  "event": "Seat Added",
  "properties": {
     "quantity": 1
  }
}

USAGE events cannot be reversed.