API Spec

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

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.

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.