PUT/api/orgs/{org_id}/identities/{identity_id}/customer-plan

Assign a customer plan

A provisioning key may assign only plans an admin delegated to that key; removing a plan (plan_key: null) is dashboard-only. Changes take effect next month unless effective=immediate; counters carry across revisions. Fenced by expected_revision (409 when stale).

認証: AuthorizationヘッダーにBearer形式のAPIキー

パスパラメータ

  • org_idstring必須

    Your organization id (uuid). GET /api/whoami returns it.

  • identity_idstring必須

    Identity id.

リクエストボディ

  • plan_keystring | null必須

    Null removes the plan (session admins only).

  • plan_versioninteger | null必須

    Set together with plan_key, or both null.

  • expected_revisioninteger必須

    The assignment's current revision (0 when none).

  • effectiveenum
    "next_month""immediate"
    デフォルト: "next_month"
  • budget_periodobject | null

    Omit to keep the current period. Changing it needs a plan and effective=immediate.

レスポンス

  • 200

    The assignment.

    レスポンス
    • org_idstring必須
    • identity_idstring必須
    • revisioninteger必須

      Pass as expected_revision on the next PUT.

    • plan_keystring | null必須
    • plan_versioninteger | null必須
    • pending_plan_keystring | null必須
    • pending_plan_versioninteger | null必須
    • pending_effective_atstring | null必須
    • updated_atstring必須
    • budget_periodobject
      いずれか

      object

      • kindstring必須

      object

      • kindstring必須
      • source_period_idstring必須
      • startstring必須
      • endstring必須
  • 401

    Missing, unknown or revoked API key.

    レスポンス
    • errorstring必須

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 403

    Not authorized for this policy change, or a customer-plan key.

    レスポンス
    • errorstring必須

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 404

    Unknown organization, identity or plan.

    レスポンス
    • errorstring必須

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 409

    Stale expected_revision, or customer-plan enforcement is off on this deployment.

    レスポンス
    • errorstring必須

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 422

    Body validation failed, or the policy is invalid.

リクエスト

curl -X PUT https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/identities/acme-support/customer-plan \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "plan_key": "starter",
  "plan_version": 2,
  "expected_revision": 3,
  "effective": "next_month"
}'

レスポンス

{
  "org_id": "3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10",
  "identity_id": "acme-support",
  "revision": 4,
  "plan_key": "starter",
  "plan_version": 2,
  "pending_plan_key": "starter",
  "pending_plan_version": 2,
  "pending_effective_at": "2026-12-01T00:00:00Z",
  "updated_at": "2026-11-10T16:00:00Z",
  "budget_period": {
    "kind": "calendar_month_utc"
  }
}

https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/identities/acme-support/customer-plan