Accounts v2

An Account v2 object represents a company, individual, or other entity that your Stripe integration interacts with. It contains both identifying information and properties that control its behavior and functionality. An Account can have one or more configurations that enable sets of related features, such as allowing it to act as a merchant or customer. The Accounts v2 API is broadly available to Connect platforms, and to other users in preview. The Accounts v2 API also supports the Global Payouts preview feature.

Learn more about calling API v2 endpoints.

Was this section helpful? Yes No

Create an account

POST / v2 / core / accounts

Update an account

POST / v2 / core / accounts /:id

Retrieve an account

GET / v2 / core / accounts /:id

List accounts

GET / v2 / core / accounts

Close an account

POST / v2 / core / accounts /:id / close

The Account object v2

Attributes

id string Unique identifier for the Account.
object string, value is "v2.core.account" String representing the object’s type. Objects of the same type share the same value of the object field.
applied _ configurations array of enums The configurations that have been applied to this account. Possible enum values customer The Account can be used as a customer. merchant The Account can be used as a merchant. recipient The Account can be used as a recipient.
closed nullable boolean Indicates whether the account has been closed.
configuration nullable object An Account represents a company, individual, or other entity that a user interacts with. Accounts store identity information and one or more configurations that enable product-specific capabilities. You can assign configurations at creation or add them later.
contact _ email nullable string The primary contact email address for the Account.
contact _ phone nullable string The default contact phone for the Account.
created timestamp Time at which the object was created. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.
dashboard nullable enum Connect Only A value indicating the Stripe dashboard this Account has access to. This will depend on which configurations are enabled for this account. Possible enum values express The Account has access to the Express hosted dashboard. full The Account has access to the full Stripe hosted dashboard. none The Account does not have access to any Stripe hosted dashboard.
defaults nullable object Default values for settings shared across Account configurations.
display _ name nullable string A descriptive name for the Account. This name will be surfaced in the Stripe Dashboard and on any invoices sent to the Account.
future _ requirements nullable object Information about the future requirements for the Account that will eventually come into effect, including what information needs to be collected, and by when.
identity nullable object Information about the company, individual, and business represented by the Account.
livemode boolean Has the value true if the object exists in live mode or the value false if the object exists in test mode.
metadata nullable map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
requirements nullable object Information about the active requirements for the Account, including what information needs to be collected, and by when.

The Account object

{ "id": "acct_1Nv0FGQ9RKHgCVdK", "object": "v2.core.account", "applied_configurations": [ "customer", "merchant" ], "configuration": { "customer": { "automatic_indirect_tax": { "exempt": "none", "location": { "country": "US", "state": "NY" }, "location_source": "identity_address" }, "billing": { "invoice": { "next_sequence": 1, "prefix": "5626C87C", "custom_fields": [] } }, "capabilities": { "automatic_indirect_tax": { "status": "active", "status_details": [] } } }, "merchant": { "card_payments": { "decline_on": { "avs_failure": false, "cvc_failure": false } }, "capabilities": { "card_payments": { "status": "active", "status_details": [] }, "stripe_balance": { "payouts": { "status": "active", "status_details": [] } } } } }, "contact_email": "furever@example.com", "created": "2025-03-28T19:59:16.000Z", "dashboard": "full", "identity": { "business_details": { "registered_name": "Furever", "address": { "country": "US", "postal_code": "10001" }, "additional_addresses": [ { "purpose": "principal_place_of_business", "country": "US", "line1": "354 Oyster Point Blvd", "city": "South San Francisco", "state": "CA", "postal_code": "94080" }, { "purpose": "administrative", "country": "US", "line1": "510 Townsend St", "city": "San Francisco", "state": "CA", "postal_code": "94103" } ] }, "country": "US", "entity_type": "company" }, "defaults": { "currency": "usd", "responsibilities": { "fees_collector": "stripe", "losses_collector": "stripe", "requirements_collector": "stripe" } }, "display_name": "Furever"}

Create an account v2

POST / v2 / core / accounts

Create an Account that represents a company, individual, or other entity that your business interacts with. Accounts contain identifying information about the entity, and configurations that store the features an account has access to. An account can be configured as any or all of the following configurations: Customer, Merchant and/or Recipient.

Learn more about calling API v2 endpoints.

Parameters

account _ token string The account token generated by the account token API.
configuration object An Account Configuration which allows the Account to take on a key persona across Stripe products.
contact _ email string The primary contact email address for the Account.
contact _ phone string The default contact phone for the Account.
dashboard enum Connect Only A value indicating the Stripe dashboard this Account has access to. This will depend on which configurations are enabled for this account. Possible enum values express The Account has access to the Express hosted dashboard. full The Account has access to the full Stripe hosted dashboard. none The Account does not have access to any Stripe hosted dashboard.
defaults object Default values to be used on Account Configurations.
display _ name string A descriptive name for the Account. This name will be surfaced in the Stripe Dashboard and on any invoices sent to the Account.
identity object Information about the company, individual, and business represented by the Account.
include array of enums Additional fields to include in the response. Possible enum values configuration.customer Include parameter to expose configuration.customer on an Account. configuration.merchant Include parameter to expose configuration.merchant on an Account. configuration.recipient Include parameter to expose configuration.recipient on an Account. defaults Include parameter to expose defaults on an Account. future_requirements Include parameter to expose future_requirements on an Account. identity Include parameter to expose identity on an Account. requirements Include parameter to expose requirements on an Account.
metadata map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

Returns

Returns an Account object.

Error Codes

400 account _ capability _ not _ supported

Requested capability is not available.

400 account _ configuration _ not _ supported

The requested configuration is not available for the account.

400 account _ controller _ express _ dash _ without _ application _ losses _ or _ fees

If dashboard is express, fees_collector must be application and losses_collector must be application.

400 account _ controller _ stripe _ pricing _ platform _ liable

If losses_collector is application, fees_collector must also be application.

400 account _ controller _ ua _ unsupported _ configuration

Connect integration combination is not supported when UA beta is enabled.

400 account _ controller _ unsupported _ configuration

Connect integration combination is not supported when UA beta is disabled.

400 account _ controller _ unsupported _ configuration _ private _ preview

Responsibility combinations is not supported in private preview.

400 account _ country _ unsupported _ currency

Currency is not allowed for the account’s country.

400 account _ create _ activation _ required

Platform must be activated to create connected accounts.

400 account _ creation _ invalid

Account creation is invalid.

400 account _ creation _ liability _ unacknowledged

Account creation error - liability unacknowledged.

400 account _ creation _ losses _ collector _ unavailable

Account creation error - losses collector unavailable.

400 account _ creation _ requirement _ collection _ and _ liability _ unacknowledged

Account creation error - requirement collection and liability unacknowledged.

400 account _ creation _ requirement _ collection _ unacknowledged

Account creation error - requirement collection unacknowledged.

400 account _ terms _ of _ service _ not _ accepted

400 account _ token _ required

Account token required for platforms in mandated countries (e.g., France).

400 accounts _ v2 _ access _ blocked

Accounts v2 is not enabled for your merchant.

400 address _ characters _ invalid

Invalid characters are provided for address fields.

400 address _ country _ identity _ country _ mismatch

Address country doesn’t match identity country.

400 address _ postal _ code _ invalid

Address postal code is invalid.

400 address _ state _ invalid

Address state is invalid.

400 address _ town _ invalid

Address town is invalid.

400 bgn _ bank _ accounts _ unsupported

Creating accounts with the BGN currency is no longer supported, as Bulgaria is now using the Euro as of 2026-01-01.

400 can _ create _ platform _ owned _ onboarding _ accounts _ required

Dormant accounts cannot create accounts where requirements collector is application (this is an account takeover prevention measure).

400 cannot _ create _ connected _ account

Platform is in an invalid state and cannot create connected accounts.

400 cannot _ create _ new _ account _ rejected

Platform is in a rejected state and cannot create connected accounts.

400 capability _ cannot _ be _ unrequested _ due _ to _ other _ capability _ requirement

Feature cannot be unrequested due to being a requirement for another feature.

400 capability _ not _ available _ for _ dashboard _ type

Feature cannot be requested for the dashboard type.

400 capability _ not _ available _ for _ entity _ type _ in _ country

Requested feature is not available for the entity type in your country.

400 capability _ not _ available _ for _ loss _ collector

A v2 Account cannot have both the specified capability and Stripe-owned loss liability.

400 capability _ not _ available _ in _ country

Requested capability is not available in your country.

400 capability _ not _ available _ in _ platform _ country

Feature cannot be requested given the platform’s country.

400 capability _ not _ available _ without _ other _ capability

Requested feature is not available without also requesting a different feature.

400 capability _ not _ available _ without _ other _ capability _ in _ country

Requested feature is not available without also requesting a different feature in your country.

400 configuration _ creation _ invalid

Cannot create an account with an invalid configuration.

400 connect _ identity _ not _ verified

Platform is not verified and cannot create connected accounts.

400 connect _ profile _ not _ submitted

Platform has not completed platform questionnaire and cannot create connected accounts.

400 cross _ border _ connected _ account _ creation _ not _ allowed

Cross-border connected account creation is not allowed for this platform/account country combination.

400 custom _ account _ beta

Custom accounts cannot be created in certain countries.

400 date _ of _ birth _ age _ restriction

Representative date of birth does not meet the age limit.

400 date _ of _ birth _ invalid

Representative date of birth is provided an invalid date or a future date.

400 default _ currency _ immutable

Cannot change defaults.currency post account activation.

400 default _ payment _ method _ invalid

Default payment method provided for a customer does not exist or is otherwise invalid.

400 default _ payment _ method _ invalid _ type

Specified payment method exists but its type is not allowed to be the default payment method.

400 directorship _ declaration _ not _ allowed _ during _ account _ creation

Directorship declaration is not allowed during account creation.

400 document _ invalid

Provided file tokens for documents are invalid, not found, deleted, or belong to a different account.

400 document _ purpose _ invalid

Provided file tokens for documents are of the wrong purpose.

400 email _ domain _ invalid _ for _ recipient

Email contains unsupported domain.

400 email _ invalid

Incorrect email is provided.

400 entity _ type _ not _ supported _ in _ country

The identity.entity_type value is not supported in a given identity.country.

400 high _ risk _ activities _ none _ cant _ be _ combined _ with _ other _ options

NONE is combined with another value in the HighRiskActivities list.

400 id _ number _ invalid

Provided ID number is of the wrong format for the given type.

400 identity _ country _ required

The identity.country value is required but not provided.

400 incorrect _ id _ number _ for _ country

Incorrect ID number is provided for a country.

400 incorrect _ token _ wrong _ type

The incorrect token type is provided.

400 invalid _ id _ number _ for _ structure

ID number is provided that is not permitted for the Identity’s entity type and business structure.

400 invalid _ id _ number _ registrar

The identity.business_details.id_numbers.registrar value is an invalid DE registrar.

400 invalid _ konbini _ payments _ support _ hours

Konbini Payments Support Hours is Invalid.

400 invalid _ konbini _ payments _ support _ phone _ number

Konbini Payments Support Phone Number is Invalid.

400 invalid _ sepa _ creditor _ id _ format

The the related setting Creditor Identifier is invalid.

400 invalid _ timezone

Timezone provided in account defaults is invalid.

400 invoice _ rendering _ template _ invalid

Invoice rendering template does not exist or is otherwise invalid.

400 ip _ address _ invalid

Invalid IP address is provided.

400 mcc _ invalid

MCC is invalid for configuration.merchant.mcc.

400 non _ connect _ platform _ accounts _ v2 _ access _ blocked

Needs to use the newer API version or onboard to Connect.

400 non _ jp _ kana _ kanji _ address

Kana Kanji script addresses must have JP country.

400 ownership _ declaration _ not _ allowed _ during _ account _ creation

Ownership declaration is not allowed during account creation.

400 param _ alongside _ account _ token

Parameter cannot be passed alongside account_token.

400 person _ percent _ ownership _ invalid

Error returned when relationship.owner is set to true but the ownership percentage is set to 0%.

400 phone _ invalid

Phone number is invalid.

400 platform _ registration _ required

The direct merchant has not signed up for Connect and cannot create connected accounts.

400 postal _ code _ required _ for _ jp _ address

Postal code is required for Japanese addresses.

400 purpose _ of _ funds _ description _ must _ be _ empty _ for _ non _ other _ purpose _ of _ funds

PurposeOfFundsDescription is not empty while PurposeOfFunds is not the related setting.

400 registration _ date _ invalid

Registration date must be in the past.

400 script _ characters _ invalid

Provided script characters are invalid for the script.

400 sepa _ debit _ creditor _ identifier _ not _ allowed

The the related setting Creditor Identifier is blocked from use at Stripe.

400 sepa _ debit _ stripe _ creditor _ identifier

A Stripe-owned shared the related setting Creditor Identifier cannot be set as a custom identifier.

400 shipping _ address _ required

Shipping address is required within the shipping hash.

400 shipping _ name _ required

Shipping name is required within the shipping hash.

400 statement _ descriptor _ invalid

Statement descriptor is invalid.

400 structure _ incompatible _ for _ entity _ type _ country

The business_details.structure value is not valid for identity.country and identity.entity_type.

400 test _ clock _ disallowed _ on _ live _ mode

Cannot set a test clock on a livemode customer.

400 test _ clock _ invalid

Test clock does not exist or is otherwise invalid.

400 test _ clocks _ advance _ in _ progress

Cannot modify a test clock that is currently advancing.

400 test _ clocks _ customer _ limit _ reached

Cannot add customer to a test clock that has already reached its customer limit.

400 token _ already _ used

The token is re-used with a different idempotency key.

400 token _ expired

Token has expired.

400 tos _ acceptance _ on _ behalf _ not _ allowed

TOS cannot be accepted on behalf of accounts when requirement collection is stripe.

400 unsupported _ field _ for _ configs

Cannot set responsibilities on the current configurations.

400 unsupported _ identity _ field _ for _ configs

Cannot set identity fields when the Account is only configured as a customer.

400 unsupported _ postal _ code

Address is in an unsupported postal code.

400 unsupported _ state

Address is in an unsupported state.

400 url _ invalid

URL is invalid.

400 v1 _ token _ invalid _ in _ v2

A v1 token ID is passed in v2 APIs.

403 invalid _ account _ token

Invalid account token.

409 idempotency _ error

An idempotent retry occurred with different request parameters.

429 account _ rate _ limit _ exceeded

Account cannot exceed a configured concurrency rate limit on updates.

Response

{ "id": "acct_1Nv0FGQ9RKHgCVdK", "object": "v2.core.account", "applied_configurations": [ "customer", "merchant" ], "configuration": { "customer": { "applied": "2025-03-28T19:59:16.000Z", "automatic_indirect_tax": { "exempt": "none", "location_source": "identity_address" }, "billing": { "invoice": { "next_sequence": 1, "prefix": "5626C87C", "custom_fields": [] } }, "capabilities": { "automatic_indirect_tax": { "status": "active", "status_details": [] } } }, "merchant": { "applied": "2025-03-28T19:59:16.000Z", "card_payments": { "decline_on": { "avs_failure": false, "cvc_failure": false } }, "capabilities": { "card_payments": { "status": "active", "status_details": [] }, "stripe_balance": { "payouts": { "status": "active", "status_details": [] } } } } }, "contact_email": "furever@example.com", "created": "2025-03-28T19:59:16.000Z", "dashboard": "full", "identity": { "business_details": { "registered_name": "Furever", "additional_addresses": [ { "purpose": "principal_place_of_business", "country": "US", "line1": "354 Oyster Point Blvd", "city": "South San Francisco", "state": "CA", "postal_code": "94080" }, { "purpose": "administrative", "country": "US", "line1": "510 Townsend St", "city": "San Francisco", "state": "CA", "postal_code": "94103" } ] }, "country": "US", "entity_type": "company" }, "livemode": false, "defaults": { "currency": "usd", "responsibilities": { "fees_collector": "stripe", "losses_collector": "stripe", "requirements_collector": "stripe" } }, "display_name": "Furever"}