# Understanding Consumers in Apideck

## Why This Matters

Every consumer you create in Apideck counts toward your plan. Your pricing tier, your billing, and your API call limits all tie back to the number of consumers you have and how you structure them. Get the consumer model wrong, and you either overpay for unnecessary consumers or, worse, route the wrong data to the wrong customer.

This guide covers what a consumer is, when to create one versus many, and how to keep your setup clean.

## What Is a Consumer?

In Apideck, a consumer represents the customer whose data you are integrating with. When ACME Corp is your customer, you create a consumer for ACME Corp. They connect their QuickBooks, Xero, or NetSuite account through Apideck Vault, and from that point on, you pass their consumer ID in every API call.

## What Is an Active Consumer?

A consumer becomes an **active consumer** for the current billing month when two conditions are met: they have at least one connection, and they generate at least one successful downstream API call (Unify or Proxy) or a successfully delivered webhook event within that month.

Once a consumer qualifies as active, they stay active until the month resets. It does not matter how many API calls they make after that first one. One successful call or one hundred, they count as one active consumer for the month.

What does **not** count: Vault calls (connection management), Management API calls, and failed requests (non-2xx responses). A consumer that only authenticates or refreshes tokens without making a downstream data request does not qualify as active.

This is the number that shows up on your invoice. If you have 50 consumers but only 12 made successful API calls this month, you are billed for 12 active consumers.

## Where Does the Data Live?

The downstream accounting system is always the source of truth. Apideck stores zero entity data. No invoices, no contacts, no ledger entries.

What Apideck stores: OAuth tokens, connection metadata, API logs (can be disabled), and consumer configuration.

Every read fetches live data from the accounting system. Every write goes directly to it.

If you need a local cache or data warehouse, build that on top of the API responses. Apideck gives you the pipe. What you do with what comes through it is up to you.

![Apideck stores no entity data — the downstream system is always the source of truth](/guides/understanding-consumers/where_does_the_data_live.png)

## How Many Consumers Should You Create?

The default rule: **one company = one consumer**.

A consumer ID like `acme-corp-123` maps to ACME Corp. Under that single consumer, they can connect multiple accounting platforms at once: QuickBooks, Xero, NetSuite, Sage Intacct, FreshBooks, and more.

### Standard: 1 Company = 1 Consumer

One consumer. Multiple accounting platforms are connected under it. You pass `acme-corp-123` in every API call, regardless of which platform you are reading from.

![One company, one consumer with multiple connected platforms](/guides/understanding-consumers/one_company_one_consumer.png)

### When One Company Needs Multiple Consumers

This applies when a company runs multiple isolated instances of the same platform with no shared data between them. The most common example: regional QuickBooks accounts.

Each QuickBooks instance is a completely separate data silo. Apideck cannot merge them. You create one consumer per isolated account and route API calls accordingly.

![One company with multiple consumers for isolated platform instances](/guides/understanding-consumers/one_company_multiple_consumers.png)

### File Storage APIs

File storage applications like Google Drive do not share data between accounts. Each account is its own silo, so each one requires a separate consumer. If your customer can consolidate access through a Google Shared Drive or by sharing files to a single designated account, you reduce this to one consumer and one connection.

### Test and Production Environments

Developers often ask: how do you handle a customer who has both a sandbox and a production account on the same platform?

In Apideck, you can define multiple applications or environments to support different stages of development (e.g., development > staging > production), or use 1 account to manage numerous applications linked to your SaaS products. You can read this [guide](https://intercom.help/apideck/en/articles/8166593-how-to-manage-an-environment-or-application)to know how to do this.

The second option is to create two consumers. Append `-prod` and `-sandbox` to the consumer ID.

Keeping environments separated means test data never touches production, and credentials never get mixed up. The naming convention does the work: `acme-corp-prod` and `acme-corp-sandbox` are unambiguous from the moment you look at a list.

![Separate consumers for test and production environments](/guides/understanding-consumers/test_vs_prod.png)

## Creating a Consumer

There are three ways to create a consumer, depending on your workflow.

### Through the Vault Widget (Most Common)

In production, most consumers are created automatically through Apideck Vault. Here is how the flow works:

Your backend creates a [Vault session](https://developers.apideck.com/apis/vault/reference#tag/Sessions) by calling the Sessions endpoint with an `x-apideck-consumer-id` header. If a consumer with that ID does not exist yet, Apideck creates one on the spot. Your user then sees the Vault widget, picks an integration (say, QuickBooks), authorizes access, and the connection is live.

The consumer ID you pass in the session request should map to a user or account in your own system. Something like `account:12345` or `acme-corp-123`. This keeps your internal data model and Apideck in sync without any extra bookkeeping.

You can embed the Vault widget directly in your app using [Vault JS](/guides/vault), [Vault React](/guides/vault-react), or [Vault Vue](/guides/vue-vault). If you prefer not to embed anything, the session response also includes a `session_uri` that redirects your user to the hosted Vault application.

> **Important**
>
> Session creation must occur on the server side. Never expose your API key in client-side code.

### From the Dashboard

In the Apideck dashboard, you can create a consumer manually by providing four fields:

- **Consumer ID** - your unique identifier for this consumer (e.g., `acme-corp-123`)
- **Email** - the consumer's email address
- **Username** - a username for the consumer
- **Account Name** - the display name for this consumer

Once created, you can manage their integrations, check API call stats, review request logs, and monitor usage from the Consumer Dashboard.

![Creating a consumer from the Apideck dashboard](/guides/understanding-consumers/create-a-consumer.png)

### Via the API

You can also create consumers programmatically through the Vault API. This is useful for bulk provisioning or automated onboarding pipelines that require no user interaction upfront.

### Connection States

After a consumer connects an integration through Vault, the connection moves through a series of states. The one that matters most: **callable**. A connection in the `callable` state means authorization is complete, credentials are valid, and you can make API calls against it.

The full lifecycle goes: `available` (integration enabled but not yet connected) > `added` (consumer started the connection but has not authorized) > `authorized` (OAuth complete, may require additional configuration, such as selecting a tenant) > `callable` (ready to use).

If credentials expire or become invalid, the state drops to `invalid` and your API calls will fail until the consumer reauthorizes. For the full breakdown, see the [Connection States guide](/guides/connection-states).

## Using the Consumer ID in API Calls

Every API call you make to Apideck requires two identifiers in the request headers:

- **Consumer ID** - tells Apideck which of your customers the request is for
- **Service ID** - tells Apideck which downstream app to route the call to (e.g., `quickbooks`, `xero`, `netsuite`)

You never hardcode credentials or manage OAuth tokens yourself. Pass these two IDs, and Apideck resolves the connection, authentication, and routing.

![Consumer ID and Service ID headers in an API call](/guides/understanding-consumers/api-headers.png)

## What's Next

Now that you understand how consumers work, here are the logical next steps:

- [**Set up Apideck Vault**](/guides/vault) to let your customers connect their accounts
- [**Make your first API call**](/get-started) using a consumer ID and service ID
- [**Review the pricing page**](https://www.apideck.com/pricing) to understand how consumer counts affect your plan