Payments

The Payments API manages your merchant catalog: the subscription Plans and Taxes you sell. Plans define the pricing tiers available to your tenants, and taxes are applied per country.

To work with a workspace’s live subscription (reading its state, selecting or changing a plan, running the cancel/reactivate/trial lifecycle, and reading entitlements), see Subscriptions & Entitlements.

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

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

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`