> ## Documentation Index
> Fetch the complete documentation index at: https://openloop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Retention Portal Session

> Creates a Chargebee Retention pre-cancel hosted-page session for a subscription scoped to a configuration that has retention enabled. Returns a redirect URL the customer is sent to in order to enter the retention flow. Sibling endpoint to `POST /billing-portals/{provider_billing_portal_id}/sessions` — retention-enabled tenants call this endpoint instead of passing `intent=cancel` to the payment provider billing-portal endpoint.



## OpenAPI

````yaml /openapi.json post /billing-portals/retention-sessions
openapi: 3.1.0
info:
  title: OpenLoop API
  version: 0.1.0
  description: >-
    Unified reference for the OpenLoop Patient (clinical) and Payments & Revenue
    APIs.
servers:
  - url: https://api.openloophealth.com/v0.1
    description: Production partner edge
  - url: https://api-staging.openloophealth.com/v0.1
    description: Staging partner edge (sandbox credentials)
security: []
paths:
  /billing-portals/retention-sessions:
    post:
      tags:
        - Billing Portals
      summary: Create Retention Portal Session
      description: >-
        Creates a Chargebee Retention pre-cancel hosted-page session for a
        subscription scoped to a configuration that has retention enabled.
        Returns a redirect URL the customer is sent to in order to enter the
        retention flow. Sibling endpoint to `POST
        /billing-portals/{provider_billing_portal_id}/sessions` —
        retention-enabled tenants call this endpoint instead of passing
        `intent=cancel` to the payment provider billing-portal endpoint.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                provider_customer_id:
                  type: string
                  description: >-
                    Customer ID in the payment provider. Forwarded to Chargebee
                    Retention as `account.internal_id`.
                provider_subscription_id:
                  type: string
                  description: >-
                    Subscription ID in the payment provider. Forwarded to
                    Chargebee Retention as `subscription_id`.
                save_return_url:
                  type: string
                  description: >-
                    Optional redirect URL on save/retain. Forwarded to Chargebee
                    Retention as-is.
                cancel_confirmation_url:
                  type: string
                  description: >-
                    Optional redirect URL on confirm-cancel. Forwarded to
                    Chargebee Retention as-is.
                custom:
                  type: object
                  additionalProperties:
                    type: string
                  description: >-
                    Optional pass-through custom fields (e.g. `{ "program":
                    "MWL", "offer_accept_url": "..." }`).
              required:
                - provider_customer_id
                - provider_subscription_id
            example:
              provider_customer_id: test_customer_id
              provider_subscription_id: test_subscription_id_2
              save_return_url: https://app.example.com/billing?retained=true
              cancel_confirmation_url: https://app.example.com/billing?cancelled=true
              custom:
                program: MWL
                offer_accept_url: https://app.example.com/offers/accept
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      url:
                        type: string
                        description: >-
                          Chargebee Retention pre-cancel hosted-page URL for
                          client redirect.
                required:
                  - data
              example:
                data:
                  url: https://app.retention.chargebee.com/precancel/abc123def456
        '400':
          description: >-
            ValidationError: Missing/invalid `provider_customer_id` or
            `provider_subscription_id`; your configuration has no
            `retention_app_id`.
        '401':
          description: Missing or invalid bearer token.
        '403':
          description: >-
            No configuration exists for your account, or provider access has
            been disabled for it.
        '500':
          description: >-
            Upstream Chargebee Retention failure (network error, non-2xx
            response, malformed response body).
      security:
        - serviceToken: []
        - userToken: []
components:
  securitySchemes:
    serviceToken:
      type: oauth2
      description: >-
        Service (M2M) access token issued by POST /auth/token using the
        client_credentials grant. Required scopes, where known, are listed on
        each operation below.
      flows:
        clientCredentials:
          tokenUrl: https://api.openloophealth.com/v0.1/auth/token
          scopes: {}
    userToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        User access token issued by POST /auth/token via the verification-code
        grant (after Verify a one-time code) or the refresh_token grant.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.