Create a billing portal session

Creates a session and returns a URL into the payment provider’s hosted billing portal, where a customer manages cards, addresses and subscriptions — none of which Tied exposes as its own endpoints.

What is behind that URL is the provider’s. It can change without a change here, so redirect rather than embed, and do not store the URL. An account with no customer record at the provider returns a 422 with type: "portal_unavailable".

POST

api

accounts

{account_id}

billing

portal_sessions

Create a billing portal session

curl --request POST \
  --url https://app.tied.com/api/v1/accounts/{account_id}/billing/portal_sessions \
  --header 'Content-Type: application/json' \
  --header 'api_access_token: <api-key>' \
  --data '
{
  "session_reference": "docs-example-session-1",
  "return_path": "/settings/billing"
}
'

import requests

url = "https://app.tied.com/api/v1/accounts/{account_id}/billing/portal_sessions"

payload = {
    "session_reference": "docs-example-session-1",
    "return_path": "/settings/billing"
}
headers = {
    "api_access_token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {api_access_token: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({session_reference: 'docs-example-session-1', return_path: '/settings/billing'})
};

fetch('https://app.tied.com/api/v1/accounts/{account_id}/billing/portal_sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

require 'uri'
require 'net/http'

url = URI("https://app.tied.com/api/v1/accounts/{account_id}/billing/portal_sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api_access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"session_reference\": \"docs-example-session-1\",\n  \"return_path\": \"/settings/billing\"\n}"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.tied.com/api/v1/accounts/{account_id}/billing/portal_sessions"

	payload := strings.NewReader("{\n  \"session_reference\": \"docs-example-session-1\",\n  \"return_path\": \"/settings/billing\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api_access_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "schema_version": "1",
  "account_id": 1,
  "portal_session": {
    "url": "https://billing.example-provider.com/session/EXAMPLE"
  },
  "freshness": {
    "source": "stripe",
    "as_of": "2026-09-21T04:24:40Z",
    "state": "fresh"
  }
}

{
  "error": "Resource could not be found"
}

{
  "message": "Url has already been taken",
  "attributes": [
    "url"
  ]
}

Authorizations

api_access_token

string

header

required

This token can be obtained by visiting the profile page or via rails console. Provides access to endpoints based on the user permissions levels. This token can be saved by an external system when user is created via API, to perform activities on behalf of the user.

Path Parameters

integer

required

The numeric ID of the account

Body

application/json

session_reference

string

required

Your own idempotency key for this session.

Example:

"docs-example-session-1"

return_path

string

Where the provider should send the customer back to, relative to your dashboard.

Example:

"/settings/billing"

Response

Success

A URL into the payment provider's own hosted flow. What sits behind that URL is the provider's, not ours — its appearance, its steps and the shape of anything it returns can change without a change here. Treat the URL as short-lived and redirect to it rather than storing it.

schema_version

string

Version of this payload's shape.

account_id

integer

The account.

freshness

object

Where this answer came from and how current it is. Billing reads several systems, so every response says which one it used — treat state other than fresh as a reason to be careful with the numbers rather than a failure.

Show child attributes

Create a billing portal session

curl --request POST \
  --url https://app.tied.com/api/v1/accounts/{account_id}/billing/portal_sessions \
  --header 'Content-Type: application/json' \
  --header 'api_access_token: <api-key>' \
  --data '
{
  "session_reference": "docs-example-session-1",
  "return_path": "/settings/billing"
}
'

import requests

url = "https://app.tied.com/api/v1/accounts/{account_id}/billing/portal_sessions"

payload = {
    "session_reference": "docs-example-session-1",
    "return_path": "/settings/billing"
}
headers = {
    "api_access_token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {api_access_token: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({session_reference: 'docs-example-session-1', return_path: '/settings/billing'})
};

fetch('https://app.tied.com/api/v1/accounts/{account_id}/billing/portal_sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

require 'uri'
require 'net/http'

url = URI("https://app.tied.com/api/v1/accounts/{account_id}/billing/portal_sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api_access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"session_reference\": \"docs-example-session-1\",\n  \"return_path\": \"/settings/billing\"\n}"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.tied.com/api/v1/accounts/{account_id}/billing/portal_sessions"

	payload := strings.NewReader("{\n  \"session_reference\": \"docs-example-session-1\",\n  \"return_path\": \"/settings/billing\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api_access_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "schema_version": "1",
  "account_id": 1,
  "portal_session": {
    "url": "https://billing.example-provider.com/session/EXAMPLE"
  },
  "freshness": {
    "source": "stripe",
    "as_of": "2026-09-21T04:24:40Z",
    "state": "fresh"
  }
}

{
  "error": "Resource could not be found"
}

{
  "message": "Url has already been taken",
  "attributes": [
    "url"
  ]
}

Getting started

Conversations

Contacts

Inboxes and channels

Automation and routing

Reporting

Help Center

Account and access

Billing

Client API

Widget API

Receiving webhooks

Create a billing portal session

Authorizations

Path Parameters

Body

Response