Core Resources
Payment Methods
Products
Commerce
Agentic Commerce
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Payment Records
Account Evaluation
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

Retrieve an account v2

GET /v2/core/accounts/:id

Retrieves the details of an Account.

Learn more about calling API v2 endpoints.

Parameters

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

    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.

  • 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 primary contact email address for the Account.

  • contact_phonenullable string

    The default contact phone for the Account.

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

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

400non_connect_platform_accounts_v2_access_blocked

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

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.

curl -G https://api.stripe.com/v2/core/accounts/ \
  -H "Authorization: Bearer sk_test_VePHdqK...NInc7u56JBrQsk_test_VePHdqKTYQjKNInc7u56JBrQ" \
  -H "Stripe-Version: 2026-06-24.dahlia" \
  -d "include[0]=defaults" \
  -d "include[1]=identity" \
  -d "include[2]=configuration.merchant"
Response
{
  "id": "",
  "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

GET /v2/core/accounts

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.

  • 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 to fetch the next page of the list. If there are no more pages, the value is null.

  • previous_page_urlnullable string

    URL to fetch the previous page of the list. If there are no previous pages, the value is null.

Error Codes
400accounts_v2_access_blocked

Accounts v2 is not enabled for your merchant.

400non_connect_platform_accounts_v2_access_blocked

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

429account_rate_limit_exceeded

Account cannot exceed a configured concurrency rate limit on updates.

curl -G https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer sk_test_VePHdqK...NInc7u56JBrQsk_test_VePHdqKTYQjKNInc7u56JBrQ" \
  -H "Stripe-Version: 2026-06-24.dahlia" \
  -d limit=2 \
  -d "applied_configurations[0]=customer"
Response
{
  "data": [
    {
      "id": "",
      "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": "",
      "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

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

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

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

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.

  • 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 primary contact email address for the Account.

  • contact_phonenullable string

    The default contact phone for the Account.

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

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

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.

400non_connect_platform_accounts_v2_access_blocked

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

400pending_transactions_cannot_be_deleted

Account cannot be closed due to other pending resources.

400platform_registration_required

The direct merchant 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.

curl -X POST https://api.stripe.com/v2/core/accounts//close \
  -H "Authorization: Bearer sk_test_VePHdqK...NInc7u56JBrQsk_test_VePHdqKTYQjKNInc7u56JBrQ" \
  -H "Stripe-Version: 2026-06-24.dahlia" \
  --json '{
    "applied_configurations": [
        "merchant"
    ]
  }'
Response
{
  "id": "",
  "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": {}
}