TagMango Documentation

Create a discount coupon (promo code) — at least one of flatDiscount or percentageDiscount off, redeemable on one or more of the creator's mangoes, or creator-wide when no mango is given. If both discount fields are given, percentageDiscount takes priority and flatDiscount is ignored entirely. Mirrors the dashboard "create coupon" flow, including the checks the dashboard form itself relies on the browser for: a mango a coupon is attached to must be one-time-priced (a free, zero-cost, open-ended, or recurring mango is rejected); without the 100%-discount plan entitlement, the discount is capped at 80%; startAt/validTill are full date-times (not bare dates) and validTill must be at least 5 minutes after startAt by actual elapsed time — see those fields' own descriptions for the exact precision required; targetUsers requires targetMangoes; and every targetUsers id must have an active subscription to one of the targetMangoes. The coupon is always created in your own account's currency (there is no currency field to set) — every selected mango must already be priced in that same currency. code must be unique among your own existing coupons, and is stored uppercase (lookups are case-insensitive).

Authorization

bearer

AuthorizationBearer <token>

In: header

Header Parameters

x-whitelabel-host*string

Host name of the dashboard, ex: mydomain.tagmango.com

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

code*string

The coupon code fans enter at checkout. Whitespace is stripped and it's stored uppercase (lookups are case-insensitive). Must be unique among your own existing coupons, at least 4 characters, and may only contain letters, digits, spaces, _, and -.

mangoes?array<>

Mango ids this coupon can be redeemed on. Omit for a creator-wide coupon not scoped to any specific mango. Every mango given must belong to this creator, and must be one-time-priced — a free, zero-cost, open-ended, or recurring (subscription) mango can never redeem a coupon, so one cannot be attached to it. Determines the coupon's type in the response — given here, mango_coupon; omitted, creator_discount_coupon — this is derived automatically and cannot be set directly.

startAt*string

When the coupon becomes redeemable. A full ISO 8601 date-time — YYYY-MM-DDTHH:mm:ss.sssZ — not a bare date; the time-of-day matters, control is at minute precision. May be in the past (opens the coupon immediately).

Formatdate-time

validTill*string

When the coupon expires. Same full ISO 8601 date-time format as startAt. Must be after the current time, AND at least 5 minutes after startAt — e.g. startAt at 10:00:00Z requires validTill at 10:05:00Z or later; 10:03:00Z is rejected even though it is "after" startAt. If you only have a target day in mind, pick any time-of-day at least 5 minutes apart on the two dates — the rule checks the actual elapsed time between the two timestamps, not calendar days.

Formatdate-time

active?boolean

Whether the coupon is active as soon as it is created.

Defaulttrue

flatDiscount?number

Flat amount off, in your account's own currency. Must be greater than 0. Give at least one of this or percentageDiscount. If both are given, percentageDiscount takes priority and this value is ignored entirely — not stored, not checked against the plan cap below. Without the 100%-discount plan entitlement, this is capped at 80% of the cheapest selected mangoes price — with it, at that price in full. The price cap is not checked when no mangoes are given.

percentageDiscount?number

Percentage off, greater than 0 and at most 100. Give at least one of this or flatDiscount. If both are given, this one takes priority and flatDiscount is ignored. Without the 100%-discount plan entitlement, this is capped at 80%.

remainingOrder?number

How many times this coupon can be redeemed in total. Omit for unlimited redemptions. The stored value decrements by 1 automatically on every successful redemption — this is the starting count, not re-derived from anything else later.

targetMangoes?array<>

Restricts redemption to fans with an active subscription to one of these mangoes (independent of mangoes — this is a redemption-eligibility gate, not what the discount applies to). Unlike mangoes, a free or subscription mango is a valid choice here — it just needs to belong to you.

targetUsers?array<>

Restricts redemption to this explicit allow-list of user ids. Only meaningful alongside targetMangoes — it narrows that scope further, so it is rejected if targetMangoes is not also given. Every user id given must have an active subscription to at least one of the given targetMangoes.

Response Body

`application/json`

curl -X POST "https://api-prod-new.tagmango.com/api/v1/external/coupons" \  -H "x-whitelabel-host: string" \  -H "Content-Type: application/json" \  -d '{    "code": "WELCOME50",    "startAt": "2026-01-28T07:47:29.862Z",    "validTill": "2026-02-28T07:47:29.862Z"  }'

{
  "_id": "66a1390268a76f2f5c9f39a3",
  "code": "WELCOME50",
  "type": "creator_discount_coupon",
  "creator": "77b2390268a76f2f5c9f39a4",
  "startAt": "2024-08-11T10:20:30Z",
  "validTill": "2024-12-31T23:59:59Z",
  "active": true,
  "flatDiscount": 100,
  "percentageDiscount": 10,
  "remainingOrder": 50,
  "totalUsage": 5,
  "currency": "INR",
  "createdAt": "2024-08-11T10:20:30Z",
  "updatedAt": "2024-08-11T10:20:30Z",
  "mangoes": [
    "64fbc8d765c6e5b324d45678"
  ],
  "targetMangoes": [
    "64fbc8d765c6e5b324d45678"
  ],
  "targetUsers": [
    "64fbc8d765c6e5b324d67890"
  ]
}

{
  "code": 400,
  "type": "Bad Request",
  "statusMessage": "BAD_REQUEST",
  "errorCode": "COUPON_MANGO_NOT_ELIGIBLE",
  "message": "A coupon can only target a one-time-priced mango — free, zero-cost, open-ended, and recurring (subscription) mangoes can never redeem a coupon, so one cannot be created for them.",
  "result": "A coupon can only target a one-time-priced mango — free, zero-cost, open-ended, and recurring (subscription) mangoes can never redeem a coupon, so one cannot be created for them.",
  "success": false
}

{
  "code": 401,
  "type": "Unauthorized",
  "statusMessage": "UNAUTHORIZED",
  "message": "Invalid token",
  "result": "Invalid token",
  "success": false
}

{
  "code": 403,
  "type": "Forbidden",
  "statusMessage": "FORBIDDEN",
  "errorCode": "COUPON_CREATOR_NOT_FOUND",
  "message": "The creator associated with the API key does not exist.",
  "result": "The creator associated with the API key does not exist.",
  "success": false
}

{
  "code": 404,
  "type": "Not Found",
  "statusMessage": "NOT_FOUND",
  "errorCode": "COUPON_MANGOES_NOT_FOUND",
  "message": "One or more mango IDs in the request do not exist or have been deleted.",
  "result": "One or more mango IDs in the request do not exist or have been deleted.",
  "success": false
}

{
  "code": 409,
  "type": "Conflict",
  "statusMessage": "CONFLICT",
  "errorCode": "COUPON_CODE_ALREADY_EXISTS",
  "message": "Coupon codes must be unique among your own existing coupons (case-insensitive). Choose a different `code`.",
  "result": "Coupon codes must be unique among your own existing coupons (case-insensitive). Choose a different `code`.",
  "success": false
}

{
  "code": 429,
  "type": "Too Many Requests",
  "statusMessage": "TOO_MANY_REQUESTS",
  "message": "Request limit exceeded. try after 10 seconds",
  "result": "Request limit exceeded. try after 10 seconds",
  "success": false
}

Create Coupon

Authorization

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

429application/json

COUPON_MANGO_NOT_ELIGIBLE

COUPON_INVALID_PERCENTAGE_DISCOUNT

COUPON_DISCOUNT_AMOUNT_INVALID

COUPON_CURRENCY_MISMATCH

COUPON_INVALID_DATE_RANGE

COUPON_TARGET_USERS_REQUIRE_TARGET_MANGOES

COUPON_TARGET_USER_NOT_SUBSCRIBED

COUPON_CREATOR_NOT_FOUND

COUPON_MANGOES_FORBIDDEN

COUPON_TARGET_MANGOES_FORBIDDEN

COUPON_DISCOUNT_CAP_EXCEEDED

COUPON_MANGOES_NOT_FOUND

COUPON_TARGET_MANGOES_NOT_FOUND

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`