This step-by-step guide will provide detailed instructions on configure seat-based billing configuration through our API, from configuring your API keys to submitting seat usage and reviewing invoices.

In this guide you will learn how to:

  • Configure your API keys
  • Setting up products, tax rates and

Follow these detailed steps to configure your pricing and billing via the Sequence API. Each step is designed to help you seamlessly integrate and automate your billing processes.

​
Configure your API keys

Before you begin integration with the Sequence API, you’ll need to set up your API keys. Follow these steps to manage your API credentials: Accessing Your API Keys

​
Setting Up Environment Variables

After obtaining your API key and secret, set them as environment variables on your system. Setting your API keys as environment variables prepares your system for the next steps in setting up billing for a new customer using Sequence.

export API_KEY=your-api-key
export API_SECRET=your-api-secret

​
Create a product

Next, we need to define the product for which we will be billing. In this example, the product is the number of seats available.

In Sequence, products appear as groups of line items on invoices. It’s important to name your products in a way that is easily recognizable to you when using our dashboard.

Remember to note down the Product IDs you receive in the response. You will need these IDs for later steps.

Create a product
curl -X POST --location "https://eu.sequencehq.com/api/products" \
    --basic --user $API_KEY:$API_SECRET \
    -H "Content-Type: application/json" \
    -d '{
            "name": "Example product",
            "label": "Example product"
        }'
Product response
{
  "id": "c7326e0d-d2fb-434e-ae8f-f5ae6142a476",
  "name": "Example product",
  "label": "Example product",
  "createdAt": "2024-05-02T14:26:48.63792Z",
  "updatedAt": "2024-05-02T14:26:48.637932Z"
}

​
Create a seat metric

We will create the seat metric for the type of seat we intend to charge for. For this example, we are creating a “standard” seat type. This designation will help determine the pricing for each seat. Note that each seat metric can have multiple prices associated with it. For instance, you could use a single seat type to represent both your standard and pro pricing tiers, or you could create separate seat types for each pricing level.

Be sure to note down the Seat Type ID you receive in the response, as it will be necessary for subsequent steps.

Create a seat type
curl -X POST --location "https://eu.sequencehq.com/api/seat-metrics" \
    --basic --user $API_KEY:$API_SECRET \
    -H "Content-Type: application/json" \
    -d '{
            "seatType": "editor",
            "label": "Editor Seat"
        }'
Seat type response
{
  "id": "49b62ade-938b-4182-b1e0-01a1f295a8ad",
  "seatType": "editor",
  "label": "Editor Seat",
  "createdAt": "2024-05-02T14:52:18.913471Z",
  "updatedAt": "2024-05-02T14:52:18.913471Z"
}

​
Create a seat price

Finally, we will set the pricing for the ‘standard’ seat type we previously created. The price per seat is set at £15.00 and will be billed monthly in arrears. The proration strategy used is ‘PRORATE_INCREMENTS’, which adjusts the customer’s bill based on the number of seats they use during the current billing month.

The pricing model is ‘SEAT_BASED’, indicating that the pricing specifically applies to each seat used.

We’ve set the contracted minimum seats to zero, ensuring that the customer pays for every seat they consume. If you have a minimum number of seats you would like to charge for, even if not all seats were consumed, then you can set this value to a number larger than zero.

Remember to note the ID of the price you receive in the response, as this will be important for future steps.

Create a seat price
curl -X POST --location "https://eu.sequencehq.com/api/prices" \
    --basic --user $API_KEY:$API_SECRET \
    -H "Content-Type: application/json" \
    -d '{
            "name": "Editor seat for ",
            "productId": "c7326e0d-d2fb-434e-ae8f-f5ae6142a476",
            "currency": "GBP",
            "billingFrequency": "MONTHLY",
            "billingType": "IN_ARREARS",
            "structure": {
              "pricingType": "SEAT_BASED"
              "seatMetricId": "49b62ade-938b-4182-b1e0-01a1f295a8ad",
              "pricePerSeat": "15.0",
              "prorationStrategy": "PRORATE_INCREMENTS",
              "contractedMinimumSeats": 0
            },
            "externalIds": []
        }'
Price response
{
  "id": "018f39d9-b6ec-760f-87c0-032b73c86b1b",
  "sequenceAccountId": "a633a6ef-f023-4d03-91c7-5879356d5eae",
  "productId": "c7326e0d-d2fb-434e-ae8f-f5ae6142a476",
  "name": "Standard seat price",
  "currency": "GBP",
  "structure": {
    "pricingType": "SEAT_BASED",
    "seatTypeId": "49b62ade-938b-4182-b1e0-01a1f295a8ad",
    "pricePerSeat": "15.0",
    "prorationStrategy": "PRORATE_INCREMENTS",
    "contractedMinimumSeats": 0,
    "tiers": []
  },
  "billingFrequency": "MONTHLY",
  "billingType": "IN_ARREARS",
  "createdAt": "2024-05-02T15:08:40.556433Z",
  "externalIds": [],
  "customMetricParameters": []
}

​
Create a customer

Up to this point, we have established the foundational models, such as the seat-based pricing model, that apply universally to all customers. This pricing model is designed to be reusable for any customer who signs up for your service. The following steps are specific to individual customers and should be repeated each time you onboard someone new.

First, you will need to create a customer through our API. The customer object is a central component in Sequence and represents the entity you will bill. It includes essential information such as contact details, billing preferences, and any external IDs you might need. For instance, in this example, we are incorporating a Stripe customer ID as an external ID, allowing us to link the Sequence customer with their Stripe counterpart.

Create a customer
curl -X POST --location "https://eu.sequencehq.com/api/customers" \
    --basic --user $API_KEY:$API_SECRET \
    -H "Content-Type: application/json" \
    -d '{
            "legalName": "John Doe",
            "contactName": "John Doe",
            "address": {
                "line1": "Flat 1",
                "line2": "123 Fake Street",
                "town": "London",
                "postcode": "AB1 2EF",
                "country": "GB"
            },
            "email": "john@example.com",
            "billingEmails": ["billing@example.com"],
            "telephone": "001122334455",
            "url": "https://example.com/",
            "label": "Example Customer",
            "taxStatus": "TAXED",
            "customerAliases": [],
            "integrationIds": [{
                "service": "Stripe",
                "id": "cus_OCtCxqQDgu1uX9"
            }]
        }'
Customer response
{
    "id": "d512f4cb-ff5c-405b-888e-ef96e2e99077",
    "createdAt": "2024-05-02T15:07:48.806213Z",
    "sequenceAccountId": "a633a6ef-f023-4d03-91c7-5879356d5eae",
    "legalName": "John Doe",
    "contactName": "John Doe",
    "address": {
      "line1": "Flat 1",
      "line2": "123 Fake Street",
      "town": "London",
      "postcode": "AB1 2EF",
      "country": "GB"
    },
    "email": "john@example.com",
    "billingEmails": [
      "billing@example.com"
    ],
    "telephone": "001122334455",
    "url": "https://example.com/",
    "taxStatus": "TAXED",
    "label": "Example Customer",
    "externalIds": [{
        "service": "Stripe",
        "id": "cus_OCtCxqQDgu1uX9",
        "lastSynced": "2024-05-09T16:09:44.303644Z",
        "url": "https://dashboard.stripe.com/customers/cus_OCtCxqQDgu1uX9"
    }]
  }

​
Create tax rates

For simplicity, we’ll assume that all future customers will be subject to tax. To accommodate this, you first need to create a tax rate. This rate will be applied later when setting up billing schedules for each customer.

cURL
curl -X POST --location "https://eu.sequencehq.com/api/tax-rates" \
--basic --user $API_KEY:$API_SECRET \
-H "Content-Type: application/json" \
-d '{
    "isPublished": true,
    "name": "UK Sales Tax",
    "invoiceName": "Value Added Tax",
    "invoiceShortName": "VAT",
    "description": "Value Added Tax applied to sales in the UK",
    "amount": "0.2",
    "country": "GB"
}'
Tax rate response
{
  "id": "4e49a233-c195-4453-8da3-f2964cd6e528",
  "versionId": "c1f427df-02c3-42c4-8677-3b3c26eaf1eb",
  "sequenceAccountId": "a633a6ef-f023-4d03-91c7-5879356d5eae",
  "version": 0,
  "isPublished": true,
  "name": "UK Sales Tax",
  "invoiceName": "Value Added Tax",
  "invoiceShortName": "VAT",
  "description": "Value Added Tax applied to sales in the UK",
  "amount": "0.2",
  "country": "GB",
  "isArchived": false
}

​
Create a billing schedule

Once the customer is set up, the next step is to create a billing schedule. The billing schedule outlines the customer’s billing plan, including start and end dates, the day of recurrence, and pricing phases. In this example, we are establishing a billing schedule that spans from January 1st, 2024, to December 31st, 2024. This schedule features a single phase that covers the entire year and incorporates the price we’ve created earlier.

Additionally, the tax rate we established will be included in the billing schedule. This ensures that the correct tax amount is applied to the price and invoice during billing.

After the billing schedule is in place, Sequence will automatically generate invoices based on the seat events you report for the customer.

Create a billing schedule
curl -X POST --location "https://eu.sequencehq.com/api/billing-schedules" \
     --basic --user $API_KEY:$API_SECRET \
    -H "Content-Type: application/json" \
    -d '{
            "type": "PHASES",
            "customerId": "d512f4cb-ff5c-405b-888e-ef96e2e99077",
            "startDate": "2024-01-01",
            "endDate": "2024-12-31",
            "recurrenceDayOfMonth": 1,
            "phases": [
              {
                "priceIds": ["018f39d9-b6ec-760f-87c0-032b73c86b1b"],
                "startDate": "2024-01-01",
                "endDate": "2024-12-31"
              }
            ],
            "taxRates": [
              {
                "priceId": "018f39d9-b6ec-760f-87c0-032b73c86b1b",
                "taxRateId": "4e49a233-c195-4453-8da3-f2964cd6e528"
              }
            ],
            "isDraft": false,
            "rollUpBilling": true
        }'
Billing schedule response
{
  "id": "8da1e0ae-205f-42ee-bb3e-38b670ded0d2",
  "customerId": "d512f4cb-ff5c-405b-888e-ef96e2e99077",
  "status": "ACTIVE",
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "taxRates": [
      {
        "priceId": "018f39d9-b6ec-760f-87c0-032b73c86b1b",
        "taxRateId": "4e49a233-c195-4453-8da3-f2964cd6e528"
      }
    ],
  "recurrenceDayOfMonth": 1,
  "autoIssueInvoices": false,
  "prices": [
    {
      "id": "018f39d9-b6ec-760f-87c0-032b73c86b1b",
      "sequenceAccountId": "a633a6ef-f023-4d03-91c7-5879356d5eae",
      "productId": "c7326e0d-d2fb-434e-ae8f-f5ae6142a476",
      "name": "Standard seat price",
      "currency": "GBP",
      "structure": {
        "pricingType": "SEAT_BASED",
        "seatTypeId": "49b62ade-938b-4182-b1e0-01a1f295a8ad",
        "pricePerSeat": "15.0",
        "prorationStrategy": "PRORATE_INCREMENTS",
        "includedSeats": 0,
        "chargeMethod": "CHARGE_CONSUMED",
        "tiers": []
      },
      "billingFrequency": "MONTHLY",
      "billingType": "IN_ARREARS",
      "createdAt": "2024-05-02T15:08:40.556433Z",
      "externalIds": [],
      "customMetricParameters": []
    }
  ],
  "createdAt": "2024-05-02T15:14:40.331734Z",
  "updatedAt": "2024-05-02T15:14:40.331734Z",
  "phases": [
    {
      "id": "018f39df-3458-7f08-a4af-6b5fabcd1f79",
      "createdAt": "2024-05-02T15:14:40.344175Z",
      "billingScheduleId": "8da1e0ae-205f-42ee-bb3e-38b670ded0d2",
      "priceIds": [
        "018f39d9-b6ec-760f-87c0-032b73c86b1b"
      ],
      "startDate": "2024-01-01",
      "endDate": "2024-12-31",
      "discounts": [],
      "minimums": []
    }
  ],
  "rollUpBilling": true
}

​
Submitting seat events

With all billing related information out of the way, you can now start submitting seat events to us when your customers consume seats on your platform.

Create a seat event
curl -X POST --location "https://eu.sequencehq.com/api/seat-events" \
     --basic --user $API_KEY:$API_SECRET \
    -H "Content-Type: application/json" \
    -d '{
    "customerEventId": "10be23bc-09a2-4078-959b-551e8a402781",
    "customerAlias": "d512f4cb-ff5c-405b-888e-ef96e2e99077",
    "seatType": "editor",
    "eventTimestamp": "2024-05-02T19:00:00.000000Z",
    "total": 1
}'
Seat event response
{
  "id": "018f5e30-7992-7b82-a352-3a73cfccacb0",
  "customerEventId": "10be23bc-09a2-4078-959b-551e8a402781",
  "customerAlias": "d512f4cb-ff5c-405b-888e-ef96e2e99077",
  "seatType": "editor",
  "sequenceAccountId": "a633a6ef-f023-4d03-91c7-5879356d5eae",
  "eventTimestamp": "2024-05-02T19:00:00.000000Z",
  "total": 10
}

​
Invoices

Finally, after the first billing period has finished, you can retrieve all invoices related to the billing schedules you have created.

Retrieve invoices
curl -X GET --location "https://eu.sequencehq.com/api/invoices" \
     --basic --user $API_KEY:$API_SECRET
Invoices response
{
  "items": [
    {
      "id": "32761569-e9a8-4155-bedb-0abaac30ecb4",
      "sequenceAccountId": "a633a6ef-f023-4d03-91c7-5879356d5eae",
      "billingScheduleId": "8da1e0ae-205f-42ee-bb3e-38b670ded0d2",
      "status": "DRAFT",
      "currency": "GBP",
      "customerEmails": [
        "exampleCorpInvoices@example.com"
      ],
      "customerLegalCompanyName": "John Doe",
      "customerBillingAddress": {
        "line1": "Flat 1",
        "line2": "123 Fake Street",
        "town": "London",
        "postcode": "AB1 2EF",
        "country": "GB"
      },
      "customerShippingAddress": {
        "line1": "Flat 1",
        "line2": "123 Fake Street",
        "town": "London",
        "postcode": "AB1 2EF",
        "country": "GB"
      },
      "paymentOptions": [
        "STRIPE"
      ],
      "billingPeriod": {
        "start": "2024-01-01",
        "endInclusive": "2024-01-31"
      },
      "customerId": "d512f4cb-ff5c-405b-888e-ef96e2e99077",
      "totalTax": "30",
      "netTotal": "150",
      "grossTotal": "180",
      "metadata": [],
      "paymentStatus": "UNPAID",
      "createdAt": "2024-02-01T16:16:47.850079Z",
      "creditNoteIds": [],
      "linkedServices": [],
      "billingRunId": "018f5e24-8f9b-71e6-a47b-e7647f55e8b8",
      "accountingDate": "2024-01-31",
      "calculatedAt": "2024-02-01T16:16:47.850079Z",
      "customerTaxStatus": "TAXED"
    }
  ],
  "pagination": {
    "after": null,
    "before": null,
    "totalResultSize": 1
  }
}

​
Conclusion

If you check your Sequence Dashboard, you should now see the tax rate, seat type, product, price, customer, and billing schedule you’ve created.

It’s important to note that while all these configurations can be accomplished directly through the Sequence Dashboard, this API example was designed to demonstrate how you can embed similar functionalities directly into your codebase for a more integrated solution.

We hope this end-to-end API guide has been informative and useful for your integration efforts. Please reach out to let us know your feedback or if you need assistance designing any other billing models to optimize your billing processes.

Seat eventsInvoicing customers