Accounts

An account is any party a merchant transacts with on Frame. A buyer who pays for a t-shirt is an account. A creator who receives payouts is an account. A business that gets onboarded onto your platform is an account. One primitive, every flavor of counterparty.

Customer vs Account

If you've used Frame before, you've seen the Customer model. Account replaces Customer as the canonical party model. The Customer model is wire-compatible forever — old endpoints keep working, old IDs keep resolving — but new flows, new docs, and new guides all model parties as accounts.

Here's the practical distinction:

A Customer was always a buyer. There was nothing else it could be. If you needed to pay someone out, model their identity, or run KYC, you reached for a different primitive.
An Account is shape-agnostic. The same Account can be a buyer one day and the recipient of a payout the next. Which side of a transaction it sits on is determined by the capabilities it has, not by which model you created.

This matters because the previous structure forced platforms to maintain parallel objects for the same real-world person. If your marketplace had buyers who later became sellers, you had to create a Customer and then a Customer-flavor onboarding session and then thread the IDs together. Accounts collapse that — one party object, capabilities turned on as the relationship grows.

If you're integrating fresh, use accounts everywhere. If you have a Customer-based integration in production, it keeps working — there is no migration deadline, no schema change, no merchant churn. Add account-based flows as you build new features.

Account types

Every account has a type. The type is set at creation and determines which profile fields apply and which verification flows are available.

Type	When to use
`individual`	Sole proprietors, creators, freelancers, end users on a marketplace, anyone who is a person rather than a registered entity.
`business`	LLCs, corporations, partnerships — entities with a legal registration.
`merchant`	Reserved for platform merchants — the entity holding the API key, your own organization on Frame. Created by Frame at merchant signup; not the type you pass when modeling the buyers, sellers, or platform users your application transacts with.

For the parties your application transacts with, use individual or business. merchant represents you (the platform) and is provisioned during signup, not on the fly.

Most Frame verification products (KYC, phone verification, address verification, age verification) operate on individuals. Businesses follow a separate model: Frame runs KYB on the legal entity while simultaneously onboarding each owner or controller as an individual account in parallel.

State

An account walks through four states:

pending — the account has been created but at least one requested capability hasn't activated yet. Most accounts spend time here.
active — every requested capability is active. The account can do everything it was created to do.
restricted — the account is temporarily limited (for example, a verification check needs re-running, or a compliance review is in progress). Use the restrict/unrestrict admin endpoints to transition into and out of this state; capabilities behave as if the account were pending while restricted.
disabled — the account has been suspended. Disabled accounts can't initiate or receive payments and all capabilities are suspended. Contact Frame support to re-enable.

State transitions are driven by capability status changes, not by direct API calls. Update profile fields, attach a payment method, or accept terms of service, and Frame re-runs the underlying capability checks automatically. Disable the account explicitly via DELETE/v1/accounts/{id}.

Relationships

An account is the party; the rest of the platform attaches to it.

Capability is what an account can do. Card payments, payouts, KYC, age verification — each is a named capability with its own status and requirements. Accounts can have many capabilities, each independently activated. See capabilities for the lifecycle.

Onboarding sessions collect the information a capability needs to activate. When you request a capability whose requirements aren't yet met, the next step is usually to create an onboarding session, redirect the account holder, and let Frame's hosted flow gather the rest.

Money movement is anchored to accounts. Every Transfer is attributed to an account so you can reconcile activity per buyer, per seller, per platform user.

Gotchas

Symptom: you have two accounts for the same buyer in production. Why: if you're creating accounts on every checkout without checking for an existing one, returning customers accumulate duplicates. Fix: dedupe by email scoped to your merchant before creating — or use external_id to pin a Frame account to a record in your own system.

Symptom: you requested a capability but its currently_due array is empty and yet it's still pending. Why: the capability is waiting on a back-channel check that the account holder can't satisfy through profile fields (a verification result still pending, a document still being reviewed). Fix: listen for capability.activated (or capability.disabled if the check fails) webhooks; the capability transitions when the check resolves, with no further action needed on your side.

Reference

For the full API surface, see POST/v1/accounts and the rest of the Accounts resource.