---
title: "Redeem a complimentary-access grant code for the active organization"
method: POST
path: "/v1/plan/redeem"
tags: ["plan"]
---

# Redeem a complimentary-access grant code for the active organization

`POST /v1/plan/redeem`

## Request

- Base URL: `https://postbag.dev`
- URL: `https://postbag.dev/v1/plan/redeem`
- Auth: HTTP bearer

Requires the manage scope (a session is always manage-scoped). A code minted by POST /v1/admin/plan-grants sets plan, plan_source='complimentary', plan_note and — if the grant has a plan_duration_days — plan_expires_at. A paying org (plan_source='billing') cannot redeem (409 plan_is_billing: cancel the subscription first); redeeming a lower tier than the org's current plan is refused (409 plan_not_upgrade).

## Request body

- object
  - `code` string, required: A code minted by POST /v1/admin/plan-grants.

## Response `200`

ok

- PlanRedeemResult
  - `plan` 'free' | 'pro' | 'team' | 'selfhost', required
  - `plan_source` 'free' | 'billing' | 'complimentary' | 'selfhost', required
  - `plan_expires_at` string, nullable, required
  - `plan_note` string, nullable, required
  - `next` object[], required
    - `why` string
    - `method` string
    - `path` string
    - `body` object

## Other responses

- `400`: Error
- `401`: Error
- `403`: Error
- `404`: Not found
- `409`: Error
- `410`: The code is expired, revoked, or fully redeemed
- `422`: Error

---

[API](https://skmtc.dev/postbag/apis/postbag-api.md) · [All operations](https://skmtc.dev/postbag/apis/postbag-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postbag/apis/postbag-api/revisions/3da976524695?raw)