Skip to content
Create account or Sign in
The Stripe Docs logo
/
Create accountSign in

Use Accounts as customers

Accept payments from Accounts configured as customers.

With Accounts v2, you can use an Account object similarly to a Customer object by assigning it the customer configuration.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-11-17.preview" \
  --json '{
    "contact_email": "jenny.rosen@example.com",
    "display_name": "Jenny Rosen",
    "identity": {
        "country": "us",
        "individual": {
            "given_name": "Jenny Rosen"
        }
    },
    "configuration": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            }
        }
    },
    "include": [
        "configuration.customer",
        "identity"
    ]
  }'

When you use Accounts v2, your Stripe-hosted integrations, such as Checkout, create Accounts with the customer configuration. If your code references Customers, we recommend that you update it to reference customer-configured Accounts instead.

Purposev1 referencev2 reference
Customer referencecustomercustomer_account
Customer identificationcus_xxxxxacct_xxxxx
Set billing addressaddress
Set shipping addressshippingconfiguration.customer.shipping

Provide an Account as the customer

API requests such as Subscriptions and SetupIntents require you to specify a customer. These requests accept either the customer or customer_account parameter. The following sample shows a subscription that specifies the customer by passing an Accounts v2 object as the customer_account.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-04-30.preview" \
  -d customer_account=acct_xxxxx \
  -d "items[0][price]"=price_CBb6IXqvTLXp3f \
  -d "items[0][quantity]"=5

Reference Accounts in Customers v1 integrations

A request that specifies customer_account returns both customer and customer_account properties, with correspondingly formatted values. This maintains compatibility with existing Billing and Payments integrations.

Example response
{
  "id": "sub_1Mow234",
  .
  .
  .
  "customer": "cus_xxxxx",
  "customer_account": "acct_xxxxx"
}

You can also retrieve or update customer-configured Accounts using the /v1/customers endpoint.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v1/customers/acct_1234 \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Accounts v2 webhooks

Webhooks for Accounts v2 send thin events.

Actionv1 eventv2 event
Customer createdcustomer.createdAccounts v2 sends separate events indicating the account creation and the customer configuration:
  • v2.core.account.created
  • v2.core.account[configuration.customer].updated
Billing address updatedcustomer.updatedv2.core.account[identity].updated
Subscription actionscustomer.subscription.[action]None; use the v1 event
Customer deletedcustomer.deletedv2.core.account.closed

Customer invoice properties

Data valueCustomers v1 propertyAccounts v2 property
Customer stored creditinvoice_credit_balanceNone; see Reference an Accounts v2 ID in a /v1/customers path
Customer invoice prefixinvoice_prefixconfiguration.customer.billing.invoice.prefix
Custom settingsinvoice_settings.custom_fieldsconfiguration.customer.billing.invoice.custom_fields
Default payment methodinvoice_settings.default_payment_methodconfiguration.customer.billing.default_payment_method
Invoice footerinvoice_settings.footerconfiguration.customer.billing.invoice.footer
Invoice rendering optionsinvoice_settings.rendering_optionsconfiguration.customer.billing.invoice.rendering.template

Reference an Accounts v2 ID using the v1 Customers endpoint

Accounts v2 doesn’t have endpoints for every customer function. To perform the following actions for an Accounts v2 object, use the v1/customers endpoint and pass the Account ID (acct_xxxxx) as the path parameter.

Use case v1 endpoint with account ID
Manage cash balances
  • v1/customers/acct_xxxxx/cash_balances
  • v1/customers/acct_xxxxx/cash_balances/:id
Manage cash balance transactions
  • GET v1/customers/acct_xxxxx/cash_balance_transactions
  • GET v1/customers/acct_xxxxx/cash_balance_transactions/:id
  • POST v1/test_helpers/customers/acct_xxxxx/fund_cash_balance
  • POST v1/customers/acct_xxxxx/funding_instructions
  • GET v1/customers/acct_xxxxx/funding_instructions

Manage invoice credit balance

For Accounts v2, the ending_balance of the account’s most recently finalized invoice is the equivalent of the invoice_credit_balance for v1 customers.

  • POST v1/customers/acct_xxxxx/balance_transactions
  • POST v1/customers/acct_xxxxx/balance_transactions/:id
  • GET v1/customers/acct_xxxxx/balance_transactions/:id
  • GET v1/customers/acct_xxxxx/balance_transactions
On this page