API reference
Test mode. Use your secret key on your server; live processing is currently disabled.
https://api.knoxapi.comSend form-encoded requests with Authorization: Bearer sk_test_....
Complete OpenAPI specification · Integration guide
Operations and schemas are based on the pinned Stripe OpenAPI specification (MIT). Nested object definitions and enums are available in the complete specification.
GET /v1/billing_portal/configurations
List portal configurations
Returns a list of configurations that describe the functionality of the customer portal.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
active | query | boolean | Only return configurations that are active or inactive (e.g., pass `true` to only list active configurations). |
ending_before | query | string | A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list. |
expand | query | array of string | Specifies which fields in the response should be expanded. |
is_default | query | boolean | Only return the default or non-default configurations (e.g., pass `true` to only list the default configuration). |
limit | query | integer | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. |
starting_after | query | string | A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list. |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
data required | array of billing_portal.configuration | |
has_more required | boolean | True if this list has another page of items after this one that can be fetched. |
object required | string | String representing the object's type. Objects of the same type share the same value. Always has the value `list`. |
url required | string | The URL where this list can be accessed. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |
POST /v1/billing_portal/configurations
Create a portal configuration
Creates a configuration that describes the functionality and behavior of a PortalSession
Request parameters
| Field | Type | Description |
|---|---|---|
business_profile | object | The business information shown to customers in the portal. |
default_return_url | one of multiple schemas | The default URL to redirect customers to when they click on the portal's link to return to your website. This can be [overridden](https://docs.stripe.com/api/customer_portal/sessions/create#create_portal_session-return_url) when creating the session. |
expand | array of string | Specifies which fields in the response should be expanded. |
features required | object | Information about the features available in the portal. |
login_page | object | The hosted login page for this configuration. Learn more about the portal login page in our [integration docs](https://stripe.com/docs/billing/subscriptions/integrating-customer-portal#share). |
metadata | object | Set of [key-value pairs](https://docs.stripe.com/api/metadata) 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`. |
name | one of multiple schemas | The name of the configuration. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
active required | boolean | Whether the configuration is active and can be used to create portal sessions. |
application | one of multiple schemas | ID of the Connect Application that created the configuration. |
business_profile required | portal_business_profile | |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
default_return_url | string | The default URL to redirect customers to when they click on the portal's link to return to your website. This can be [overridden](https://docs.stripe.com/api/customer_portal/sessions/create#create_portal_session-return_url) when creating the session. |
features required | portal_features | |
id required | string | Unique identifier for the object. |
is_default required | boolean | Whether the configuration is the default. If `true`, this configuration can be managed in the Dashboard and portal sessions will use this configuration unless it is overriden when creating the session. |
livemode required | boolean | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
login_page required | portal_login_page | |
metadata | object | Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. |
name | string | The name of the configuration. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
updated required | integer | Time at which the object was last updated. Measured in seconds since the Unix epoch. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |
POST /v1/billing_portal/sessions
Create a portal session
Creates a session of the customer portal.
Request parameters
| Field | Type | Description |
|---|---|---|
configuration | string | The ID of an existing [configuration](https://docs.stripe.com/api/customer_portal/configurations) to use for this session, describing its functionality and features. If not specified, the session uses the default configuration. |
customer | string | The ID of an existing customer. |
customer_account | string | The ID of an existing account. |
expand | array of string | Specifies which fields in the response should be expanded. |
flow_data | object | Information about a specific flow for the customer to go through. See the [docs](https://docs.stripe.com/customer-management/portal-deep-links) to learn more about using customer portal deep links and flows. |
locale | string | The IETF language tag of the locale customer portal is displayed in. If blank or auto, the customer’s `preferred_locales` or browser’s locale is used. |
on_behalf_of | string | The `on_behalf_of` account to use for this session. When specified, only subscriptions and invoices with this `on_behalf_of` account appear in the portal. For more information, see the [docs](https://docs.stripe.com/connect/separate-charges-and-transfers#settlement-merchant). Use the [Accounts API](https://docs.stripe.com/api/accounts/object#account_object-settings-branding) to modify the `on_behalf_of` account's branding settings, which the portal displays. |
return_url | string | The default URL to redirect customers to when they click on the portal's link to return to your website. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
configuration required | one of multiple schemas | The configuration used by this session, describing the features available. |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
customer required | string | The ID of the customer for this session. |
customer_account | string | The ID of the account for this session. |
flow | one of multiple schemas | Information about a specific flow for the customer to go through. See the [docs](https://docs.stripe.com/customer-management/portal-deep-links) to learn more about using customer portal deep links and flows. |
id required | string | Unique identifier for the object. |
livemode required | boolean | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
locale | string | The IETF language tag of the locale Customer Portal is displayed in. If blank or auto, the customer’s `preferred_locales` or browser’s locale is used. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
on_behalf_of | string | The account for which the session was created on behalf of. When specified, only subscriptions and invoices with this `on_behalf_of` account appear in the portal. For more information, see the [docs](https://docs.stripe.com/connect/separate-charges-and-transfers#settlement-merchant). Use the [Accounts API](https://docs.stripe.com/api/accounts/object#account_object-settings-branding) to modify the `on_behalf_of` account's branding settings, which the portal displays. |
return_url | string | The URL to redirect customers to when they click on the portal's link to return to your website. |
url required | string | The short-lived URL of the session that gives customers access to the customer portal. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |
GET /v1/billing_portal/configurations/{configuration}
Retrieve a portal configuration
Retrieves a configuration that describes the functionality of the customer portal.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
configuration | path | string | |
expand | query | array of string | Specifies which fields in the response should be expanded. |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
active required | boolean | Whether the configuration is active and can be used to create portal sessions. |
application | one of multiple schemas | ID of the Connect Application that created the configuration. |
business_profile required | portal_business_profile | |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
default_return_url | string | The default URL to redirect customers to when they click on the portal's link to return to your website. This can be [overridden](https://docs.stripe.com/api/customer_portal/sessions/create#create_portal_session-return_url) when creating the session. |
features required | portal_features | |
id required | string | Unique identifier for the object. |
is_default required | boolean | Whether the configuration is the default. If `true`, this configuration can be managed in the Dashboard and portal sessions will use this configuration unless it is overriden when creating the session. |
livemode required | boolean | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
login_page required | portal_login_page | |
metadata | object | Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. |
name | string | The name of the configuration. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
updated required | integer | Time at which the object was last updated. Measured in seconds since the Unix epoch. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |
POST /v1/billing_portal/configurations/{configuration}
Update a portal configuration
Updates a configuration that describes the functionality of the customer portal.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
configuration | path | string |
| Field | Type | Description |
|---|---|---|
active | boolean | Whether the configuration is active and can be used to create portal sessions. |
business_profile | object | The business information shown to customers in the portal. |
default_return_url | one of multiple schemas | The default URL to redirect customers to when they click on the portal's link to return to your website. This can be [overridden](https://docs.stripe.com/api/customer_portal/sessions/create#create_portal_session-return_url) when creating the session. |
expand | array of string | Specifies which fields in the response should be expanded. |
features | object | Information about the features available in the portal. |
login_page | object | The hosted login page for this configuration. Learn more about the portal login page in our [integration docs](https://stripe.com/docs/billing/subscriptions/integrating-customer-portal#share). |
metadata | one of multiple schemas | Set of [key-value pairs](https://docs.stripe.com/api/metadata) 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`. |
name | one of multiple schemas | The name of the configuration. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
active required | boolean | Whether the configuration is active and can be used to create portal sessions. |
application | one of multiple schemas | ID of the Connect Application that created the configuration. |
business_profile required | portal_business_profile | |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
default_return_url | string | The default URL to redirect customers to when they click on the portal's link to return to your website. This can be [overridden](https://docs.stripe.com/api/customer_portal/sessions/create#create_portal_session-return_url) when creating the session. |
features required | portal_features | |
id required | string | Unique identifier for the object. |
is_default required | boolean | Whether the configuration is the default. If `true`, this configuration can be managed in the Dashboard and portal sessions will use this configuration unless it is overriden when creating the session. |
livemode required | boolean | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
login_page required | portal_login_page | |
metadata | object | Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. |
name | string | The name of the configuration. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
updated required | integer | Time at which the object was last updated. Measured in seconds since the Unix epoch. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |