Create an Account v2

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.

Learn more about calling API v2 endpoints.

Parameters

  • account_tokenstring

    The account token generated by the account token api.

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

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

    configuration.storer

    Include parameter to expose configuration.storer 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.

  • 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

    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.

    storer

    The Account can be used as a storer.

  • closednullable boolean

    Indicates whether the account has been closed.

  • configurationnullable 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_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 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.

  • defaultsnullable object

    Default values for settings shared across 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.

  • future_requirementsnullable 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.

  • identitynullable object

    Information about the company, individual, and business represented by the Account.

  • livemodeboolean

    Has the value true if the object exists in live mode or the value false if 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 active requirements for the Account, including what information needs to be collected, and by when.

Error Codes
400account_capability_not_supported

Requested capability is not available.

400account_controller_express_dash_without_application_losses_or_fees

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

400account_controller_stripe_pricing_platform_liable

If losses_collector is application, fees_collector must also be application.

400account_controller_ua_unsupported_configuration

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

400account_controller_unsupported_configuration

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

400account_controller_unsupported_configuration_private_preview

Responsibility combinations is not supported in private preview.

400account_country_unsupported_currency

Currency is not allowed for the account’s country.

400account_create_activation_required

Platform must be activated to create connected accounts.

400account_creation_invalid

Account creation is invalid.

400account_creation_liability_unacknowledged

Account creation error - liability unacknowledged.

400account_creation_requirement_collection_and_liability_unacknowledged

Account creation error - requirement collection and liability unacknowledged.

400account_creation_requirement_collection_unacknowledged

Account creation error - requirement collection unacknowledged.

400account_terms_of_service_not_accepted

Terms of service must be accepted before adding merchant configuration.

400account_token_required

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

400accounts_v2_access_blocked

Accounts v2 is not enabled for your platform.

400address_characters_invalid

Invalid characters are provided for address fields.

400address_country_identity_country_mismatch

Address country doesn’t match identity country.

400address_postal_code_invalid

Address postal code is invalid.

400address_state_invalid

Address state is invalid.

400address_town_invalid

Address town is invalid.

400bgn_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.

400can_create_platform_owned_onboarding_accounts_required

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

400cannot_create_connected_account

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

400cannot_create_new_account_rejected

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

400capability_cannot_be_unrequested_due_to_other_capability_requirement

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

400capability_not_available_for_dashboard_type

Feature cannot be requested for the dashboard type.

400capability_not_available_for_entity_type_in_country

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

400capability_not_available_in_country

Requested capability is not available in your country.

400capability_not_available_in_platform_country

Feature cannot be requested given the platform’s country.

400capability_not_available_without_other_capability

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

400capability_not_available_without_other_capability_in_country

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

400configuration_creation_invalid

Cannot create an account with an invalid configuration.

400connect_identity_not_verified

Platform is not verified and cannot create connected accounts.

400connect_profile_not_submitted

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

400cross_border_connected_account_creation_not_allowed

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

400custom_account_beta

Custom accounts cannot be created in certain countries.

400date_of_birth_age_restriction

Representative date of birth does not meet the age limit.

400date_of_birth_invalid

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

400default_currency_immutable

Cannot change defaults.currency post account activation.

400default_payment_method_invalid

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

400default_payment_method_invalid_type

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

400directorship_declaration_not_allowed_during_account_creation

Directorship declaration is not allowed during account creation.

400document_invalid

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

400document_purpose_invalid

Provided file tokens for documents are of the wrong purpose.

400email_domain_invalid_for_recipient

Email contains unsupported domain.

400email_invalid

Incorrect email is provided.

400entity_type_not_supported_in_country

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

400high_risk_activities_none_cant_be_combined_with_other_options

NONE is combined with another value in the HighRiskActivities list.

400id_number_invalid

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

400identity_country_required

The identity.country value is required but not provided.

400incorrect_id_number_for_country

Incorrect ID number is provided for a country.

400incorrect_token_wrong_type

The incorrect token type is provided .

400invalid_id_number_for_structure

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

400invalid_id_number_registrar

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

400invalid_konbini_payments_support_hours

Konbini Payments Support Hours is Invalid.

400invalid_konbini_payments_support_phone_number

Konbini Payments Support Phone Number is Invalid.

400invoice_rendering_template_invalid

Invoice rendering template does not exist or is otherwise invalid.

400ip_address_invalid

Invalid IP address is provided.

400mcc_invalid

MCC is invalid for configuration.merchant.mcc.

400non_jp_kana_kanji_address

Kana Kanji script addresses must have JP country.

400ownership_declaration_not_allowed_during_account_creation

Ownership declaration is not allowed during account creation.

400param_alongside_account_token

Parameter cannot be passed alongside account_token.

400person_percent_ownership_invalid

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

400phone_invalid

Phone number is invalid.

400platform_registration_required

Platform has not signed up for Connect and cannot create connected accounts.

400postal_code_required_for_jp_address

Postal code is required for Japanese addresses.

400purpose_of_funds_description_must_be_empty_for_non_other_purpose_of_funds

PurposeOfFundsDescription is not empty while PurposeOfFunds is not OTHER.

400script_characters_invalid

Provided script characters are invalid for the script.

400shipping_address_required

Shipping address is required within the shipping hash.

400shipping_name_required

Shipping name is required within the shipping hash.

400statement_descriptor_invalid

Statement descriptor is invalid.

400structure_incompatible_for_entity_type_country

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

400test_clock_disallowed_on_live_mode

Cannot set a test clock on a livemode customer.

400test_clock_invalid

Test clock does not exist or is otherwise invalid.

400test_clocks_advance_in_progress

Cannot modify a test clock that is currently advancing.

400test_clocks_customer_limit_reached

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

400token_already_used

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

400token_expired

Token has expired.

400tos_acceptance_on_behalf_not_allowed

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

400unsupported_field_for_configs

Cannot set responsibilities on the current configurations.

400unsupported_identity_field_for_configs

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

400unsupported_postal_code

Address is in an unsupported postal code.

400unsupported_state

Address is in an unsupported state.

400url_invalid

URL is invalid.

400v1_token_invalid_in_v2

A v1 token ID is passed in v2 APIs.

403invalid_account_token

Invalid account token.

409idempotency_error

An idempotent retry occurred with different request parameters.

429account_rate_limit_exceeded

Account cannot exceed a configured concurrency rate limit on updates.

POST /v2/core/accounts
curl -X POST https://api.stripe.com/v2/core/accounts \
-H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
-H "Stripe-Version: 2025-12-15.preview" \
--json '{
"contact_email": "furever@example.com",
"display_name": "Furever",
"identity": {
"country": "us",
"entity_type": "company",
"business_details": {
"registered_name": "Furever"
}
},
"configuration": {
"customer": {
"capabilities": {
"automatic_indirect_tax": {
"requested": true
}
}
},
"merchant": {
"capabilities": {
"card_payments": {
"requested": true
}
}
}
},
"defaults": {
"responsibilities": {
"fees_collector": "stripe",
"losses_collector": "stripe"
}
},
"dashboard": "full",
"include": [
"configuration.merchant",
"configuration.customer",
"identity",
"defaults"
]
}'
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"
},
"country": "US",
"entity_type": "company"
},
"livemode": false,
"defaults": {
"currency": "usd",
"responsibilities": {
"fees_collector": "stripe",
"losses_collector": "stripe",
"requirements_collector": "stripe"
}
},
"display_name": "Furever"
}

Update an Account v2

Updates the details of an Account.

Learn more about calling API v2 endpoints.

Parameters

  • idstringRequired

    The ID of the Account to update.

  • account_tokenstring

    The account token generated by the account token api.

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

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

    configuration.storer

    Include parameter to expose configuration.storer 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.

  • 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

    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.

    storer

    The Account can be used as a storer.

  • closednullable boolean

    Indicates whether the account has been closed.

  • configurationnullable 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_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 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.

  • defaultsnullable object

    Default values for settings shared across 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.

  • future_requirementsnullable 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.

  • identitynullable object

    Information about the company, individual, and business represented by the Account.

  • livemodeboolean

    Has the value true if the object exists in live mode or the value false if 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 active requirements for the Account, including what information needs to be collected, and by when.

Error Codes
400account_capability_not_supported

Requested capability is not available.

400account_controller_express_dash_without_application_losses_or_fees

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

400account_controller_stripe_pricing_platform_liable

If losses_collector is application, fees_collector must also be application.

400account_controller_unsupported_configuration

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

400account_controller_unsupported_configuration_private_preview

Responsibility combinations is not supported in private preview.

400account_country_unsupported_currency

Currency is not allowed for the account’s country.

400account_not_yet_compatible_with_v2

Account is not yet compatible with V2 APIs.

400account_terms_of_service_not_accepted

Terms of service must be accepted before adding merchant configuration.

400account_token_required

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

400accounts_v2_access_blocked

Accounts v2 is not enabled for your platform.

400address_characters_invalid

Invalid characters are provided for address fields.

400address_country_identity_country_mismatch

Address country doesn’t match identity country.

400address_postal_code_invalid

Address postal code is invalid.

400address_state_invalid

Address state is invalid.

400address_town_invalid

Address town is invalid.

400attach_payment_method_to_customer

Default payment method is added to the customer config before attaching it to the account using /v1/payment_methods.

400bgn_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.

400can_create_platform_owned_onboarding_accounts_required

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

400cannot_use_validate_location_on_customer_create

Cannot set automatic_indirect_tax.validate_location when initially creating a customer configuration.

400capability_cannot_be_unrequested_due_to_other_capability_requirement

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

400capability_not_available_for_dashboard_type

Feature cannot be requested for the dashboard type.

400capability_not_available_for_entity_type_in_country

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

400capability_not_available_in_country

Requested capability is not available in your country.

400capability_not_available_in_platform_country

Feature cannot be requested given the platform’s country.

400capability_not_available_without_other_capability

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

400capability_not_available_without_other_capability_in_country

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

400configuration_cannot_be_deactivated

Configuration cannot be deactivated.

400configuration_cannot_be_deactivated_due_to_other_capability_requirement

Configuration cannot be deactivated due to a dependency with another capability.

400configuration_cannot_be_deactivated_due_to_other_configuration

Cannot deactivate a configuration due to another configuration depending on it.

400configuration_cannot_be_updated_while_deactivated

Configuration cannot be updated while deactivated.

400configuration_creation_invalid

Cannot create an account with an invalid configuration.

400cross_border_connected_account_creation_not_allowed

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

400custom_account_beta

Custom accounts cannot be created in certain countries.

400customer_invalid_tax_location

Invalid customer tax location.

400date_of_birth_age_restriction

Representative date of birth does not meet the age limit.

400date_of_birth_invalid

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

400default_currency_immutable

Cannot change defaults.currency post account activation.

400default_outbound_destination_invalid

Outbound Destination ID is invalid.

400default_payment_method_invalid

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

400document_invalid

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

400document_purpose_invalid

Provided file tokens for documents are of the wrong purpose.

400duplicate_person_not_allowed

Duplicate person is added to an account.

400email_domain_invalid_for_recipient

Email contains unsupported domain.

400email_invalid

Incorrect email is provided.

400entity_type_not_supported_in_country

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

400high_risk_activities_none_cant_be_combined_with_other_options

NONE is combined with another value in the HighRiskActivities list.

400id_number_invalid

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

400identity_country_required

The identity.country value is required but not provided.

400immutable_identity_param

Identity param has been made immutable due to the state of the account.

400incorrect_id_number_for_country

Incorrect ID number is provided for a country.

400incorrect_token_wrong_type

The incorrect token type is provided .

400invalid_id_number_for_structure

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

400invalid_id_number_registrar

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

400invalid_konbini_payments_support_hours

Konbini Payments Support Hours is Invalid.

400invalid_konbini_payments_support_phone_number

Konbini Payments Support Phone Number is Invalid.

400ip_address_invalid

Invalid IP address is provided.

400mcc_invalid

MCC is invalid for configuration.merchant.mcc.

400non_jp_kana_kanji_address

Kana Kanji script addresses must have JP country.

400param_alongside_account_token

Parameter cannot be passed alongside account_token.

400person_percent_ownership_invalid

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

400phone_invalid

Phone number is invalid.

400postal_code_required_for_jp_address

Postal code is required for Japanese addresses.

400purpose_of_funds_description_must_be_empty_for_non_other_purpose_of_funds

PurposeOfFundsDescription is not empty while PurposeOfFunds is not OTHER.

400script_characters_invalid

Provided script characters are invalid for the script.

400shipping_address_required

Shipping address is required within the shipping hash.

400shipping_name_required

Shipping name is required within the shipping hash.

400statement_descriptor_invalid

Statement descriptor is invalid.

400structure_incompatible_for_entity_type_country

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

400test_clock_disallowed_on_live_mode

Cannot set a test clock on a livemode customer.

400test_clock_invalid

Test clock does not exist or is otherwise invalid.

400token_already_used

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

400token_expired

Token has expired.

400tos_acceptance_on_behalf_not_allowed

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

400total_person_ownership_exceeded

Total ownership percentages of all Persons on the account exceeds 100%.

400unsupported_field_for_configs

Cannot set responsibilities on the current configurations.

400unsupported_identity_field_for_configs

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

400unsupported_postal_code

Address is in an unsupported postal code.

400unsupported_state

Address is in an unsupported state.

400url_invalid

URL is invalid.

400v1_account_instead_of_v2_account

V1 Account ID cannot be used in V2 Account APIs.

400v1_customer_instead_of_v2_account

V1 Customer ID cannot be used in V2 Account APIs.

400v1_token_invalid_in_v2

A v1 token ID is passed in v2 APIs.

403invalid_account_token

Invalid account token.

404not_found

The resource wasn’t found.

409idempotency_error

An idempotent retry occurred with different request parameters.

429account_rate_limit_exceeded

Account cannot exceed a configured concurrency rate limit on updates.

POST /v2/core/accounts/:id
curl -X POST https://api.stripe.com/v2/core/accounts/acct_1Nv0FGQ9RKHgCVdK \
-H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
-H "Stripe-Version: 2025-12-15.preview" \
--json '{
"defaults": {
"profile": {
"business_url": "http://accessible.stripe.com",
"doing_business_as": "FurEver",
"product_description": "Saas pet grooming platform at furever.dev using Connect embedded components"
}
},
"identity": {
"business_details": {
"structure": "sole_proprietorship",
"id_numbers": [
{
"type": "us_ein",
"value": "000000000"
}
]
}
},
"include": [
"defaults",
"identity"
]
}'
Response
{
"id": "acct_1Nv0FGQ9RKHgCVdK",
"object": "v2.core.account",
"applied_configurations": [
"customer",
"merchant"
],
"contact_email": "furever@example.com",
"created": "2024-11-26T16:33:03.000Z",
"dashboard": "full",
"identity": {
"business_details": {
"id_numbers": [
{
"type": "us_ein"
}
],
"registered_name": "Furever",
"structure": "sole_proprietorship"
},
"country": "us",
"entity_type": "company"
},
"defaults": {
"currency": "usd",
"locales": [],
"profile": {
"business_url": "http://accessible.stripe.com",
"doing_business_as": "FurEver",
"product_description": "Saas pet grooming platform at furever.dev using Connect embedded components"
},
"responsibilities": {
"fees_collector": "stripe",
"losses_collector": "stripe",
"requirements_collector": "stripe"
}
},
"display_name": "Furever",
"livemode": true,
"metadata": {}
}

Retrieve an Account v2

Retrieves the details of an Account.

Learn more about calling API v2 endpoints.

Parameters

  • idstringRequired

    The ID of the Account to retrieve.

  • includearray 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.

    configuration.storer

    Include parameter to expose configuration.storer 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.

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

    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.

    storer

    The Account can be used as a storer.

  • closednullable boolean

    Indicates whether the account has been closed.

  • configurationnullable 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_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 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.

  • defaultsnullable object

    Default values for settings shared across 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.

  • future_requirementsnullable 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.

  • identitynullable object

    Information about the company, individual, and business represented by the Account.

  • livemodeboolean

    Has the value true if the object exists in live mode or the value false if 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 active requirements for the Account, including what information needs to be collected, and by when.

Error Codes
400account_not_yet_compatible_with_v2

Account is not yet compatible with V2 APIs.

400accounts_v2_access_blocked

Accounts v2 is not enabled for your platform.

400v1_account_instead_of_v2_account

V1 Account ID cannot be used in V2 Account APIs.

400v1_customer_instead_of_v2_account

V1 Customer ID cannot be used in V2 Account APIs.

404not_found

The resource wasn’t found.

429account_rate_limit_exceeded

Account cannot exceed a configured concurrency rate limit on updates.

GET /v2/core/accounts/:id
curl -G https://api.stripe.com/v2/core/accounts/acct_1Nv0FGQ9RKHgCVdK \
-H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
-H "Stripe-Version: 2025-12-15.preview" \
-d "include[0]"=defaults \
-d "include[1]"=identity \
-d "include[2]"="configuration.merchant"
Response
{
"id": "acct_1Nv0FGQ9RKHgCVdK",
"object": "v2.core.account",
"applied_configurations": [
"customer",
"merchant"
],
"configuration": {
"merchant": {
"applied": "2024-11-26T16:33:03.000Z",
"card_payments": {
"decline_on": {
"avs_failure": false,
"cvc_failure": false
}
},
"capabilities": {
"card_payments": {
"status": "restricted",
"status_details": [
{
"code": "requirements_past_due",
"resolution": "provide_info"
}
]
}
},
"statement_descriptor": {
"descriptor": "accessible.stripe.com"
}
}
},
"contact_email": "furever@example.com",
"created": "2024-11-26T16:33:03.000Z",
"dashboard": "full",
"identity": {
"business_details": {
"address": {
"country": "us"
},
"id_numbers": [
{
"type": "us_ein"
}
],
"structure": "sole_proprietorship"
},
"country": "us",
"entity_type": "company"
},
"defaults": {
"currency": "usd",
"locales": [],
"profile": {
"business_url": "http://accessible.stripe.com",
"doing_business_as": "FurEver",
"product_description": "Saas pet grooming platform at furever.dev using Connect embedded components"
},
"responsibilities": {
"fees_collector": "stripe",
"losses_collector": "stripe",
"requirements_collector": "stripe"
}
},
"display_name": "Furever",
"livemode": true,
"metadata": {}
}

List Accounts v2

Returns a list of Accounts.

Learn more about calling API v2 endpoints.

Parameters

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

    storer

    The Account can be used as a storer.

  • closedboolean

    Filter by whether the account is closed. If omitted, returns only Accounts that are not closed.

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

Error Codes
400accounts_v2_access_blocked

Accounts v2 is not enabled for your platform.

429account_rate_limit_exceeded

Account cannot exceed a configured concurrency rate limit on updates.

GET /v2/core/accounts
curl -G https://api.stripe.com/v2/core/accounts \
-H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
-H "Stripe-Version: 2025-12-15.preview" \
-d limit=2 \
-d "applied_configurations[0]"=customer
Response
{
"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",
"livemode": true,
"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",
"livemode": true,
"metadata": {
"my_key": "my_value"
}
}
],
"next_page_url": "/v2/core/accounts?page=page_5dr8SFDbv7rZ2aj4ZSGuf4J1Dv58yE0YM4BhBqb2tg94CD5PDoUA7RD2AE7VBEH5C0E0qGJi1wMFPf9MEBbh6M125&limit=2&applied_configurations=customer"
}

Close an Account v2

Removes access to the Account and its associated resources. Closed Accounts can no longer be operated on, but limited information can still be retrieved through the API in order to be able to track their history.

Learn more about calling API v2 endpoints.

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

    storer

    The Account can be used as a storer.

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

    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.

    storer

    The Account can be used as a storer.

  • closednullable boolean

    Indicates whether the account has been closed.

  • configurationnullable 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_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 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.

  • defaultsnullable object

    Default values for settings shared across 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.

  • future_requirementsnullable 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.

  • identitynullable object

    Information about the company, individual, and business represented by the Account.

  • livemodeboolean

    Has the value true if the object exists in live mode or the value false if 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 active requirements for the Account, including what information needs to be collected, and by when.

Error Codes
400account_not_yet_compatible_with_v2

Account is not yet compatible with V2 APIs.

400accounts_v2_access_blocked

Accounts v2 is not enabled for your platform.

400cannot_delete_account_with_balance

Account with Merchant or Recipient configuration with transfers feature cannot be closed because the account has a cash balance.

400cannot_delete_customer_with_available_cash_balance

Account with Customer configuration cannot be closed because the customer has a cash balance.

400configs_must_match_to_close

Account cannot be closed without specifying the right configurations.

400pending_transactions_cannot_be_deleted

Account cannot be closed due to other pending resources.

400platform_registration_required

Platform has not signed up for Connect and cannot create connected accounts.

400stripe_loss_liable_cannot_be_deleted

Account with Stripe-owned loss liability and dashboard cannot be deleted.

400v1_account_instead_of_v2_account

V1 Account ID cannot be used in V2 Account APIs.

400v1_customer_instead_of_v2_account

V1 Customer ID cannot be used in V2 Account APIs.

404not_found

The resource wasn’t found.

429account_rate_limit_exceeded

Account cannot exceed a configured concurrency rate limit on updates.

POST /v2/core/accounts/:id/close
curl -X POST https://api.stripe.com/v2/core/accounts/acct_1Nv0FGQ9RKHgCVdK/close \
-H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
-H "Stripe-Version: 2025-12-15.preview" \
--json '{
"applied_configurations": [
"merchant"
]
}'
Response
{
"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",
"livemode": true,
"metadata": {}
}