Create a billing portal link

POST

/organizations/{organization_id}/subscriptions/billing_portal.json

curl --request POST \
  --url https://secure.ethicsportal.eu/organizations/example/subscriptions/billing_portal.json \
  --header 'Authorization: Bearer <token>'

• EthicsPortal application

Return a Stripe customer portal link where a person changes the plan, updates the payment method, downloads invoices or cancels. The link manages the subscription for whoever holds it until it expires, so treat it like a credential; each link is recorded in the audit trail. A personal token also needs its user to be a current administrator.

Authorizations

• personalToken
  billing:write
• organizationToken
  billing:write

Parameters

Path Parameters

organization_id

required

string

Obfuscated organisation ID returned by identity.

Header Parameters

Idempotency-Key

string

>= 1 characters <= 255 characters /^[\x21-\x7e]+$/

Recommended on every POST. Retrying with the same key and the same request within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice. Only successful responses and validation errors are stored; any other outcome releases the key. Reusing a key with a different request returns 409 idempotency_key_reused; a retry while the first request is still running returns 409 idempotency_key_in_progress. Keys are scoped to the token.

Responses

201

Billing portal link created.

Media typeapplication/json

object

url

required

Stripe-hosted page. Give it to the person who pays or manages billing; it works for whoever holds it until it expires.

string format: uri

expires_at

required

When the link stops working. Null for billing portal links, which expire shortly after creation; create one just before use.

string | null format: date-time

Example

{
  "url": "https://billing.stripe.com/p/session/live_example",
  "expires_at": null
}

400

Invalid body

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: invalid_token forbidden insufficient_scope not_found invalid_request agreement_required rate_limited idempotency_key_reused idempotency_key_in_progress not_retryable channel_inactive invitation_unavailable already_subscribed no_subscription

feedback_url

required

Where to tell EthicsPortal what went wrong: POST product feedback here with the same token.

string format: uri

Example

{
  "error": {
    "code": "invalid_request",
    "feedback_url": "https://secure.ethicsportal.eu/me/feedback.json"
  }
}

401

Missing, unknown, expired or revoked token

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: invalid_token forbidden insufficient_scope not_found invalid_request agreement_required rate_limited idempotency_key_reused idempotency_key_in_progress not_retryable channel_inactive invitation_unavailable already_subscribed no_subscription

feedback_url

required

Where to tell EthicsPortal what went wrong: POST product feedback here with the same token.

string format: uri

Example

{
  "error": {
    "code": "invalid_token",
    "feedback_url": "https://secure.ethicsportal.eu/me/feedback.json"
  }
}

403

The token lacks the required scope (WWW-Authenticate names it), the user’s role does not allow the action, or an agreement must be accepted in the web application

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: invalid_token forbidden insufficient_scope not_found invalid_request agreement_required rate_limited idempotency_key_reused idempotency_key_in_progress not_retryable channel_inactive invitation_unavailable already_subscribed no_subscription

feedback_url

required

Where to tell EthicsPortal what went wrong: POST product feedback here with the same token.

string format: uri

Example

{
  "error": {
    "code": "insufficient_scope",
    "feedback_url": "https://secure.ethicsportal.eu/me/feedback.json"
  }
}

404

Organisation missing or inaccessible, API access suspended, or billing not configured

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: invalid_token forbidden insufficient_scope not_found invalid_request agreement_required rate_limited idempotency_key_reused idempotency_key_in_progress not_retryable channel_inactive invitation_unavailable already_subscribed no_subscription

feedback_url

required

Where to tell EthicsPortal what went wrong: POST product feedback here with the same token.

string format: uri

Example

{
  "error": {
    "code": "not_found",
    "feedback_url": "https://secure.ethicsportal.eu/me/feedback.json"
  }
}

409

The organisation has no Stripe customer yet (create a checkout link first), or an Idempotency-Key conflict (This Idempotency-Key was already used with a different request, or its first request is still running)

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: invalid_token forbidden insufficient_scope not_found invalid_request agreement_required rate_limited idempotency_key_reused idempotency_key_in_progress not_retryable channel_inactive invitation_unavailable already_subscribed no_subscription

feedback_url

required

Where to tell EthicsPortal what went wrong: POST product feedback here with the same token.

string format: uri

Example

{
  "error": {
    "code": "no_subscription",
    "feedback_url": "https://secure.ethicsportal.eu/me/feedback.json"
  }
}

429

Rate limited; retry after the Retry-After interval

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: invalid_token forbidden insufficient_scope not_found invalid_request agreement_required rate_limited idempotency_key_reused idempotency_key_in_progress not_retryable channel_inactive invitation_unavailable already_subscribed no_subscription

feedback_url

required

Where to tell EthicsPortal what went wrong: POST product feedback here with the same token.

string format: uri

Example

{
  "error": {
    "code": "rate_limited",
    "feedback_url": "https://secure.ethicsportal.eu/me/feedback.json"
  }
}