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

Create a portal configuration 

Billing
Customer Portal Configuration
Create a portal configuration

Creates a configuration that describes the functionality and behavior of a PortalSession

Parameters

  • featuresobjectRequired

    Information about the features available in the portal.

    • features.customer_updateobject

      Information about updating the customer details in the portal.

      • features.customer_update.enabledbooleanRequired

        Whether the feature is enabled.

      • features.customer_update.allowed_updatesarray of enums

        The types of customer updates that are supported. When empty, customers are not updateable.

        Possible enum values
        address

        Allow updating billing addresses.

        email

        Allow updating email addresses.

        name

        Allow updating names.

        phone

        Allow updating phone numbers.

        shipping

        Allow updating shipping addresses.

        tax_id

        Allow updating tax IDs.

    • features.invoice_historyobject

      Information about showing the billing history in the portal.

      • features.invoice_history.enabledbooleanRequired

        Whether the feature is enabled.

    • features.payment_method_updateobject

      Information about updating payment methods in the portal.

      • features.payment_method_update.enabledbooleanRequired

        Whether the feature is enabled.

    • features.subscription_cancelobject

      Information about canceling subscriptions in the portal.

      • features.subscription_cancel.enabledbooleanRequired

        Whether the feature is enabled.

      • features.subscription_cancel.cancellation_reasonobject

        Whether the cancellation reasons will be collected in the portal and which options are exposed to the customer

        • features.subscription_cancel.cancellation_reason.enabledbooleanRequired

          Whether the feature is enabled.

        • features.subscription_cancel.cancellation_reason.optionsarray of enumsRequired

          Which cancellation reasons will be given as options to the customer.

          Possible enum values
          customer_service

          Customer service was less than expected

          low_quality

          Quality was less than expected

          missing_features

          Some features are missing

          other

          Other reason

          switched_service

          I’m switching to a different service

          too_complex

          Ease of use was less than expected

          too_expensive

          It’s too expensive

          unused

          I don’t use the service enough

      • features.subscription_cancel.modeenum

        Whether to cancel subscriptions immediately or at the end of the billing period.

        Possible enum values
        at_period_end

        After canceling, customers can still renew subscriptions until the billing period ends.

        immediately

        Cancel subscriptions immediately.

      • features.subscription_cancel.proration_behaviorenum

        Whether to create prorations when canceling subscriptions. Possible values are none and create_prorations, which is only compatible with mode=immediately. Passing always_invoice will result in an error. No prorations are generated when canceling a subscription at the end of its natural billing period.

        Possible enum values
        always_invoice
        create_prorations
        none

    • features.subscription_updateobject

      Information about updating subscriptions in the portal.

      • features.subscription_update.enabledbooleanRequired

        Whether the feature is enabled.

      • features.subscription_update.default_allowed_updatesarray of enums

        The types of subscription updates that are supported. When empty, subscriptions are not updateable.

        Possible enum values
        price

        Allow switching to a different price.

        promotion_code

        Allow applying promotion codes to subscriptions.

        quantity

        Allow updating subscription quantities.

      • features.subscription_update.productsarray of objects

        The list of up to 10 products that support subscription updates.

        • features.subscription_update.products.pricesarray of stringsRequired

          The list of price IDs for the product that a subscription can be updated to.

        • features.subscription_update.products.productstringRequired

          The product id.

        • features.subscription_update.products.adjustable_quantityobject

          Control whether the quantity of the product can be adjusted.

          • features.subscription_update.products.adjustable_quantity.enabledbooleanRequired

            Set to true if the quantity can be adjusted to any non-negative integer.

          • features.subscription_update.products.adjustable_quantity.maximuminteger

            The maximum quantity that can be set for the product.

          • features.subscription_update.products.adjustable_quantity.minimuminteger

            The minimum quantity that can be set for the product.

      • features.subscription_update.proration_behaviorenum

        Determines how to handle prorations resulting from subscription updates. Valid values are none, create_prorations, and always_invoice.

        Possible enum values
        always_invoice
        create_prorations
        none

      • features.subscription_update.schedule_at_period_endobject

        Setting to control when an update should be scheduled at the end of the period instead of applying immediately.

        • features.subscription_update.schedule_at_period_end.conditionsarray of objects

          List of conditions. When any condition is true, the update will be scheduled at the end of the current period.

          • features.subscription_update.schedule_at_period_end.conditions.typeenumRequired

            The type of condition.

            Possible enum values
            decreasing_item_amount

            Schedule the update when the subscription’s item amount decreases. This can happen when changing to a cheaper price or decreasing the quantity.

            shortening_interval

            Schedule the update when the subscription’s interval is becoming shorter and no other changes to the subscription’s items are made. For example, this applies when changing from a yearly to monthly pricing interval.

  • business_profileobject

    The business information shown to customers in the portal.

    • business_profile.headlinestring

      The messaging shown to customers in the portal.

    • business_profile.privacy_policy_urlstring

      A link to the business’s publicly available privacy policy.

    • business_profile.terms_of_service_urlstring

      A link to the business’s publicly available terms of service.

  • default_return_urlstring

    The default URL to redirect customers to when they click on the portal’s link to return to your website. This can be overriden when creating the session.

  • login_pageobject

    The hosted login page for this configuration. Learn more about the portal login page in our integration docs.

    • login_page.enabledbooleanRequired

      Set to true to generate a shareable URL login_page.url that will take your customers to a hosted login page for the customer portal.

  • metadataobject

    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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • namestring

    The name of the configuration.

Returns

Returns a portal configuration object.

POST /v1/billing_portal/configurations
curl https://api.stripe.com/v1/billing_portal/configurations \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d "features[customer_update][allowed_updates][]"=email \
  -d "features[customer_update][allowed_updates][]"=tax_id \
  -d "features[customer_update][enabled]"=true \
  -d "features[invoice_history][enabled]"=true
Response
{
  "id": "bpc_1MrnZsLkdIwHu7ixNiQL1xPM",
  "object": "billing_portal.configuration",
  "active": true,
  "application": null,
  "business_profile": {
    "headline": null,
    "privacy_policy_url": null,
    "terms_of_service_url": null
  },
  "created": 1680290736,
  "default_return_url": null,
  "features": {
    "customer_update": {
      "allowed_updates": [
        "email",
        "tax_id"
      ],
      "enabled": true
    },
    "invoice_history": {
      "enabled": true
    },
    "payment_method_update": {
      "enabled": false
    },
    "subscription_cancel": {
      "cancellation_reason": {
        "enabled": false,
        "options": [
          "too_expensive",
          "missing_features",
          "switched_service",
          "unused",
          "other"
        ]
      },
      "enabled": false,
      "mode": "at_period_end",
      "proration_behavior": "none"
    },
    "subscription_update": {
      "default_allowed_updates": [],
      "enabled": false,
      "proration_behavior": "none"
    }
  },
  "is_default": false,
  "livemode": false,
  "login_page": {
    "enabled": false,
    "url": null
  },
  "metadata": {},
  "updated": 1680290736
}