Billing Profile v2

Billing Profile is a representation of how a bill is paid, separating payment behavior from customer identity.

Learn more about calling API v2 endpoints.

Endpoints

POST/v2/billing/profiles

POST/v2/billing/profiles/:id

GET/v2/billing/profiles/:id

GET/v2/billing/profiles

The Profile object

Attributes

idstring
The ID of the billing profile object.

objectstring, value is "v2.billing.profile"
String representing the object’s type. Objects of the same type share the same value of the object field.

createdtimestamp
Timestamp of when the object was created.

customernullable string
The ID of the customer object.

default_payment_methodnullable string
The ID of the payment method object.

display_namenullable string
A customer-facing name for the billing profile. Maximum length of 250 characters.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

lookup_keynullable string
An internal key you can use to search for a particular billing profile. Maximum length of 200 characters.

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.

statusenum
The current status of the billing profile.
Possible enum values
active
The billing profile is active.
inactive
The billing profile is inactive and cannot be used.

The Profile object

{
  "created": "2025-01-01T00:00:00.000Z",
  "customer": "4242",
  "default_payment_method": "4242",
  "display_name": "4242",
  "id": "4242",
  "lookup_key": "4242",
  "metadata": {
    "4242": "4242"
  },
  "object": "4242",
  "status": "active",
  "livemode": true
}

Create a Billing Profile v2

Create a BillingProfile object.

Learn more about calling API v2 endpoints.

Parameters

customerstringRequired
The ID of the customer object.

default_payment_methodstring
The ID of the payment method object.

display_namestring
A customer-facing name for the billing profile. Maximum length of 250 characters.

lookup_keystring
An internal key you can use to search for a particular billing profile. It must be unique among billing profiles for a given customer. Maximum length of 200 characters.

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
The ID of the billing profile object.

objectstring, value is "v2.billing.profile"
String representing the object’s type. Objects of the same type share the same value of the object field.

createdtimestamp
Timestamp of when the object was created.

customernullable string
The ID of the customer object.

default_payment_methodnullable string
The ID of the payment method object.

display_namenullable string
A customer-facing name for the billing profile. Maximum length of 250 characters.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

lookup_keynullable string
An internal key you can use to search for a particular billing profile. Maximum length of 200 characters.

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.

statusenum
The current status of the billing profile.
Possible enum values
active
The billing profile is active.
inactive
The billing profile is inactive and cannot be used.

Error Codes

400customer_not_found_for_billing_profile

Returned when the customer for the provided ID cannot be found.

400invalid_customer_for_billing_profile

Returned when associating a billing profile with a deleted customer.

400lookup_key_already_exists_for_billing_profile

Returned when the Lookup Key already exists for another billing profile for this customer.

400payment_method_customer_mismatch_for_billing_profile

Returned when the payment method belongs to a different customer.

400payment_method_not_found_for_billing_profile

Returned when the payment method for the provided ID cannot be found.

POST /v2/billing/profiles

Server-side language

curl -X POST https://api.stripe.com/v2/billing/profiles \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "customer": "cus_123",
    "default_payment_method": "pm_123",
    "display_name": "Display Name",
    "lookup_key": "billing_profile_cus_123",
    "metadata": {
        "test": "data"
    }
  }'

Response

{
  "created": "2025-01-01T00:00:00.000Z",
  "customer": "cus_123",
  "default_payment_method": "pm_123",
  "display_name": "Display Name",
  "id": "bilp_123",
  "lookup_key": "billing_profile_cus_123",
  "metadata": {
    "test": "data"
  },
  "object": "v2.billing.profile",
  "status": "active",
  "livemode": true
}

Update a Billing Profile v2

Update a BillingProfile object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the billing profile to update.

default_payment_methodstring
The ID of the payment method object.

display_namestring
A customer-facing name for the billing profile. Maximum length of 250 characters. To remove the display_name from the object, set it to null in the request.

lookup_keystring
An internal key you can use to search for a particular billing profile. It must be unique among billing profiles for a given customer. Maximum length of 200 characters. To remove the lookup_key from the object, set it to null in the request.

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
The ID of the billing profile object.

objectstring, value is "v2.billing.profile"
String representing the object’s type. Objects of the same type share the same value of the object field.

createdtimestamp
Timestamp of when the object was created.

customernullable string
The ID of the customer object.

default_payment_methodnullable string
The ID of the payment method object.

display_namenullable string
A customer-facing name for the billing profile. Maximum length of 250 characters.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

lookup_keynullable string
An internal key you can use to search for a particular billing profile. Maximum length of 200 characters.

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.

statusenum
The current status of the billing profile.
Possible enum values
active
The billing profile is active.
inactive
The billing profile is inactive and cannot be used.

Error Codes

400lookup_key_already_exists_for_billing_profile

Returned when the Lookup Key already exists for another billing profile for this customer.

400payment_method_customer_mismatch_for_billing_profile

Returned when the payment method belongs to a different customer.

400payment_method_not_found_for_billing_profile

Returned when the payment method for the provided ID cannot be found.

404billing_profile_not_found

Returned when the Billing Profile for the provided ID cannot be found.

POST /v2/billing/profiles/:id

Server-side language

curl -X POST https://api.stripe.com/v2/billing/profiles/bilp_123 \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "lookup_key": "business_profile_cus_123",
    "display_name": "Business Profile"
  }'

Response

{
  "created": "2025-01-01T00:00:00.000Z",
  "customer": "cus_123",
  "default_payment_method": "pm_123",
  "display_name": "Business Profile",
  "id": "bilp_123",
  "lookup_key": "business_profile_cus_123",
  "metadata": {
    "test": "data"
  },
  "object": "v2.billing.profile",
  "status": "active",
  "livemode": true
}

Retrieve a Billing Profile v2

Retrieve a BillingProfile object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the billing profile to Retrieve.

Returns

Response attributes

idstring
The ID of the billing profile object.

objectstring, value is "v2.billing.profile"
String representing the object’s type. Objects of the same type share the same value of the object field.

createdtimestamp
Timestamp of when the object was created.

customernullable string
The ID of the customer object.

default_payment_methodnullable string
The ID of the payment method object.

display_namenullable string
A customer-facing name for the billing profile. Maximum length of 250 characters.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

lookup_keynullable string
An internal key you can use to search for a particular billing profile. Maximum length of 200 characters.

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.

statusenum
The current status of the billing profile.
Possible enum values
active
The billing profile is active.
inactive
The billing profile is inactive and cannot be used.

Error Codes

404billing_profile_not_found

Returned when the Billing Profile for the provided ID cannot be found.

GET /v2/billing/profiles/:id

Server-side language

curl https://api.stripe.com/v2/billing/profiles/bilp_123 \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview"

Response

{
  "created": "2025-01-01T00:00:00.000Z",
  "customer": "cus_123",
  "default_payment_method": "pm_123",
  "display_name": "Display Name",
  "id": "bilp_123",
  "lookup_key": "billing_profile_cus_123",
  "metadata": {
    "test": "data"
  },
  "object": "v2.billing.profile",
  "status": "active",
  "livemode": true
}

Billing Profile v2

The Profile object

Attributes

idstring

objectstring, value is "v2.billing.profile"

createdtimestamp

customernullable string

default_payment_methodnullable string

display_namenullable string

livemodeboolean

lookup_keynullable string

metadatanullable map

statusenum

Create a Billing Profile v2

Parameters

customerstringRequired

default_payment_methodstring

display_namestring

lookup_keystring

metadatamap

Returns

Response attributes

idstring

objectstring, value is "v2.billing.profile"

createdtimestamp

customernullable string

default_payment_methodnullable string

display_namenullable string

livemodeboolean

lookup_keynullable string

metadatanullable map

statusenum

Update a Billing Profile v2

Parameters

idstringRequired

default_payment_methodstring

display_namestring

lookup_keystring

metadatamap

Returns

Response attributes

idstring

objectstring, value is "v2.billing.profile"

createdtimestamp

customernullable string

default_payment_methodnullable string

display_namenullable string

livemodeboolean

lookup_keynullable string

metadatanullable map

statusenum

Retrieve a Billing Profile v2

Parameters

idstringRequired

Returns

Response attributes

idstring

objectstring, value is "v2.billing.profile"

createdtimestamp

customernullable string

default_payment_methodnullable string

display_namenullable string

livemodeboolean

lookup_keynullable string

metadatanullable map

statusenum