Segments

Segments are member tiers — the equivalent of "Free", "Pro", "Founding Member", "Annual Supporter" depending on your model. A segment can have a public form (members submit it to apply), pricing (monthly / quarterly / yearly / one-time / installment), and an active flag.

Configuration reference. This page is the REST endpoints reference. For the complete tier configuration model — every supported billing cycle, how to mix them on a single tier, currencies, commissions, founding rates — see Memberships.

Public-read endpoints (READ_PUBLIC) — list segments, fetch form schema, check email. Write endpoints — submit form (WRITE_MEMBERS), accept rules (WRITE_MEMBERS), patch a segment (ADMIN).

Base URL: https://api.cobuntu.com/api/v1

Every endpoint requires an X-API-Key header. See Authentication for scope details.

`GET` `/communities/{communityTag}/segments/public` — List public segments (tiers)

Scope: READ_PUBLIC

Path parameters:

Param	Type	Description
`communityTag`	`string`	Your community's tag (e.g. `your-community`, `acme`).

Response (200):

[
  {
    "id": "…",
    "name": "…",
    "description": "…",                          // nullable
    "color": "…",
    "hasForm": false,
    "currency": "EUR",
    "priceMonthly": 0,                           // nullable
    "priceQuarterly": 0,                         // nullable
    "priceYearly": 0,                            // nullable
    "priceOneTime": 0,                           // nullable
    "installmentTotalPrice": 0,                  // nullable
    "installmentCount": 0,                       // nullable
    "installmentIntervalMonths": 0,              // nullable
    "accessDurationMonths": 0,                   // nullable
    "installmentRenewsAnnually": false,
    "foundingPriceMonthly": 0,                   // nullable
    "foundingPriceQuarterly": 0,                 // nullable
    "foundingPriceYearly": 0,                    // nullable
    "foundingMemberCap": 0,                      // nullable
    "foundingMemberCount": 0
  }
]

Field	Type	Description
`id`	`string`	Stable segment identifier (uuid).
`name`	`string`	Display name (e.g. `Free`, `Pro`, `Founding Member`).
`description`	`string` (nullable)	Long-form description shown on the segment's apply page.
`color`	`string`	Display color, hex.
`hasForm`	`boolean`	True if the segment requires submitting a form to join (use `GET /segments/{segmentId}/form`).
`currency`	`string`	ISO-4217 code. See Memberships → Currencies for the supported list.
`priceMonthly`	`integer` (nullable)	Monthly price in cents (null = not offered monthly).
`priceQuarterly`	`integer` (nullable)	Quarterly price in cents (null = not offered quarterly).
`priceYearly`	`integer` (nullable)	Yearly price in cents (null = not offered yearly).
`priceOneTime`	`integer` (nullable)	One-time price in cents (null = not offered as a single charge). Access lasts `accessDurationMonths` then expires.
`installmentTotalPrice`	`integer` (nullable)	Total amount the buyer commits to across `installmentCount` charges. Null = installment plan not offered.
`installmentCount`	`integer` (nullable)	How many charges (e.g. 3).
`installmentIntervalMonths`	`integer` (nullable)	Months between installment charges (typically 1).
`accessDurationMonths`	`integer` (nullable)	How long access lasts from signup (typically 12).
`installmentRenewsAnnually`	`boolean`	When true + an installment plan is set, the N-charge cycle repeats every `accessDurationMonths`. False = single-cycle.
`foundingPriceMonthly` / `Quarterly` / `Yearly`	`integer` (nullable)	Founding-member discount prices. Used in place of the regular price until `foundingMemberCap` is reached.
`foundingMemberCap`	`integer` (nullable)	Max members eligible for the founding rate. Null = no cap.
`foundingMemberCount`	`integer`	Current count of founding-rate members (drives the "N spots left" UI).

Configuration model + buyer-experience matrix lives in Memberships.

Example:

curl https://api.cobuntu.com/api/v1/communities/my-community/segments/public \
  -H "X-API-Key: pk_live_..."

`GET` `/communities/{communityTag}/segments/{segmentId}/check-email` — Check whether an email is already registered for this segment

Scope: READ_PUBLIC

Path parameters:

Param	Type	Description
`communityTag`	`string`	Your community's tag (e.g. `your-community`, `acme`).
`segmentId`	`string`	Segment identifier from `GET /segments/public`.

Query parameters:

Param	Type	Default	Description
`email`	`string`		Email address (RFC 5322).

Response (200):

{
  "exists": false,
  "status": "…",
}

Field	Type	Description
`exists`	`boolean`
`status`	`string`

Example:

curl https://api.cobuntu.com/api/v1/communities/my-community/segments/EXAMPLE_ID/check-email \
  -H "X-API-Key: pk_live_..."

`GET` `/communities/{communityTag}/segments/{segmentId}/form` — Get the segment's form schema

Scope: READ_PUBLIC

Path parameters:

Param	Type	Description
`communityTag`	`string`	Your community's tag (e.g. `your-community`, `acme`).
`segmentId`	`string`	Segment identifier from `GET /segments/public`.

Response (200):

{
  "segmentId": "…",
  "schema": […],
}

Field	Type	Description
`segmentId`	`string`
`schema`	`array`

Example:

curl https://api.cobuntu.com/api/v1/communities/my-community/segments/EXAMPLE_ID/form \
  -H "X-API-Key: pk_live_..."

`POST` `/communities/{communityTag}/rules/accept` — Accept the community rules (per visitor / on first member action)

Scope: WRITE_MEMBERS

Path parameters:

Param	Type	Description
`communityTag`	`string`	Your community's tag (e.g. `your-community`, `acme`).

Request body:

{
  "rulesVersion": 0,
}

Field	Type	Description
`rulesVersion`	`integer`	Integer version of the rules document the visitor accepted. Get the current version from the community's storefront config.

Response (200):

{
  "ok": false,
}

Field	Type	Description
`ok`	`boolean`	Always `true` on a 200 response.

Example:

curl -X POST \
  https://api.cobuntu.com/api/v1/communities/my-community/rules/accept \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'

`PATCH` `/communities/{communityTag}/segments/{segmentId}` — Update a segment (name / pricing / active)

Scope: ADMIN

Path parameters:

Param	Type	Description
`communityTag`	`string`	Your community's tag (e.g. `your-community`, `acme`).
`segmentId`	`string`	Segment identifier from `GET /segments/public`.

Request body:

{
  "name": "…",
  "priceMonthly": 0,                   // nullable
  "priceQuarterly": 0,                 // nullable
  "priceYearly": 0,                    // nullable
  "priceOneTime": 0,                   // nullable
  "installmentTotalPrice": 0,          // nullable
  "installmentCount": 0,               // nullable
  "installmentIntervalMonths": 0,      // nullable
  "accessDurationMonths": 0,           // nullable
  "installmentRenewsAnnually": false,
  "isActive": false
}

Field	Type	Description
`name`	`string`	New display name. Preserves the segment's id and existing memberships.
`priceMonthly`	`integer` (nullable)	New monthly price in cents. Null disables monthly. Existing subscribers keep their current billing until renewal.
`priceQuarterly`	`integer` (nullable)	New quarterly price in cents. Null disables quarterly.
`priceYearly`	`integer` (nullable)	New yearly price in cents. Null disables yearly.
`priceOneTime`	`integer` (nullable)	One-time price in cents. Null disables the one-time offer.
`installmentTotalPrice`	`integer` (nullable)	Total committed across `installmentCount` charges. All four installment fields are a unit — set all or none.
`installmentCount`	`integer` (nullable)	How many charges.
`installmentIntervalMonths`	`integer` (nullable)	Months between charges.
`accessDurationMonths`	`integer` (nullable)	How long access lasts after signup. Also the renewal anchor when `installmentRenewsAnnually = true`.
`installmentRenewsAnnually`	`boolean`	Repeats the installment cycle every `accessDurationMonths`. Ignored if no installment plan is configured.
`isActive`	`boolean`	False = closed to new members (existing memberships unaffected). True = open for new applications.

Response (200): same shape as GET /segments/public (see above).

Example:

curl -X PATCH \
  https://api.cobuntu.com/api/v1/communities/my-community/segments/EXAMPLE_ID \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'

`POST` `/communities/{communityTag}/segments/{segmentId}/submit` — Submit the segment's form (= apply for membership)

Scope: WRITE_MEMBERS

Path parameters:

Param	Type	Description
`communityTag`	`string`	Your community's tag (e.g. `your-community`, `acme`).
`segmentId`	`string`	Segment identifier from `GET /segments/public`.

Request body:

{
  "answers": { "<fieldId>": "…", "email": "buyer@example.com", "name": "Jane" },
  "source": "community_app",
  "billingCycle": "ONE_TIME"
}

Field	Type	Description
`answers`	`object`	Form answers keyed by field id. Must match the segment's form schema (`GET /segments/{segmentId}/form`). `email` and `name` are extracted from `answers` — the form's EMAIL field and the SHORT_TEXT field whose label contains "name" are required.
`source`	`string` (optional)	Free-form attribution (e.g. `"community_app"`, `"landing_page"`, `"linktree"`). Persisted on the membership_request and exposed in the `member.requested` webhook.
`billingCycle`	`string (enum)` (optional)	One of `MONTHLY`, `QUARTERLY`, `YEARLY`, `ONE_TIME`, `INSTALLMENT_PLAN`. Required when the tier exposes more than one billing cycle (returns 400 otherwise). Optional / can be omitted when the tier has exactly one cycle configured (server resolves it). See Memberships → Mixing payment styles.

Response (201) — free-tier auto-approve path:

{
  "success": true,
  "requestId": "…",
  "requestStatus": "APPROVED",
  "segmentName": "Free",
  "segmentId": "…"
}

Response (201) — paid-tier path (PAYMENT_PENDING):

{
  "success": true,
  "requestId": "…",
  "paymentRequired": true,
  "segmentId": "…",
  "segmentName": "Membro 3x"
}

When paymentRequired: true, the integrator must chain a call to POST /communities/{tag}/apply/checkout with the requestId to obtain the Stripe Checkout URL.

Field	Type	Description
`success`	`boolean`	Always `true` on a 201 response.
`requestId`	`string`	Stable id for the membership request. Carried in the `member.requested` webhook payload and required for the downstream paid-checkout call.
`requestStatus`	`string (enum)` (free path)	`APPROVED` for auto-approve segments (OPEN + LIVE community), else `PENDING` for admin review.
`paymentRequired`	`boolean` (paid path)	`true` when the tier is paid and the buyer must complete Stripe Checkout to finalize.
`segmentId`	`string`	Echo of the path parameter.
`segmentName`	`string`	Display name (useful for `"Welcome to {segmentName}"` confirmation copy).

Error responses:

Code	When
`400` `ALREADY_MEMBER`	The email already has an `ACCEPTED` membership in this community.
`400` `APPLICATION_PENDING`	The email has a pending application — wait for admin review or pay outstanding.
`400` generic	Missing required form fields, invalid billingCycle for this tier, tier sold out, etc.

Example:

curl -X POST \
  https://api.cobuntu.com/api/v1/communities/my-community/segments/EXAMPLE_ID/submit \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'

`POST` `/communities/{communityTag}/apply/checkout` — Create Stripe Checkout for a PAYMENT_PENDING application

Scope: WRITE_MEMBERS

Issues a Stripe Checkout URL for a PAYMENT_PENDING membership request created by POST /segments/{segmentId}/submit. The session shape (subscription vs payment mode, recurring interval, cancel_at) is resolved server-side from the request's persisted billingCycle.

Path parameters:

Param	Type	Description
`communityTag`	`string`	Your community's tag.

Request body:

{
  "requestId": "…",
  "origin": "https://my-community.com"
}

Field	Type	Description
`requestId`	`string`	The `requestId` returned from the prior `/segments/{segmentId}/submit` call. Must reference a row in `PAYMENT_PENDING` status.
`origin`	`string` (optional)	Browser origin used to build the success / cancel URLs. Defaults to `APP_BASE_URL` if omitted.

Response (200):

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_…",
  "sessionId": "cs_test_…"
}

Field	Type	Description
`checkoutUrl`	`string`	Redirect the buyer's browser here.
`sessionId`	`string`	Stripe Checkout session id.

Error responses:

Code	When
`400`	`requestId` is not in `PAYMENT_PENDING` status (already paid, never created, etc.).
`400`	Tier has no price configured for the requested `billingCycle`.

Example:

curl -X POST \
  https://api.cobuntu.com/api/v1/communities/my-community/apply/checkout \
  -H "X-API-Key: pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "requestId": "abc-123", "origin": "https://my-community.com" }'

Products Errors

Segments

GET /communities/{communityTag}/segments/public — List public segments (tiers)

GET /communities/{communityTag}/segments/{segmentId}/check-email — Check whether an email is already registered for this segment

GET /communities/{communityTag}/segments/{segmentId}/form — Get the segment's form schema

POST /communities/{communityTag}/rules/accept — Accept the community rules (per visitor / on first member action)

PATCH /communities/{communityTag}/segments/{segmentId} — Update a segment (name / pricing / active)

POST /communities/{communityTag}/segments/{segmentId}/submit — Submit the segment's form (= apply for membership)

POST /communities/{communityTag}/apply/checkout — Create Stripe Checkout for a PAYMENT_PENDING application

`GET` `/communities/{communityTag}/segments/public` — List public segments (tiers)

`GET` `/communities/{communityTag}/segments/{segmentId}/check-email` — Check whether an email is already registered for this segment

`GET` `/communities/{communityTag}/segments/{segmentId}/form` — Get the segment's form schema

`POST` `/communities/{communityTag}/rules/accept` — Accept the community rules (per visitor / on first member action)

`PATCH` `/communities/{communityTag}/segments/{segmentId}` — Update a segment (name / pricing / active)

`POST` `/communities/{communityTag}/segments/{segmentId}/submit` — Submit the segment's form (= apply for membership)

`POST` `/communities/{communityTag}/apply/checkout` — Create Stripe Checkout for a PAYMENT_PENDING application