API REFERENCE

Create Billing Portal Session

On this page

POST/api/accounts/{id}/portal

Create a Stripe Customer Portal session for an account. Returns a hosted URL where the customer can update the card on file, view invoices, or cancel a Starter or Pro subscription; the client should redirect the user to that URL. id may be the authenticated account or an organization the caller belongs to. Enterprise (invoiced) plans are managed with your Recoup contact and the app does not offer this portal for them, but the endpoint works for any account with a Stripe customer.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/accounts/YOUR_ID/portal' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "returnUrl": "https://chat.recoupable.com/settings/billing"
}'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Path parameters

idstringrequired

The unique identifier (UUID) of the account. Must be the authenticated account or another accessible via organization membership.

Request body required

Portal session parameters

application/json

returnUrlstringrequired

The URL to redirect to when the customer leaves the portal.

format: uri

Responses

200Portal session created successfully

application/json

idstringrequired

The portal session ID.

urlstringrequired

The hosted portal URL. Redirect to this URL so the customer can manage their subscription.

format: uri

400Bad request - invalid parameters, or the account has no Stripe customer yet

application/json

errorstringrequired

Human-readable error message.

400 example

{
  "error": "No active subscription found"
}

401Unauthorized - invalid or missing authentication

application/json

errorstringrequired

Human-readable error message.

401 example

{
  "error": "Unauthorized"
}

403Forbidden - the account is not the caller's and not an organization they belong to (an unknown id also returns 403, never 404)

application/json

errorstringrequired

Human-readable error message.

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download accounts.json

View operation source

json

{
  "description": "Create a Stripe Customer Portal session for an account. Returns a hosted URL where the customer can update the card on file, view invoices, or cancel a Starter or Pro subscription; the client should redirect the user to that URL. `id` may be the authenticated account or an organization the caller belongs to. Enterprise (invoiced) plans are managed with your Recoup contact and the app does not offer this portal for them, but the endpoint works for any account with a Stripe customer.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "The unique identifier (UUID) of the account. Must be the authenticated account or another accessible via organization membership.",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "description": "Portal session parameters",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateSubscriptionPortalRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Portal session created successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CreateSubscriptionPortalResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - invalid parameters, or the account has no Stripe customer yet",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SubscriptionPortalErrorResponse"
          },
          "example": {
            "error": "No active subscription found"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - invalid or missing authentication",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SubscriptionPortalErrorResponse"
          },
          "example": {
            "error": "Unauthorized"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - the account is not the caller's and not an organization they belong to (an unknown id also returns 403, never 404)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SubscriptionPortalErrorResponse"
          }
        }
      }
    }
  }
}