An Account is a representation of a company, individual or other entity that a user 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.
Parameters
- configurationobject
An Account Configuration which allows the Account to take on a key persona across Stripe products.
- contact_
emailstring The default contact email address for the Account. Required when configuring the account as a merchant or recipient.
- dashboardenum
A value indicating the Stripe dashboard this Account has access to. This will depend on which configurations are enabled for this account.
Possible enum valuesexpressThe Account has access to the Express hosted dashboard.
fullThe Account has access to the full Stripe hosted dashboard.
noneThe Account does not have access to any Stripe hosted dashboard.
- defaultsobject
Default values to be used on Account Configurations.
- display_
namestring A descriptive name for the Account. This name will be surfaced in the Stripe Dashboard and on any invoices sent to the Account.
- identityobject
Information about the company, individual, and business represented by the Account.
- includearray of enums
Additional fields to include in the response.
Possible enum valuesconfiguration.customer Include parameter to expose
configuration.on an Account.customer configuration.merchant Include parameter to expose
configuration.on an Account.merchant configuration.recipient Include parameter to expose
configuration.on an Account.recipient defaultsInclude parameter to expose
defaultson an Account.identityInclude parameter to expose
identityon an Account.requirementsInclude parameter to expose
requirementson an Account. - metadatamap
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
Response attributes
- idstring
Unique identifier for the Account.
- objectstring, 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_
configurationsarray of enums Filter only accounts that have all of the configurations specified. If omitted, returns all accounts regardless of which configurations they have.
Possible enum valuescustomerThe Account can be used as a customer.
merchantThe Account can be used as a merchant.
recipientThe Account can be used as a recipient.
- configurationnullable object
An Account Configuration which allows the Account to take on a key persona across Stripe products.
- contact_
emailnullable string The default contact email address for the Account. Required when configuring the account as a merchant or recipient.
- createdtimestamp
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.
- dashboardnullable enum
A value indicating the Stripe dashboard this Account has access to. This will depend on which configurations are enabled for this account.
Possible enum valuesexpressThe Account has access to the Express hosted dashboard.
fullThe Account has access to the full Stripe hosted dashboard.
noneThe Account does not have access to any Stripe hosted dashboard.
- defaultsnullable object
Default values to be used on Account Configurations.
- display_
namenullable string A descriptive name for the Account. This name will be surfaced in the Stripe Dashboard and on any invoices sent to the Account.
- identitynullable object
Information about the company, individual, and business represented by the Account.
- livemodeboolean
Has the value
trueif the object exists in live mode or the valuefalseif the object exists in test mode. - metadatanullable 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.
- requirementsnullable object
Information about the requirements for the Account, including what information needs to be collected, and by when.
If dashboard is express, fees_ must be application and losses_ must be application.
If losses_ is application, fees_ must also be application.
Connect integration combination is not supported.
Responsibility combinations is not supported in private preview.
Currency is not allowed for the account’s country.
Platform must be activated to create connected accounts.
Account creation is invalid.
Invalid characters are provided for address fields.
Address country doesn’t match identity country.
Address postal code is invalid.
Address state is invalid.
Address town is invalid.
Dormant accounts cannot create accounts where requirements collector is application (this is an account takeover prevention measure).
Platform is in an invalid state and cannot create connected accounts.
Platform is in a rejected state and cannot create connected accounts.
Feature cannot be unrequested due to being a requirement for another feature.
Feature cannot be requested for the dashboard type.
Requested feature is not available for the entity type in your country.
Requested capability is not available in your country.
Feature cannot be requested given the platform’s country.
Requested feature is not available without also requesting a different feature.
Requested feature is not available without also requesting a different feature in your country.
Cannot create an account with an invalid configuration.
Platform is not verified and cannot create connected accounts.
Platform has not completed platform questionnaire and cannot create connected accounts.
Custom accounts cannot be created in certain countries.
Representative date of birth does not meet the age limit.
Representative date of birth is provided an invalid date or a future date.
Cannot change defaults. post account activation.
Default payment method provided for a customer does not exist or is otherwise invalid.
Specified payment method exists but its type is not allowed to be the default payment method.
Provided file tokens for documents are invalid, not found, deleted, or belong to a different account.
Provided file tokens for documents are of the wrong purpose.
Email contains unsupported domain.
Incorrect email is provided.
The identity. value is not supported in a given identity..
Provided ID number is of the wrong format for the given type.
The identity. value is required but not provided.
Incorrect ID number is provided for a country.
ID number is provided that is not permitted for the Identity’s entity type and business structure.
The identity. value is an invalid DE registrar.
Invoice rendering template does not exist or is otherwise invalid.
Invalid IP address is provided.
MCC is invalid for configuration..
Kana Kanji script addresses must have JP country.
Error returned when relationship.owner is set to true but the ownership percentage is set to 0%.
Phone number is invalid.
Platform has not signed up for Connect and cannot create connected accounts.
Provided script characters are invalid for the script.
Shipping address is required within the shipping hash.
Shipping name is required within the shipping hash.
Statement descriptor is invalid.
The business_ value is not valid for identity. and identity..
Cannot set a test clock on a livemode customer.
Test clock does not exist or is otherwise invalid.
Cannot modify a test clock that is currently advancing.
Cannot add customer to a test clock that has already reached its customer limit.
TOS cannot be accepted on behalf of accounts when requirement collection is stripe.
Cannot set responsibilities on the current configurations.
Cannot set identity fields when the Account is only configured as a customer.
URL is invalid.
An idempotent retry occurred with different request parameters.
{ "id": "acct_1Nv0FGQ9RKHgCVdK", "object": "v2.core.account", "applied_configurations": [ "customer", "merchant" ], "configuration": { "customer": { "automatic_indirect_tax": { "exempt": "none", "location_source": "identity_address" }, "billing": { "invoice": { "next_sequence": 1, "prefix": "5626C87C" } }, "capabilities": { "automatic_indirect_tax": { "requested": true, "status": "active" } } }, "merchant": { "card_payments": { "decline_on": { "avs_failure": false, "cvc_failure": false } }, "capabilities": { "card_payments": { "requested": true, "status": "active" }, "stripe_balance": { "payouts": { "requested": true, "status": "active" } } } } }, "contact_email": "furever@example.com", "created": "2025-03-28T19:59:16.000Z", "dashboard": "full", "identity": { "business_details": { "registered_name": "Furever" }, "country": "US", "entity_type": "company" }, "defaults": { "currency": "usd", "responsibilities": { "fees_collector": "stripe", "losses_collector": "stripe" } }, "display_name": "Furever"}Updates the details of an Account.
Parameters
- idstringRequired
The ID of the Account to update.
- configurationobject
An Account Configuration which allows the Account to take on a key persona across Stripe products.
- contact_
emailstring The default contact email address for the Account. Required when configuring the account as a merchant or recipient.
- dashboardenum
A value indicating the Stripe dashboard this Account has access to. This will depend on which configurations are enabled for this account.
Possible enum valuesexpressThe Account has access to the Express hosted dashboard.
fullThe Account has access to the full Stripe hosted dashboard.
noneThe Account does not have access to any Stripe hosted dashboard.
- defaultsobject
Default values to be used on Account Configurations.
- display_
namestring A descriptive name for the Account. This name will be surfaced in the Stripe Dashboard and on any invoices sent to the Account.
- identityobject
Information about the company, individual, and business represented by the Account.
- includearray of enums
Additional fields to include in the response.
Possible enum valuesconfiguration.customer Include parameter to expose
configuration.on an Account.customer configuration.merchant Include parameter to expose
configuration.on an Account.merchant configuration.recipient Include parameter to expose
configuration.on an Account.recipient defaultsInclude parameter to expose
defaultson an Account.identityInclude parameter to expose
identityon an Account.requirementsInclude parameter to expose
requirementson an Account. - metadatamap
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
Response attributes
- idstring
Unique identifier for the Account.
- objectstring, 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_
configurationsarray of enums Filter only accounts that have all of the configurations specified. If omitted, returns all accounts regardless of which configurations they have.
Possible enum valuescustomerThe Account can be used as a customer.
merchantThe Account can be used as a merchant.
recipientThe Account can be used as a recipient.
- configurationnullable object
An Account Configuration which allows the Account to take on a key persona across Stripe products.
- contact_
emailnullable string The default contact email address for the Account. Required when configuring the account as a merchant or recipient.
- createdtimestamp
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.
- dashboardnullable enum
A value indicating the Stripe dashboard this Account has access to. This will depend on which configurations are enabled for this account.
Possible enum valuesexpressThe Account has access to the Express hosted dashboard.
fullThe Account has access to the full Stripe hosted dashboard.
noneThe Account does not have access to any Stripe hosted dashboard.
- defaultsnullable object
Default values to be used on Account Configurations.
- display_
namenullable string A descriptive name for the Account. This name will be surfaced in the Stripe Dashboard and on any invoices sent to the Account.
- identitynullable object
Information about the company, individual, and business represented by the Account.
- livemodeboolean
Has the value
trueif the object exists in live mode or the valuefalseif the object exists in test mode. - metadatanullable 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.
- requirementsnullable object
Information about the requirements for the Account, including what information needs to be collected, and by when.
If dashboard is express, fees_ must be application and losses_ must be application.
If losses_ is application, fees_ must also be application.
Connect integration combination is not supported.
Responsibility combinations is not supported in private preview.
Currency is not allowed for the account’s country.
Invalid characters are provided for address fields.
Address country doesn’t match identity country.
Address postal code is invalid.
Address state is invalid.
Address town is invalid.
Default payment method is added to the customer config before attaching it to the account using /v1/payment_.
Dormant accounts cannot create accounts where requirements collector is application (this is an account takeover prevention measure).
Cannot set automatic_ when initially creating a customer configuration.
Feature cannot be unrequested due to being a requirement for another feature.
Feature cannot be requested for the dashboard type.
Requested feature is not available for the entity type in your country.
Requested capability is not available in your country.
Feature cannot be requested given the platform’s country.
Requested feature is not available without also requesting a different feature.
Requested feature is not available without also requesting a different feature in your country.
Cannot create an account with an invalid configuration.
Custom accounts cannot be created in certain countries.
Invalid customer tax location.
Representative date of birth does not meet the age limit.
Representative date of birth is provided an invalid date or a future date.
Cannot change defaults. post account activation.
Outbound Destination ID is invalid.
Default payment method provided for a customer does not exist or is otherwise invalid.
Provided file tokens for documents are invalid, not found, deleted, or belong to a different account.
Provided file tokens for documents are of the wrong purpose.
Duplicate person is added to an account.
Email contains unsupported domain.
Incorrect email is provided.
The identity. value is not supported in a given identity..
Provided ID number is of the wrong format for the given type.
The identity. value is required but not provided.
Identity param has been made immutable due to the state of the account.
Incorrect ID number is provided for a country.
ID number is provided that is not permitted for the Identity’s entity type and business structure.
The identity. value is an invalid DE registrar.
Invalid IP address is provided.
MCC is invalid for configuration..
Kana Kanji script addresses must have JP country.
Error returned when relationship.owner is set to true but the ownership percentage is set to 0%.
Phone number is invalid.
Provided script characters are invalid for the script.
Shipping address is required within the shipping hash.
Shipping name is required within the shipping hash.
Statement descriptor is invalid.
The business_ value is not valid for identity. and identity..
Cannot set a test clock on a livemode customer.
Test clock does not exist or is otherwise invalid.
TOS cannot be accepted on behalf of accounts when requirement collection is stripe.
Total ownership percentages of all Persons on the account exceeds 100%.
Cannot set responsibilities on the current configurations.
Cannot set identity fields when the Account is only configured as a customer.
URL is invalid.
V1 Account ID cannot be used in V2 Account APIs.
V1 Customer ID cannot be used in V2 Account APIs.
The resource wasn’t found.
An idempotent retry occurred with different request parameters.
{ "id": "acct_1Nv0FGQ9RKHgCVdK", "object": "v2.core.account", "applied_configurations": [ "merchant" ], "contact_email": "furever@example.com", "created": "2024-11-26T16:33:03.000Z", "dashboard": "none", "identity": { "business_details": { "doing_business_as": "FurEver", "id_numbers": [ { "type": "us_ein" } ], "product_description": "Saas pet grooming platform at furever.dev using Connect embedded components", "structure": "sole_proprietorship", "url": "http://accessible.stripe.com" }, "country": "US" }, "display_name": "Furever", "metadata": {}}Retrieves the details of an Account.
Parameters
- idstringRequired
The ID of the Account to retrieve.
- includearray of enums
Additional fields to include in the response.
Possible enum valuesconfiguration.customer Include parameter to expose
configuration.on an Account.customer configuration.merchant Include parameter to expose
configuration.on an Account.merchant configuration.recipient Include parameter to expose
configuration.on an Account.recipient defaultsInclude parameter to expose
defaultson an Account.identityInclude parameter to expose
identityon an Account.requirementsInclude parameter to expose
requirementson an Account.
Returns
Response attributes
- idstring
Unique identifier for the Account.
- objectstring, 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_
configurationsarray of enums Filter only accounts that have all of the configurations specified. If omitted, returns all accounts regardless of which configurations they have.
Possible enum valuescustomerThe Account can be used as a customer.
merchantThe Account can be used as a merchant.
recipientThe Account can be used as a recipient.
- configurationnullable object
An Account Configuration which allows the Account to take on a key persona across Stripe products.
- contact_
emailnullable string The default contact email address for the Account. Required when configuring the account as a merchant or recipient.
- createdtimestamp
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.
- dashboardnullable enum
A value indicating the Stripe dashboard this Account has access to. This will depend on which configurations are enabled for this account.
Possible enum valuesexpressThe Account has access to the Express hosted dashboard.
fullThe Account has access to the full Stripe hosted dashboard.
noneThe Account does not have access to any Stripe hosted dashboard.
- defaultsnullable object
Default values to be used on Account Configurations.
- display_
namenullable string A descriptive name for the Account. This name will be surfaced in the Stripe Dashboard and on any invoices sent to the Account.
- identitynullable object
Information about the company, individual, and business represented by the Account.
- livemodeboolean
Has the value
trueif the object exists in live mode or the valuefalseif the object exists in test mode. - metadatanullable 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.
- requirementsnullable object
Information about the requirements for the Account, including what information needs to be collected, and by when.
V1 Account ID cannot be used in V2 Account APIs.
V1 Customer ID cannot be used in V2 Account APIs.
The resource wasn’t found.
{ "id": "acct_1Nv0FGQ9RKHgCVdK", "object": "v2.core.account", "applied_configurations": [ "merchant", "customer" ], "configuration": { "merchant": { "card_payments": { "decline_on": { "avs_failure": false, "cvc_failure": false } }, "capabilities": { "card_payments": { "requested": true, "status": "restricted", "status_details": [ { "code": "requirements_past_due", "resolution": "provide_info" } ] } }, "statement_descriptor": { "descriptor": "accessible.stripe.com" }, "mcc": "5734" } }, "contact_email": "furever@example.com", "created": "2024-11-26T16:33:03.000Z", "dashboard": "none", "identity": { "business_details": { "doing_business_as": "FurEver", "id_numbers": [ { "type": "us_ein" } ], "product_description": "Saas pet grooming platform at furever.dev using Connect embedded components", "structure": "sole_proprietorship", "url": "http://accessible.stripe.com" }, "country": "us" }, "display_name": "Furever", "metadata": {}}Returns a list of Accounts.
Parameters
- applied_
configurationsarray of strings Filter only accounts that have all of the configurations specified. If omitted, returns all accounts regardless of which configurations they have.
- limitinteger
The upper limit on the number of accounts returned by the List Account request.
- pagestring
The page token to navigate to next or previous batch of accounts given by the list request.
Returns
Response attributes
- dataarray of objects
A list of retrieved Account objects.
- next_
page_ urlnullable string URL with page token to navigate to next batch of accounts given by the list request.
- previous_
page_ urlnullable string URL with page token to navigate to previous batch of accounts given by the list request.
{ "data": [ { "id": "acct_1QP3oLBUFVXWiKFB", "object": "v2.core.account", "applied_configurations": [ "customer" ], "contact_email": "jenny.rosen@example.com", "created": "2024-11-25T15:02:50.000Z", "display_name": "Jenny Rosen", "metadata": {} }, { "id": "acct_1QO24tPeVxUa6gV6", "object": "v2.core.account", "applied_configurations": [ "recipient", "customer", "merchant" ], "contact_email": "jenny.rosen@example.com", "created": "2024-11-22T18:59:45.000Z", "dashboard": "none", "display_name": "Jenny Rosen 2", "metadata": { "my_key": "my_value" } } ], "next_page_url": "/v2/core/accounts?page=page_5dr8SFDbv7rZ2aj4ZSGuf4J1Dv58yE0YM4BhBqb2tg94CD5PDoUA7RD2AE7VBEH5C0E0qGJi1wMFPf9MEBbh6M125&limit=2&applied_configurations=customer"}Removes access to the Account and its associated resources.
Parameters
- idstringRequired
The ID of the Account to close.
- applied_
configurationsarray of enums Configurations on the Account to be closed. All configurations on the Account must be passed in for this request to succeed.
Possible enum valuescustomerThe Account can be used as a customer.
merchantThe Account can be used as a merchant.
recipientThe Account can be used as a recipient.
Returns
Response attributes
- idstring
Unique identifier for the Account.
- objectstring, 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_
configurationsarray of enums Filter only accounts that have all of the configurations specified. If omitted, returns all accounts regardless of which configurations they have.
Possible enum valuescustomerThe Account can be used as a customer.
merchantThe Account can be used as a merchant.
recipientThe Account can be used as a recipient.
- configurationnullable object
An Account Configuration which allows the Account to take on a key persona across Stripe products.
- contact_
emailnullable string The default contact email address for the Account. Required when configuring the account as a merchant or recipient.
- createdtimestamp
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.
- dashboardnullable enum
A value indicating the Stripe dashboard this Account has access to. This will depend on which configurations are enabled for this account.
Possible enum valuesexpressThe Account has access to the Express hosted dashboard.
fullThe Account has access to the full Stripe hosted dashboard.
noneThe Account does not have access to any Stripe hosted dashboard.
- defaultsnullable object
Default values to be used on Account Configurations.
- display_
namenullable string A descriptive name for the Account. This name will be surfaced in the Stripe Dashboard and on any invoices sent to the Account.
- identitynullable object
Information about the company, individual, and business represented by the Account.
- livemodeboolean
Has the value
trueif the object exists in live mode or the valuefalseif the object exists in test mode. - metadatanullable 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.
- requirementsnullable object
Information about the requirements for the Account, including what information needs to be collected, and by when.
Account with Merchant or Recipient configuration with transfers feature cannot be closed because the account has a cash balance.
Account with Customer configuration cannot be closed because the customer has a cash balance.
Account cannot be closed without specifying the right configurations.
Account cannot be closed due to other pending resources.
Platform has not signed up for Connect and cannot create connected accounts.
Account with Stripe-owned loss liability and dashboard cannot be deleted.
V1 Account ID cannot be used in V2 Account APIs.
V1 Customer ID cannot be used in V2 Account APIs.
The resource wasn’t found.
{ "id": "acct_1Nv0FGQ9RKHgCVdK", "object": "v2.core.account", "applied_configurations": [ "merchant" ], "contact_email": "jenny.rosen@example.com", "created": "2024-11-26T16:33:03.000Z", "dashboard": "none", "display_name": "Jenny Rosen", "metadata": {}}