API Tutorial 101

Billing a customer through Fermata requires your app to establish an account in Fermata’s database. Emit an event when your customer uses your platform and Fermata will use the plan your setup in the platform to determine when to capture payment.

​

Create an account

Create a new account when a user registers.

{
  "name": "John Smith",
  "email": "[e-mail]",
  "metadata": "d2s8f83ns", //your customer's internal ID
  "plan*id": "23434", //find this in Fermata dashboard
  "stripe_id": "a093uns" //only pass this in if there's a Stripe ID
}

If you already have a Stripe account for the customer you can pass the Stripe customer id in the stripe_id parameter. If you leave this off, then we will create a Stripe customer for you in your Stripe account. We support a metadata parameter that can be any JSON you want in case you want to track things like your internal customer IDs. You can pass a plan_id parameter to set the plan the customer will be billed against. See the plan section for more information on plans. This API call will return a new account_id starting with a*

//Lets put in the return call?

​

Send an event

Emit events to Fermata to track customer balances in real-time. The logic for how that event gets billed sits within Fermata so your app doesn’t need to do any calculations on transactions or balances.

//whats accountID vs companyID? //should we take out the promise string stuff? and does the payload sit in a different part?

{
  accountId: string,
  eventType: string,
  eventCost: number,
  eventDenomination: string,
  companyId: string,
  apiKey: string
): Promise<string> {
  const url = https://api.gofermata.com/v1/accounts/${accountId}/events`;
  const payload = {
    type: eventType,
    cost_override_amount: eventCost,
    cost_override_denomination: eventDenomination,
    gate_on_balance: true, // Push will fail if not enough balance
}

Also note, you’re unlimited in the number of events you send to Fermata so you can do things like capture all events you may want to bill against, but only bill against those that are configured in plans.

​

Upgrade plan

Fermata handles all the calculations required for mid-cycle plan upgrades. There are currently 3 different schemes we support for upgrading plans and you can request additional ones here: (link to a contact us?).

Sleeping Beauty (simplest)

The new plan upgrade happens upon renewal.

this is the code for sending an upgrade

Snow White (fairest)

We charge the difference between the two plans, and grant the new features. There’s no change to billing cycle or refund for overage.

Ariel

Fermata pro-rates the refund and starts the new plan immediately. This changes the billing cycle.

Downgrade plan

// leaving for now. not sure we have the SCHEMES.

Set a customer-facing payment notification at 90% of metered balance

Fermata monitors customer and product balances in real-time to trigger webhooks. These webhooks are often configured to send internal alerts, external notifications, or gate features in your app.

Here’s an example for how to trigger a webhook when a product balance is 90% consumed.