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

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
curl -X POST https://api.stripe.com/v2/billing/profiles/bilp_61SahwKGATwuyXMY516SBbsMNLSQJnWcho4VDz0fYLKi \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "lookup_key": "business_profile_cus_SM22QFjZh7DtOo",
    "display_name": "Business Profile"
  }'
Response
{
  "created": "2025-01-01T00:00:00.000Z",
  "customer": "cus_SM22QFjZh7DtOo",
  "default_payment_method": "pm_1RRJyOCZPkOPzJLWkaBPKr4J ",
  "display_name": "Business Profile",
  "id": "bilp_61SahwKGATwuyXMY516SBbsMNLSQJnWcho4VDz0fYLKi",
  "lookup_key": "business_profile_cus_SM22QFjZh7DtOo",
  "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
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_SM22QFjZh7DtOo",
  "default_payment_method": "pm_1RRJyOCZPkOPzJLWkaBPKr4J ",
  "display_name": "Display Name",
  "id": "bilp_61SahwKGATwuyXMY516SBbsMNLSQJnWcho4VDz0fYLKi",
  "lookup_key": "billing_profile_cus_SM22QFjZh7DtOo",
  "metadata": {
    "test": "data"
  },
  "object": "v2.billing.profile",
  "status": "active",
  "livemode": true
}

List all Billing Profile objects v2

List Billing Profiles.

Learn more about calling API v2 endpoints.

Parameters

  • lookup_keysarray of stringsRequired

    Filter billing profiles by lookup keys. Mutually exclusive with customer and default_payment_method. You can specify up to 10 lookup_keys.

  • customerstring

    Filter billing profiles by a customer. Mutually exclusive with lookup_keys and default_payment_method.

  • default_payment_methodstring

    Filter billing profiles by a default payment method. Mutually exclusive with customer and lookup_keys.

  • limitinteger

    Optionally set the maximum number of results per page. Defaults to 10.

  • pagestring

    Opaque page token.

  • statusenum

    Filter billing profiles by status. Can be combined with all other filters. If not provided, all billing profiles will be returned.

    Possible enum values
    active

    The billing profile is active.

    inactive

    The billing profile is inactive and cannot be used.

Returns

Response attributes

  • dataarray of objects

    The retrieved Profile objects.

  • next_page_urlnullable string

    The URL of the next page of results, if there is one.

  • previous_page_urlnullable string

    The URL of the previous page of results, if there is one.

Error Codes
400customer_not_found_for_billing_profile

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

400payment_method_not_found_for_billing_profile

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

GET /v2/billing/profiles
cURL
curl -G https://api.stripe.com/v2/billing/profiles \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview" \
  -d default_payment_method=pm_123
Response
{
  "data": [
    {
      "created": "2025-01-01T00:00:00.000Z",
      "customer": "cus_SM22QFjZh7DtOo",
      "default_payment_method": "pm_1RRJyOCZPkOPzJLWkaBPKr4J ",
      "display_name": "Display Name",
      "id": "bilp_61SahwKGATwuyXMY516SBbsMNLSQJnWcho4VDz0fYLKi",
      "lookup_key": "billing_profile_cus_SM22QFjZh7DtOo",
      "metadata": {
        "test": "data"
      },
      "object": "v2.billing.profile",
      "status": "active",
      "livemode": true
    }
  ]
}

Billing Intents v2

A Billing Intent represents a request to create, modify or cancel subscriptions.

Learn more about calling API v2 endpoints.
Endpoints

Alerts 

A billing alert is a resource that notifies you when a certain usage threshold on a meter is crossed. For example, you might create a billing alert to notify you when a certain user made 100 API requests.

Endpoints