Hanzo
OpenapiMarketing

Records the caller org's claim on a promo.

Records the caller org's claim on a promo.

POST /v1/marketing/promos/{code}/redeem

Addresshttps://api.hanzo.ai/v1/marketing/promos/{code}/redeem
MethodPOST
Operationpost_marketing_promos_by_code_redeem
AuthAuthorization: Bearer $HANZO_API_KEY

Records the caller org's claim on a promo. NOTHING IS CREDITED: the redemption is a row, and credit into an org is an admin decision made on the admin surface against an auditable ledger.

The plan is DERIVED from the org's live ACTIVE/TRIALING paid subscription and can never be named by the caller — an org with no qualifying subscription is refused, and so is one whose subscription cannot be read. The seat count is the single-seat floor (claimSeats), so the recorded figure has no input that can inflate it.

Guards run under one lock so the cap cannot be raced past: the fleet-wide redemption cap, one redemption per org, one per payment instrument (REQUIRED), and the per-redemption ceiling.

It is IDEMPOTENT: an org that already redeemed gets its original redemption back with alreadyRedeemed true.

Request

3 fields, body application/json (required).

FieldInTypeRequiredDescription
codepathstringyesCode is the promo code from the path.
codebodystringCode is the promo code from the path.
instrumentbodystringInstrument identifies the payment method. It is the anti-farming key: one redemption per instrument, fleet-wide, and it is REQUIRED — an absent instrument is…

Response

StatusBodyMeaning
200RedeemResultok

200 body — 9 fields.

FieldInTypeAlwaysDescription
alreadyRedeemedbodybooleanAlreadyRedeemed is true when this org had already taken the promo and the call was an idempotent replay.
chargeCentsbodyintegerChargeCents is what month one costs after the discount, DiscountCents the discount that produced it.
discountCentsbodyintegerDiscountCents is the discount claimed for month one, in USD cents, at the single-seat floor.
redemptionbodyRedemption
redemption.codebodystringCode is the promo redeemed.
redemption.discountCentsbodyintegerDiscountCents is the month-one discount this redemption CLAIMS, in USD cents. It is a recorded figure, NOT a balance: nothing was credited and no wallet moved.
redemption.planbodystringPlan is the tier redeemed against: pro, max or team.
redemption.redeemedAtbodyintegerRedeemedAt is unix seconds.
redemption.seatsbodyintegerSeats is the seat count the claim was priced at, and it is ALWAYS 1.

Failure carries the platform error shape — see Errors.

Examples

hanzo marketing promos redeem <code>

Marketing API · All Hanzo APIs · Interactive reference

How is this guide?

On this page