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.

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.

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.

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 guideto 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.

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 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, Vault React, or Vault Vue. If you prefer not to embed anything, the session response also includes a session_uri that redirects your user to the hosted Vault application.

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.

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.

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.

What's Next

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

• Set up Apideck Vault to let your customers connect their accounts
• Make your first API call using a consumer ID and service ID
• Review the pricing page to understand how consumer counts affect your plan