API reference

Billing Portal

Knox answers these operations with the same requests and responses as Stripe's API. Authenticate with your secret key, Authorization: Bearer sk_test_..., from your server, and send form-encoded bodies. Test mode only: live processing is currently disabled.

Create a portal configuration

POST/v1/billing_portal/configurations

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

Body parameters

  • featuresobjectRequired

    Information about the features available in the portal.

    Show 5 child parameters
    • customer_updateobject
      Show 2 child parameters
      • enabledbooleanRequired
      • allowed_updatesarray of strings
    • invoice_historyobject
      Show 1 child parameter
      • enabledbooleanRequired
    • payment_method_updateobject
      Show 2 child parameters
      • enabledbooleanRequired
      • payment_method_configurationstring
    • subscription_cancelobject
      Show 4 child parameters
      • enabledbooleanRequired
      • cancellation_reasonobject

        Child parameters are listed in the OpenAPI document.

      • modestring
        Possible values
        • at_period_end
        • immediately
      • proration_behaviorstring
        Possible values
        • always_invoice
        • create_prorations
        • none
    • subscription_updateobject
      Show 7 child parameters
      • enabledbooleanRequired
      • billing_cycle_anchorstring
        Possible values
        • now
        • unchanged
      • default_allowed_updatesarray of strings
      • productsarray of objects

        Child parameters are listed in the OpenAPI document.

      • proration_behaviorstring
        Possible values
        • always_invoice
        • create_prorations
        • none
      • schedule_at_period_endobject

        Child parameters are listed in the OpenAPI document.

      • trial_update_behaviorstring
        Possible values
        • continue_trial
        • end_trial
  • business_profileobject

    The business information shown to customers in the portal.

    Show 3 child parameters
    • headlinestring
    • privacy_policy_urlstring
    • terms_of_service_urlstring
  • 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 overridden when creating the session.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • login_pageobject

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

    Show 1 child parameter
    • enabledbooleanRequired
  • 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

The billing_portal.configuration object.

POST /v1/billing_portal/configurations
curl https://api.knoxapi.com/v1/billing_portal/configurations \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d features=
Response
{
  "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

  • activeboolean

    Only return configurations that are active or inactive (e.g., pass true to only list active configurations).

  • ending_beforestring

    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.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • is_defaultboolean

    Only return the default or non-default configurations (e.g., pass true to only list the default configuration).

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • starting_afterstring

    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.

Returns

A list of billing_portal.configuration objects.

GET /v1/billing_portal/configurations
curl -G https://api.knoxapi.com/v1/billing_portal/configurations \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "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

  • configurationstring

    The ID of an existing configuration to use for this session, describing its functionality and features. If not specified, the session uses the default configuration.

  • customerstring

    The ID of an existing customer.

  • customer_accountstring

    The ID of an existing account.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • flow_dataobject

    Information 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
    • typestringRequired
      Possible values
      • customer_update
      • payment_method_update
      • subscription_cancel
      • subscription_update
      • subscription_update_confirm
    • after_completionobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • hosted_confirmation
        • portal_homepage
        • redirect
      • hosted_confirmationobject

        Child parameters are listed in the OpenAPI document.

      • redirectobject

        Child parameters are listed in the OpenAPI document.

    • subscription_cancelobject
      Show 2 child parameters
      • subscriptionstringRequired
      • retentionobject

        Child parameters are listed in the OpenAPI document.

    • subscription_updateobject
      Show 1 child parameter
      • subscriptionstringRequired
    • subscription_update_confirmobject
      Show 3 child parameters
      • itemsarray of objectsRequired

        Child parameters are listed in the OpenAPI document.

      • subscriptionstringRequired
      • discountsarray of objects

        Child parameters are listed in the OpenAPI document.

  • localestring

    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.

    Possible values
    • auto
    • bg
    • cs
    • da
    • de
    • el
    • en
    • en-AU
    • en-CA
    • en-GB
    • en-IE
    • en-IN
    • en-NZ
    • en-SG
    • es
    • es-419
    • and 31 more
  • on_behalf_ofstring

    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. Use the Accounts API to modify the on_behalf_of account's branding settings, which the portal displays.

  • return_urlstring

    The 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.

POST /v1/billing_portal/sessions
curl -X POST https://api.knoxapi.com/v1/billing_portal/sessions \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "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

  • activeboolean

    Whether the configuration is active and can be used to create portal sessions.

  • business_profileobject

    The business information shown to customers in the portal.

    Show 3 child parameters
    • headlinestring
    • privacy_policy_urlstring
    • terms_of_service_urlstring
  • 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 overridden when creating the session.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • featuresobject

    Information about the features available in the portal.

    Show 5 child parameters
    • customer_updateobject
      Show 2 child parameters
      • allowed_updatesarray of strings
      • enabledboolean
    • invoice_historyobject
      Show 1 child parameter
      • enabledbooleanRequired
    • payment_method_updateobject
      Show 2 child parameters
      • enabledbooleanRequired
      • payment_method_configurationstring
    • subscription_cancelobject
      Show 4 child parameters
      • cancellation_reasonobject

        Child parameters are listed in the OpenAPI document.

      • enabledboolean
      • modestring
        Possible values
        • at_period_end
        • immediately
      • proration_behaviorstring
        Possible values
        • always_invoice
        • create_prorations
        • none
    • subscription_updateobject
      Show 7 child parameters
      • billing_cycle_anchorstring
        Possible values
        • now
        • unchanged
      • default_allowed_updatesarray of strings
      • enabledboolean
      • productsarray of objects

        Child parameters are listed in the OpenAPI document.

      • proration_behaviorstring
        Possible values
        • always_invoice
        • create_prorations
        • none
      • schedule_at_period_endobject

        Child parameters are listed in the OpenAPI document.

      • trial_update_behaviorstring
        Possible values
        • continue_trial
        • end_trial
  • login_pageobject

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

    Show 1 child parameter
    • enabledbooleanRequired
  • 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

The billing_portal.configuration object.

POST /v1/billing_portal/configurations/{configuration}
curl https://api.knoxapi.com/v1/billing_portal/configurations/bpc_1Pgc70B7WZ01zgkWSnFO04Vt \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "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 strings

    Specifies which fields in the response should be expanded.

Returns

The billing_portal.configuration object.

GET /v1/billing_portal/configurations/{configuration}
curl https://api.knoxapi.com/v1/billing_portal/configurations/bpc_1Pgc70B7WZ01zgkWSnFO04Vt \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "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.