Quickstart Guide

This is a quickstart guide to get set up on Archetype. This walkthrough will take you through a guide on best practice to have Archetype integrated and get familiar with the life cycle of how subscriptions and revenue will be processed through Archetype

Create an Account and link your Stripe Account

Go to https://app.archetype.dev to register a new account. During the onboarding you'll have the option to link your stripe account. Once you do so, your Archetype account will natively work with Stripe via Stripe Connect.

Once you do so, you'll see a button on the top of the Archetype Dashboard to toggle live mode. You want to switch to test mode for the next steps. Switching to test mode allows you to create and assign products without any real money being transacted through your systems.

📘

Test vs Prod Mode

Each mode will have its own set of customers, products, billable metrics, API Keys, and App Ids. Make sure to swap out the API keys whenever toggling in your systems.

Create a billable metric

Go to the billable metrics page and create a billable metric.

Create a product

Go to the product page and create a product.

Since this is a metered product, we'll want to create a simple Starter Plan . We set the base price to be $100 that will be charged monthly to your customer.

For the purpose of the demo, this will be a private plan thus unable to be publicly visible to your end customer.

Next, add a metered item by pressing the green + icon. You'll open a modal where you can create a metered plan.

For this example, we'll create a simple Volume Based Discounted Plan that tracks API calls.

In the above examples, EACH of the API calls will be billed at $1.00 per call. After that threshold, the entire usage will be set to use the average price of $0.80 up to 5000 API Calls.

Since this is a limited plan, your customer will be capped at 5000 API Calls. Alternatively you can toggle the usage to be unlimited and set all usage to be $0.80 * # of API calls going forward.

More information on these limits can be found in the Products page.

Create a customer

Go to the customer page and create a customer. Set the ID to be some unique string that will not be recycled.

Assign a customer a sandbox subscription

Go into that newly created customer and you'll see their full details. This will be where you can modify their subscription details, view their usage stats, update their details, view their invoices and usage and more!

Click on Add Subscription then select Startup Plan from the dropdown and assign the sandbox subscription. This assigns a subscription to the customer.

🚧

Customers need a valid subscription enabled for billable metrics to be tracked.

📘

Default Free Products Can Be Enabled

For all customers to have access to billable metrics, services or content entitlements either in a limited or a full service format, you are able to create a free product that can be enabled by default for any new customer that is registered.

Now that your customer is created and assigned a product, you can implement our SDK into your stack.

Implement the Archetype SDK

Python SDK

pip install archetypesdk

Once installed in your main file, integrate the SDK into your codebase. You'll need your App ID and Secret Key which can be found in your settings page.

import archetypesdk as archetype
from fastapi import FastAPI, Depends

app = FastAPI()
archetype.app_id = "ARCHETYPE_APP_ID"
archetype.secret_key = "ARCHETYPE_SECRET_KEY"

Next Add the route that you want to track with a custom billable metric

@app.get("/auth-test")
async def root():
 
		## GET or Create a custom id if it doesn't exist
		archetype.Customer.Retrieve(
      custom_uid="YOUR_CUSTOMER_ID"
    )
  
  	#This creates a Billable Metric Usage Record that is instantly sent.
    #You can view this customer's usage in a few ways:
    # a) From the customer's page
    # b) From the analytics charts
    # c) From the dashboard homepage
    #Each page comes with a bunch of different context
    # from revenue, usage to optimization opportunities
   
    archetype.BillableMetric.LogUsage(
        custom_ud="YOUR_CUSTOMER_ID", 
        billable_metric_id="BILLABLE_METRIC_ID", 
        amount=1
    )
    return {"message": "Hello World"}
  
 

The final output of your sample API should look like this

import archetypesdk as archetype
from fastapi import FastAPI, Depends

app = FastAPI()
archetype.app_id = "ARCHETYPE_APP_ID"
archetype.secret_key = "ARCHETYPE_SECRET_KEY"

@app.get("/auth-test")
async def root():
	archetype.BillableMetric.LogUsage(
        custom_ud="YOUR_CUSTOMER_ID", 
        billable_metric_id="BILLABLE_METRIC_ID", 
        amount=1
    )

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, debug=True, host="0.0.0.0", port=3000)

Node SDK

npm install @archetypeapi/node

//OR

yarn add @archetypeapi/node

Once installed in your package.json file, integrate the SDK into your codebase. You'll need your App ID and Secret Key which can be found in your settings page.

const archetypesdk = require('@archetypeapi/node')
const express = require('express')
const app = express()

const appId = process.env.APP_ID; // find in your Archetype Dashboard
const secretKey = process.env.SECRET_KEY; // find in your Archetype Dashboard

const Archetype = archetypesdk(appId, secretKey);

Next Add the route that you want to track with a custom billable metric

@app.get("/auth-test") => {
  // GET or Create a custom id if it doesn't exist
  Archetype.Customer.Retrieve("YOUR_CUSTOMER_ID")

  //This creates a Billable Metric Usage Record that is instantly sent.
  // You can view this customer's usage in a few ways:
  // a) From the customer's page
  // b) From the analytics charts
  // c) From the dashboard homepage
  // Each page comes with a bunch of different context
  // from revenue, usage to optimization opportunities

  Archetype.BillableMetric.LogUsage("YOUR_CUSTOMER_ID", "BILLABLE_METRIC_ID", amount=1)
  return {"message": "Hello World"}
}
  
 

📘

Billable Metric Amounts can be Decremented

If you ever need to decrement a customer's usage just pass a negative number for usage. There are other usage_types like max, last_ever and last in period. Check out Metered Items for more details.

Run the service and test the billable metric usage

Once you run your server instance locally, you can view this usage in the dashboard. Go to your dashboard home to view the usage being tracked.

That's it! Done