`GET /api/marketplace/items/{id}/subscription` — #1111: the live subscription license the ACTIVE WORKSPACE holds for this item, or `null`.

GET

/api/marketplace/items/{id}/subscription

const url = 'https://example.com/api/marketplace/items/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/subscription';
const options = {method: 'GET', headers: {cookie: 'supacloud_session=<supacloud_session>'}};

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

curl --request GET \
  --url https://example.com/api/marketplace/items/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/subscription \
  --cookie supacloud_session=<supacloud_session>

Workspace-scoped rather than user-scoped on purpose: the entitlement is the workspace’s, so a colleague of the original buyer sees (and can end) the same subscription they are both using.

Authorizations

cookie_auth

Parameters

Path Parameters

required

string format: uuid

Responses

200

application/json

One of:

null
object

null

A purchase record tying a buyer (user + workspace) to a specific item version via a price row. All monetary amounts are in minor units (cents). fee_policy_snapshot captures the fee settings at purchase time for audit.

object

amount_minor

required

integer format: int32

buyer_user_id

required

string format: uuid

buyer_workspace_id

required

string format: uuid

cancel_at_period_end

required

boolean

canceled_at

string | null format: date-time

created_at

required

string format: date-time

currency

required

string

current_period_end

Stripe’s truth: the end of the period that is currently paid for.

string | null format: date-time

disputed_at

string | null format: date-time

fee_policy_snapshot

required

string format: uuid

item_version_id

required

string format: uuid

license_expires_at

The single enforcement instant the license gate reads. None = perpetual (a one-time purchase). See migration 350 for why it is derived from current_period_end plus the grace window rather than equal to it.

string | null format: date-time

platform_fee_minor

required

integer format: int32

price_id

required

string format: uuid

provider_checkout_id

string | null

provider_fee_minor

required

integer format: int32

provider_payment_id

string | null

provider_subscription_id

The Stripe subscription (sub_...) this license is driven by. Also the routing key that CLAIMS an invoice.* / customer.subscription.* event for the marketplace instead of org billing.

string | null

purchased_at

string | null format: date-time

refunded_at

string | null format: date-time

seller_profile_id

required

string format: uuid

status

required

Purchase lifecycle status (marketplace_purchases.status CHECK). Runtime stays String; the spec narrows it to the closed [PurchaseStatusSpec].

string

Allowed values: pending active refunded partially_refunded disputed revoked past_due suspended canceled

updated_at

required

string format: date-time

Example

{
  "status": "pending"
}

401

Authentication required

application/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden license_required license_expired bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited too_many_requests quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null
object

null

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

404

Item not found

application/json

object

code

required

Machine-readable, stable error code.

string

details

One of:

null
object

null

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

500

Structured server error

application/json

object

code

required

Machine-readable, stable error code.

string

details

One of:

null
object

null

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}