Manage discount codes with API and MCP

Site administrators can create, list, inspect, edit, and deactivate single-use subscription discount codes through REST or MCP. The same validation and audit records apply as in Site Admin → Discounts.

OAuth MCP calls use your signed-in site-admin identity. A paired local gateway uses its owner's identity. For REST or API-key MCP, create a key in Settings → API Keys with Manage discount codes across Pencil enabled. Only site admins can grant this permission; existing keys do not inherit it. Read keys can inspect offers; write keys can create and deactivate them. MCP keys also need MCP access enabled. Revoking the key or removing its creator's site-admin or organization-admin access stops discount management.

The MCP tools are list_discount_codes, get_discount_code, create_discount_code, update_discount_code, and deactivate_discount_code. Use the code itself when inspecting or deactivating an offer. List returns at most 100 offers per page and a nextCursor. Get includes the redemption and ten most recent audit events.

Create an offer with code, label, percentOff, duration (once, repeating, or forever), and planKey (pro or team). For repeating, provide months (1–36). Optional redeemBy is a future timestamp in milliseconds. Omit both recipient fields to let anyone holding the code redeem it once; optionally supply one of targetUserId or targetOrgId to restrict it.

For a 50% Pro monthly discount lasting 12 months:

{"code":"PILOT50","label":"Pilot offer","percentOff":50,"duration":"repeating","months":12,"planKey":"pro"}

REST uses GET /api/v1/discount-codes, POST /api/v1/discount-codes, GET /api/v1/discount-codes/{code}, PATCH /api/v1/discount-codes/{code}, and POST /api/v1/discount-codes/{code}/deactivate. Authenticate with a bearer API key. Responses use the usual {data} envelope; consult the OpenAPI reference for the complete contract.

Creation returns the normalized code. Share https://app.pencil.ink/sign-up?discountCode=CODE with the recipient. Each code is single-use across organizations. Discounts cover eligible USD monthly base subscriptions; AI usage is separate. Creation does not enable the global redemption switch or perform a Stripe operation. Verify enabled from the list response and billing rollout readiness before promising redemption.

Before redemption starts, choose Edit code in Site Admin → Discounts to change the label, percentage, plan, duration/months, or redemption deadline. The same code and signup link remain valid. The code text and recipient cannot be changed. Save records before/after terms in the audit history.

To change an ongoing offer to twelve months, call update_discount_code with {"code":"PILOT50","duration":"repeating","months":12}, or PATCH its REST resource with {"duration":"repeating","months":12}. Omitted fields are preserved; redeemBy: null clears the deadline. Identical updates do not add duplicate audit events.

Any redemption history (pending, applied, or removed) locks terms. This prevents a concurrent checkout from applying stale Stripe coupon terms. Changing an already-claimed offer requires a new code; editing does not modify existing Stripe subscriptions. Deactivation preserves already-applied discounts and refuses pending redemptions until their Stripe sessions are reconciled. Repeated deactivation is safe. Creation rejects duplicate codes: after an uncertain response, inspect the code before retrying; never automatically generate a different code.