Create a subscription checkout link

POST

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

const url = 'https://secure.ethicsportal.eu/organizations/example/subscriptions/checkout.json';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"subscription":{"interval":"year"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://secure.ethicsportal.eu/organizations/example/subscriptions/checkout.json \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "subscription": { "interval": "year" } }'

Return a Stripe Checkout link for the monthly or yearly plan. A person opens it and pays; Stripe handles strong customer authentication, tax and VAT ID collection. Access starts when Stripe confirms the payment, whether or not the payer is signed in to EthicsPortal. Send an Idempotency-Key so a retry returns the same link. 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.

Request Body^required

application/json

object

subscription

required

object

interval

required

string

Allowed values: month year

Example

{
  "subscription": {
    "interval": "year"
  }
}

Responses

201

Checkout link created.

application/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://checkout.stripe.com/c/pay/cs_live_example",
  "expires_at": "2026-11-10T10:00:00Z"
}

400

Invalid body

application/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

application/json

object

error

required

object

code

required

string

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

application/json

object

error

required

object

code

required

string

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

application/json

object

error

required

object

code

required

string

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 already has a subscription (use the billing portal link), or an Idempotency-Key conflict (This Idempotency-Key was already used with a different request, or its first request is still running)

application/json

object

error

required

object

code

required

string

feedback_url

required

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

string format: uri

Example

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

422

Unknown interval

application/json

object

error

required

object

code

required

Allowed value: validation_failed

fields

required

Array<string>

>= 1 items unique items

feedback_url

required

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

string format: uri

Example

{
  "error": {
    "code": "validation_failed",
    "fields": [
      "interval"
    ],
    "feedback_url": "https://secure.ethicsportal.eu/me/feedback.json"
  }
}

429

Rate limited; retry after the Retry-After interval

application/json

object

error

required

object

code

required

string

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"
  }
}

Create a subscription checkout link

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Example

Responses

201

Example

400

Example

401

Example

403

Example

404

Example

409

Example

422

Example

429

Example

Request Body^required