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 stored as a User or Team record 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 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",
    "internal_id": 1
  },
  "identifier": "97980cfea0067",
  "billing_provider": {
    "type": "stripe",
    "identifier": "ABC"
  }
}

Spec: Charge

Spec: Usage