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

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

Meters 

Meters specify how to aggregate meter events over a billing period. Meter events represent the actions that customers take in your system. Meters attach to prices and form the basis of the bill.

Related guide: Usage based billing

Endpoints

Meter Events 

Meter events represent actions that customers take in your system. You can use meter events to bill a customer based on their usage. Meter events are associated with billing meters, which define both the contents of the event’s payload and how to aggregate those events.

Endpoints