Create a portal configuration
POST/v1/billing_portal/configurations
Creates a configuration that describes the functionality and behavior of a PortalSession
Body parameters
featuresobjectRequiredInformation about the features available in the portal.
Show 5 child parameters
customer_updateobjectShow 2 child parameters
enabledbooleanRequiredallowed_updatesarray of strings
invoice_historyobjectShow 1 child parameter
enabledbooleanRequired
payment_method_updateobjectShow 2 child parameters
enabledbooleanRequiredpayment_method_configurationstring
subscription_cancelobjectShow 4 child parameters
enabledbooleanRequiredcancellation_reasonobjectChild parameters are listed in the OpenAPI document.
modestringPossible valuesat_period_endimmediately
proration_behaviorstringPossible valuesalways_invoicecreate_prorationsnone
subscription_updateobjectShow 7 child parameters
enabledbooleanRequiredbilling_cycle_anchorstringPossible valuesnowunchanged
default_allowed_updatesarray of stringsproductsarray of objectsChild parameters are listed in the OpenAPI document.
proration_behaviorstringPossible valuesalways_invoicecreate_prorationsnone
schedule_at_period_endobjectChild parameters are listed in the OpenAPI document.
trial_update_behaviorstringPossible valuescontinue_trialend_trial
business_profileobjectThe business information shown to customers in the portal.
Show 3 child parameters
headlinestringprivacy_policy_urlstringterms_of_service_urlstring
default_return_urlstringThe default URL to redirect customers to when they click on the portal's link to return to your website. This can be overridden when creating the session.
expandarray of stringsSpecifies which fields in the response should be expanded.
login_pageobjectThe hosted login page for this configuration. Learn more about the portal login page in our integration docs.
Show 1 child parameter
enabledbooleanRequired
metadataobjectSet 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.namestringThe name of the configuration.
Returns
The billing_portal.configuration object.
curl https://api.knoxapi.com/v1/billing_portal/configurations \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
-d features=const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const response = await stripe.rawRequest('POST', '/v1/billing_portal/configurations', {
features: {},
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
response = client.raw_request("post", "/v1/billing_portal/configurations", features={})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
response = Stripe.raw_request(:post, '/v1/billing_portal/configurations', {
features: {},
}){
"active": true,
"application": null,
"business_profile": {
"headline": null,
"privacy_policy_url": "https://example.com/privacy",
"terms_of_service_url": "https://example.com/terms"
},
"created": 1234567890,
"default_return_url": null,
"features": {
"customer_update": {
"allowed_updates": [
"email",
"tax_id"
],
"enabled": true
},
"invoice_history": {
"enabled": true
},
"payment_method_update": {
"enabled": false,
"payment_method_configuration": null
},
"subscription_cancel": {
"cancellation_reason": {
"enabled": false,
"options": [],
"feedback_options": null
},
"enabled": false,
"mode": "at_period_end",
"proration_behavior": "none"
},
"subscription_update": {
"default_allowed_updates": [],
"enabled": false,
"proration_behavior": "none",
"schedule_at_period_end": {
"conditions": [
{
"type": "decreasing_item_amount"
}
]
},
"trial_update_behavior": "end_trial",
"billing_cycle_anchor": null
}
},
"id": "bpc_1Pgc70B7WZ01zgkWSnFO04Vt",
"is_default": true,
"livemode": true,
"login_page": {
"enabled": false,
"url": null
},
"metadata": null,
"object": "billing_portal.configuration",
"updated": 1234567890,
"name": null
}List portal configurations
GET/v1/billing_portal/configurations
Returns a list of configurations that describe the functionality of the customer portal.
Query parameters
activebooleanOnly return configurations that are active or inactive (e.g., pass
trueto only list active configurations).ending_beforestringA cursor for use in pagination.
ending_beforeis an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting withobj_bar, your subsequent call can includeending_before=obj_barin order to fetch the previous page of the list.expandarray of stringsSpecifies which fields in the response should be expanded.
is_defaultbooleanOnly return the default or non-default configurations (e.g., pass
trueto only list the default configuration).limitintegerA limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
starting_afterstringA cursor for use in pagination.
starting_afteris an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending withobj_foo, your subsequent call can includestarting_after=obj_fooin order to fetch the next page of the list.
Returns
A list of billing_portal.configuration objects.
curl -G https://api.knoxapi.com/v1/billing_portal/configurations \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
--data-urlencode limit=3const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const response = await stripe.rawRequest('GET', '/v1/billing_portal/configurations', {
limit: 3,
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
response = client.raw_request("get", "/v1/billing_portal/configurations", limit=3)require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
response = Stripe.raw_request(:get, '/v1/billing_portal/configurations', {
limit: 3,
}){
"object": "list",
"url": "/v1/billing_portal/configurations",
"has_more": false,
"data": [
{
"active": true,
"application": null,
"business_profile": {
"headline": null,
"privacy_policy_url": "https://example.com/privacy",
"terms_of_service_url": "https://example.com/terms"
},
"created": 1234567890,
"default_return_url": null,
"features": {
"customer_update": {
"allowed_updates": [
"email",
"tax_id"
],
"enabled": true
},
"invoice_history": {
"enabled": true
},
"payment_method_update": {
"enabled": false,
"payment_method_configuration": null
},
"subscription_cancel": {
"cancellation_reason": {
"enabled": false,
"options": [],
"feedback_options": null
},
"enabled": false,
"mode": "at_period_end",
"proration_behavior": "none"
},
"subscription_update": {
"default_allowed_updates": [],
"enabled": false,
"proration_behavior": "none",
"schedule_at_period_end": {
"conditions": [
{
"type": "decreasing_item_amount"
}
]
},
"trial_update_behavior": "end_trial",
"billing_cycle_anchor": null
}
},
"id": "bpc_1Pgc70B7WZ01zgkWSnFO04Vt",
"is_default": true,
"livemode": true,
"login_page": {
"enabled": false,
"url": null
},
"metadata": null,
"object": "billing_portal.configuration",
"updated": 1234567890,
"name": null
}
]
}Create a portal session
POST/v1/billing_portal/sessions
Creates a session of the customer portal.
Body parameters
configurationstringThe ID of an existing configuration to use for this session, describing its functionality and features. If not specified, the session uses the default configuration.
customerstringThe ID of an existing customer.
customer_accountstringThe ID of an existing account.
expandarray of stringsSpecifies which fields in the response should be expanded.
flow_dataobjectInformation about a specific flow for the customer to go through. See the docs to learn more about using customer portal deep links and flows.
Show 5 child parameters
typestringRequiredPossible valuescustomer_updatepayment_method_updatesubscription_cancelsubscription_updatesubscription_update_confirm
after_completionobjectShow 3 child parameters
typestringRequiredPossible valueshosted_confirmationportal_homepageredirect
hosted_confirmationobjectChild parameters are listed in the OpenAPI document.
redirectobjectChild parameters are listed in the OpenAPI document.
subscription_cancelobjectShow 2 child parameters
subscriptionstringRequiredretentionobjectChild parameters are listed in the OpenAPI document.
subscription_updateobjectShow 1 child parameter
subscriptionstringRequired
subscription_update_confirmobjectShow 3 child parameters
itemsarray of objectsRequiredChild parameters are listed in the OpenAPI document.
subscriptionstringRequireddiscountsarray of objectsChild parameters are listed in the OpenAPI document.
localestringThe IETF language tag of the locale customer portal is displayed in. If blank or auto, the customer’s
preferred_localesor browser’s locale is used.Possible valuesautobgcsdadeelenen-AUen-CAen-GBen-IEen-INen-NZen-SGeses-419- and 31 more
on_behalf_ofstringThe
on_behalf_ofaccount to use for this session. When specified, only subscriptions and invoices with thison_behalf_ofaccount appear in the portal. For more information, see the docs. Use the Accounts API to modify theon_behalf_ofaccount's branding settings, which the portal displays.return_urlstringThe default URL to redirect customers to when they click on the portal's link to return to your website.
Returns
The billing_portal.session object.
curl -X POST https://api.knoxapi.com/v1/billing_portal/sessions \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const response = await stripe.rawRequest('POST', '/v1/billing_portal/sessions');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
response = client.raw_request("post", "/v1/billing_portal/sessions")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
response = Stripe.raw_request(:post, '/v1/billing_portal/sessions'){
"configuration": "bpc_1Pgc7HB7WZ01zgkWxH2EPWRX",
"created": 1234567890,
"customer": "cus_QXg1o8vcGmoR32",
"flow": {
"after_completion": {
"hosted_confirmation": {
"custom_message": null
},
"redirect": {
"return_url": "return_url"
},
"type": "hosted_confirmation"
},
"subscription_cancel": {
"retention": {
"coupon_offer": {
"coupon": "coupon"
},
"type": "coupon_offer"
},
"subscription": "subscription"
},
"subscription_update": {
"subscription": "subscription"
},
"subscription_update_confirm": {
"discounts": null,
"items": [
{
"id": null,
"price": null
}
],
"subscription": "subscription"
},
"type": "subscription_update",
"customer_update": {}
},
"id": "bps_1Pgc7HB7WZ01zgkWNs8s9Auh",
"livemode": true,
"locale": null,
"object": "billing_portal.session",
"on_behalf_of": null,
"return_url": "https://example.com/account",
"url": "https://sangeekp-15t6ai--customer_portal-mydev.dev.stripe.me/session/{SESSION_SECRET}",
"customer_account": null
}Update a portal configuration
POST/v1/billing_portal/configurations/{configuration}
Updates a configuration that describes the functionality of the customer portal.
Path parameters
configurationstringRequired
Body parameters
activebooleanWhether the configuration is active and can be used to create portal sessions.
business_profileobjectThe business information shown to customers in the portal.
Show 3 child parameters
headlinestringprivacy_policy_urlstringterms_of_service_urlstring
default_return_urlstringThe default URL to redirect customers to when they click on the portal's link to return to your website. This can be overridden when creating the session.
expandarray of stringsSpecifies which fields in the response should be expanded.
featuresobjectInformation about the features available in the portal.
Show 5 child parameters
customer_updateobjectShow 2 child parameters
allowed_updatesarray of stringsenabledboolean
invoice_historyobjectShow 1 child parameter
enabledbooleanRequired
payment_method_updateobjectShow 2 child parameters
enabledbooleanRequiredpayment_method_configurationstring
subscription_cancelobjectShow 4 child parameters
cancellation_reasonobjectChild parameters are listed in the OpenAPI document.
enabledbooleanmodestringPossible valuesat_period_endimmediately
proration_behaviorstringPossible valuesalways_invoicecreate_prorationsnone
subscription_updateobjectShow 7 child parameters
billing_cycle_anchorstringPossible valuesnowunchanged
default_allowed_updatesarray of stringsenabledbooleanproductsarray of objectsChild parameters are listed in the OpenAPI document.
proration_behaviorstringPossible valuesalways_invoicecreate_prorationsnone
schedule_at_period_endobjectChild parameters are listed in the OpenAPI document.
trial_update_behaviorstringPossible valuescontinue_trialend_trial
login_pageobjectThe hosted login page for this configuration. Learn more about the portal login page in our integration docs.
Show 1 child parameter
enabledbooleanRequired
metadataobjectSet 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.namestringThe name of the configuration.
Returns
The billing_portal.configuration object.
curl https://api.knoxapi.com/v1/billing_portal/configurations/bpc_1Pgc70B7WZ01zgkWSnFO04Vt \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
-d "metadata[order_id]=6735"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const response = await stripe.rawRequest('POST', '/v1/billing_portal/configurations/bpc_1Pgc70B7WZ01zgkWSnFO04Vt', {
metadata: {
order_id: '6735',
},
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
response = client.raw_request("post", "/v1/billing_portal/configurations/bpc_1Pgc70B7WZ01zgkWSnFO04Vt", metadata={
"order_id": "6735",
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
response = Stripe.raw_request(:post, '/v1/billing_portal/configurations/bpc_1Pgc70B7WZ01zgkWSnFO04Vt', {
metadata: {
order_id: '6735',
},
}){
"active": true,
"application": null,
"business_profile": {
"headline": null,
"privacy_policy_url": "https://example.com/privacy",
"terms_of_service_url": "https://example.com/terms"
},
"created": 1234567890,
"default_return_url": null,
"features": {
"customer_update": {
"allowed_updates": [
"email",
"tax_id"
],
"enabled": true
},
"invoice_history": {
"enabled": true
},
"payment_method_update": {
"enabled": false,
"payment_method_configuration": null
},
"subscription_cancel": {
"cancellation_reason": {
"enabled": false,
"options": [],
"feedback_options": null
},
"enabled": false,
"mode": "at_period_end",
"proration_behavior": "none"
},
"subscription_update": {
"default_allowed_updates": [],
"enabled": false,
"proration_behavior": "none",
"schedule_at_period_end": {
"conditions": [
{
"type": "decreasing_item_amount"
}
]
},
"trial_update_behavior": "end_trial",
"billing_cycle_anchor": null
}
},
"id": "bpc_1Pgc70B7WZ01zgkWSnFO04Vt",
"is_default": true,
"livemode": true,
"login_page": {
"enabled": false,
"url": null
},
"metadata": null,
"object": "billing_portal.configuration",
"updated": 1234567890,
"name": null
}Retrieve a portal configuration
GET/v1/billing_portal/configurations/{configuration}
Retrieves a configuration that describes the functionality of the customer portal.
Path parameters
configurationstringRequired
Query parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
Returns
The billing_portal.configuration object.
curl https://api.knoxapi.com/v1/billing_portal/configurations/bpc_1Pgc70B7WZ01zgkWSnFO04Vt \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const response = await stripe.rawRequest('GET', '/v1/billing_portal/configurations/bpc_1Pgc70B7WZ01zgkWSnFO04Vt');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
response = client.raw_request("get", "/v1/billing_portal/configurations/bpc_1Pgc70B7WZ01zgkWSnFO04Vt")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
response = Stripe.raw_request(:get, '/v1/billing_portal/configurations/bpc_1Pgc70B7WZ01zgkWSnFO04Vt'){
"active": true,
"application": null,
"business_profile": {
"headline": null,
"privacy_policy_url": "https://example.com/privacy",
"terms_of_service_url": "https://example.com/terms"
},
"created": 1234567890,
"default_return_url": null,
"features": {
"customer_update": {
"allowed_updates": [
"email",
"tax_id"
],
"enabled": true
},
"invoice_history": {
"enabled": true
},
"payment_method_update": {
"enabled": false,
"payment_method_configuration": null
},
"subscription_cancel": {
"cancellation_reason": {
"enabled": false,
"options": [],
"feedback_options": null
},
"enabled": false,
"mode": "at_period_end",
"proration_behavior": "none"
},
"subscription_update": {
"default_allowed_updates": [],
"enabled": false,
"proration_behavior": "none",
"schedule_at_period_end": {
"conditions": [
{
"type": "decreasing_item_amount"
}
]
},
"trial_update_behavior": "end_trial",
"billing_cycle_anchor": null
}
},
"id": "bpc_1Pgc70B7WZ01zgkWSnFO04Vt",
"is_default": true,
"livemode": true,
"login_page": {
"enabled": false,
"url": null
},
"metadata": null,
"object": "billing_portal.configuration",
"updated": 1234567890,
"name": null
}Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.