Payments

The Payments API lets you manage subscription Plans, configure Taxes, and handle tenant Subscriptions. Plans define the pricing tiers available to your tenants, taxes are applied per country, and subscriptions tie a tenant to a specific plan and price.

Plans

List Plans

List all plans configured for your app.

HTTP Request

GET https://api.thebridge.dev/account/payments/plan

Response `HTTP 200`

HTTP 200 — Returns an array of plan objects.

Request example

curl --request GET 'https://api.thebridge.dev/account/payments/plan' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

[
    {
        "id": "650c548c29b15b62e681f28a",
        "key": "premium",
        "name": "Premium",
        "trial": true,
        "trialDays": 14,
        "prices": [
            { "amount": 50, "currency": "EUR", "recurrenceInterval": "month" }
        ],
        "createdAt": "2023-09-21T14:34:52.248Z"
    }
]

▶ GET Try it out

GET https://api.thebridge.dev/account/payments/plan

x-api-key required Stored in session memory only. Never persisted.

Create a Plan

Create a new subscription plan.

HTTP Request

POST https://api.thebridge.dev/account/payments/plan

Body Parameters

Parameter	Type	Required	Description
`key`	`string`	Required	A unique key for this plan
`name`	`string`	Required	A presentable label for this plan
`description`	`string`	Optional	Optional description of the plan
`trial`	`boolean`	Optional	Whether this plan includes a trial period
`trialDays`	`number`	Optional	Number of trial days (required when `trial` is `true`)
`prices`	`Price[]`	Required	Array of price objects: `{ amount, currency, recurrenceInterval }`

Price Object

Parameter	Type	Required	Description
`amount`	`number`	Required	Price amount
`currency`	`string`	Required	ISO 4217 currency code (e.g. `EUR`, `USD`)
`recurrenceInterval`	`string`	Required	Billing interval: `day`, `week`, `month`, or `year`

Response `HTTP 200`

HTTP 200 — Returns the created plan object.

Request example

curl --request POST 'https://api.thebridge.dev/account/payments/plan' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "key": "premium",
  "name": "Premium",
  "description": "Full-featured premium plan",
  "trial": true,
  "trialDays": 14,
  "prices": [
    { "amount": 50, "currency": "EUR", "recurrenceInterval": "month" }
  ]
}'

Response example:

{
    "id": "650c548c29b15b62e681f28a",
    "key": "premium",
    "name": "Premium",
    "trial": true,
    "trialDays": 14,
    "prices": [
        { "amount": 50, "currency": "EUR", "recurrenceInterval": "month" }
    ],
    "createdAt": "2023-09-21T14:34:52.248Z"
}

▶ POST Try it out

POST https://api.thebridge.dev/account/payments/plan

x-api-key required Stored in session memory only. Never persisted.

Request Body (JSON)

Get a Plan

Retrieve a single plan by ID.

HTTP Request

GET https://api.thebridge.dev/account/payments/plan/:PLAN_ID

Response `HTTP 200`

HTTP 200 — Returns the plan object.

Request example

curl --request GET 'https://api.thebridge.dev/account/payments/plan/PLAN_ID' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

{
    "id": "650c548c29b15b62e681f28a",
    "key": "premium",
    "name": "Premium",
    "trial": true,
    "trialDays": 14,
    "prices": [
        { "amount": 50, "currency": "EUR", "recurrenceInterval": "month" }
    ],
    "createdAt": "2023-09-21T14:34:52.248Z"
}

▶ GET Try it out

GET https://api.thebridge.dev/account/payments/plan/:PLAN_ID

x-api-key required Stored in session memory only. Never persisted.

PLAN_ID URL parameter The ID of the plan

Update a Plan

Update an existing plan.

HTTP Request

PUT https://api.thebridge.dev/account/payments/plan/:PLAN_ID

Body Parameters

Parameter	Type	Required	Description
`key`	`string`	Optional	A unique key for this plan
`name`	`string`	Optional	A presentable label for this plan
`description`	`string`	Optional	Optional description
`trial`	`boolean`	Optional	Whether this plan includes a trial period
`trialDays`	`number`	Optional	Number of trial days
`prices`	`Price[]`	Optional	Array of price objects

Response `HTTP 200`

HTTP 200 — Returns the updated plan object.

Request example

curl --request PUT 'https://api.thebridge.dev/account/payments/plan/PLAN_ID' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Premium Plus",
  "trialDays": 30
}'

▶ PUT Try it out

PUT https://api.thebridge.dev/account/payments/plan/:PLAN_ID

x-api-key required Stored in session memory only. Never persisted.

PLAN_ID URL parameter The ID of the plan

Request Body (JSON)

Delete a Plan

Delete an existing plan.

HTTP Request

DELETE https://api.thebridge.dev/account/payments/plan/:PLAN_ID

Response `HTTP 200`

HTTP 200 — Empty body on success.

Request example

curl --request DELETE 'https://api.thebridge.dev/account/payments/plan/PLAN_ID' \
--header 'x-api-key: YOUR_APP_API_KEY'

▶ DELETE Try it out

DELETE https://api.thebridge.dev/account/payments/plan/:PLAN_ID

x-api-key required Stored in session memory only. Never persisted.

PLAN_ID URL parameter The ID of the plan

Taxes

List Taxes

List all taxes configured for your app.

HTTP Request

GET https://api.thebridge.dev/account/payments/tax

Response `HTTP 200`

HTTP 200 — Returns an array of tax objects.

Request example

curl --request GET 'https://api.thebridge.dev/account/payments/tax' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

[
    {
        "id": "650c6a1b29b15b62e681f2a1",
        "countryCode": "SE",
        "name": "VAT",
        "percentage": 25
    }
]

▶ GET Try it out

GET https://api.thebridge.dev/account/payments/tax

x-api-key required Stored in session memory only. Never persisted.

Create a Tax

Create a new tax entry.

HTTP Request

POST https://api.thebridge.dev/account/payments/tax

Body Parameters

Parameter	Type	Required	Description
`countryCode`	`string`	Required	ISO 3166-1 alpha-2 country code (e.g. `SE`, `US`)
`name`	`string`	Required	Tax name (e.g. `VAT`, `GST`)
`percentage`	`number`	Required	Tax percentage (e.g. `25` for 25%)

Response `HTTP 200`

HTTP 200 — Returns the created tax object.

Request example

curl --request POST 'https://api.thebridge.dev/account/payments/tax' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "countryCode": "SE",
  "name": "VAT",
  "percentage": 25
}'

Response example:

{
    "id": "650c6a1b29b15b62e681f2a1",
    "countryCode": "SE",
    "name": "VAT",
    "percentage": 25
}

▶ POST Try it out

POST https://api.thebridge.dev/account/payments/tax

x-api-key required Stored in session memory only. Never persisted.

Request Body (JSON)

Get a Tax

Retrieve a single tax by ID.

HTTP Request

GET https://api.thebridge.dev/account/payments/tax/:TAX_ID

Response `HTTP 200`

HTTP 200 — Returns the tax object.

Request example

curl --request GET 'https://api.thebridge.dev/account/payments/tax/TAX_ID' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

{
    "id": "650c6a1b29b15b62e681f2a1",
    "countryCode": "SE",
    "name": "VAT",
    "percentage": 25
}

▶ GET Try it out

GET https://api.thebridge.dev/account/payments/tax/:TAX_ID

x-api-key required Stored in session memory only. Never persisted.

TAX_ID URL parameter The ID of the tax

Update a Tax

Update an existing tax entry.

HTTP Request

PUT https://api.thebridge.dev/account/payments/tax/:TAX_ID

Body Parameters

Parameter	Type	Required	Description
`countryCode`	`string`	Optional	ISO 3166-1 alpha-2 country code
`name`	`string`	Optional	Tax name
`percentage`	`number`	Optional	Tax percentage

Response `HTTP 200`

HTTP 200 — Returns the updated tax object.

Request example

curl --request PUT 'https://api.thebridge.dev/account/payments/tax/TAX_ID' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "percentage": 20
}'

▶ PUT Try it out

PUT https://api.thebridge.dev/account/payments/tax/:TAX_ID

x-api-key required Stored in session memory only. Never persisted.

TAX_ID URL parameter The ID of the tax

Request Body (JSON)

Delete a Tax

Delete an existing tax entry.

HTTP Request

DELETE https://api.thebridge.dev/account/payments/tax/:TAX_ID

Response `HTTP 200`

HTTP 200 — Empty body on success.

Request example

curl --request DELETE 'https://api.thebridge.dev/account/payments/tax/TAX_ID' \
--header 'x-api-key: YOUR_APP_API_KEY'

▶ DELETE Try it out

DELETE https://api.thebridge.dev/account/payments/tax/:TAX_ID

x-api-key required Stored in session memory only. Never persisted.

TAX_ID URL parameter The ID of the tax

Subscriptions

Subscription Portal

Redirect a tenant to the hosted subscription portal where they can select a plan and enter payment details. This is a redirect URL — open it in the browser or redirect the user to it. No x-api-key header is required.

HTTP Request

GET https://api.thebridge.dev/cloud-views/subscription-portal/selectPlan?code=XXXX

Note: Replace XXXX with the tenant’s subscription portal code. This endpoint returns an HTML page, not JSON.

Request example

# This is a redirect URL — open in the browser or redirect the user.
curl --request GET 'https://api.thebridge.dev/cloud-views/subscription-portal/selectPlan?code=XXXX'

Get Tenant Payment Details

Retrieve payment and subscription details for a specific tenant.

HTTP Request

GET https://api.thebridge.dev/account/tenant/:TENANT_ID/paymentDetails

Response `HTTP 200`

HTTP 200 — Returns payment/subscription details (planKey, priceOffer).

Request example

curl --request GET 'https://api.thebridge.dev/account/tenant/TENANT_ID/paymentDetails' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

{
    "planKey": "premium",
    "priceOffer": {
        "currency": "EUR",
        "recurrenceInterval": "month"
    }
}

▶ GET Try it out

GET https://api.thebridge.dev/account/tenant/:TENANT_ID/paymentDetails

x-api-key required Stored in session memory only. Never persisted.

x-tenant-id required

TENANT_ID URL parameter The ID of the tenant

Set Tenant Plan Details

Assign a plan and price offer to a specific tenant.

HTTP Request

POST https://api.thebridge.dev/account/tenant/:TENANT_ID/paymentDetails

Body Parameters

Parameter	Type	Required	Description
`planKey`	`string`	Required	The key of the plan to assign
`priceOffer`	`object`	Required	The price offer to apply
`priceOffer.currency`	`string`	Required	ISO 4217 currency code (e.g. `EUR`, `USD`)
`priceOffer.recurrenceInterval`	`string`	Required	Billing interval: `day`, `week`, `month`, or `year`

Response `HTTP 200`

HTTP 200 — Empty body on success.

Request example

curl --request POST 'https://api.thebridge.dev/account/tenant/TENANT_ID/paymentDetails' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "planKey": "premium",
  "priceOffer": {
    "currency": "EUR",
    "recurrenceInterval": "month"
  }
}'

▶ POST Try it out

POST https://api.thebridge.dev/account/tenant/:TENANT_ID/paymentDetails

x-api-key required Stored in session memory only. Never persisted.

x-tenant-id required

TENANT_ID URL parameter The ID of the tenant

Request Body (JSON)

Payments

Plans

List Plans

HTTP Request

Response HTTP 200

Create a Plan

HTTP Request

Body Parameters

Price Object

Response HTTP 200

Get a Plan

HTTP Request

Response HTTP 200

Update a Plan

HTTP Request

Body Parameters

Response HTTP 200

Delete a Plan

HTTP Request

Response HTTP 200

Taxes

List Taxes

HTTP Request

Response HTTP 200

Create a Tax

HTTP Request

Body Parameters

Response HTTP 200

Get a Tax

HTTP Request

Response HTTP 200

Update a Tax

HTTP Request

Body Parameters

Response HTTP 200

Delete a Tax

HTTP Request

Response HTTP 200

Subscriptions

Subscription Portal

HTTP Request

Get Tenant Payment Details

HTTP Request

Response HTTP 200

Set Tenant Plan Details

HTTP Request

Body Parameters

Response HTTP 200

Response `HTTP 200`

Response `HTTP 200`

Response `HTTP 200`

Response `HTTP 200`

Response `HTTP 200`

Response `HTTP 200`

Response `HTTP 200`

Response `HTTP 200`

Response `HTTP 200`

Response `HTTP 200`

Response `HTTP 200`

Response `HTTP 200`