TagMangoTagMango Docs
Subscription

Create Subscription

POST
/api/v1/external/subscriptions

Create a subscription for a user after collecting payment via your external payment gateway. Uses transactionId as idempotency key — safe to retry.

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.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api-prod-new.tagmango.com/api/v1/external/subscriptions" \  -H "x-whitelabel-host: string" \  -H "Content-Type: application/json" \  -d '{    "userId": "62f1f378a7aeb6ce86fae3dd",    "mangoId": "62f1f378a7aeb6ce86fae3dd",    "amount": 999,    "currency": "INR",    "transactionId": "pay_abc123xyz"  }'
{
  "_id": "66a1390268a76f2f5c9f39a3",
  "fan": "66a1390268a76f2f5c9f39a3",
  "creator": "66a1390268a76f2f5c9f39a3",
  "mango": "66a1390268a76f2f5c9f39a3",
  "subscribedAt": "2024-08-11T10:20:30Z",
  "latestSubscriptionDate": "2024-08-11T10:20:30Z",
  "expiredAt": "2024-08-11T10:20:30Z",
  "paymentProvider": "Razorpay",
  "status": "active",
  "orders": [
    "66a1390268a76f2f5c9f39a3",
    "77b2390268a76f2f5c9f39a4"
  ],
  "acquisitionType": "organic",
  "isFree": true,
  "amount": 1000,
  "isLifetime": false,
  "createdAt": "2024-11-04T13:05:43.799Z",
  "updatedAt": "2024-11-04T13:05:43.799Z",
  "order": {
    "_id": "66a1390268a76f2f5c9f39a3",
    "amount": 1000,
    "subscriberCurrency": "INR",
    "status": "PAID",
    "externalTransactionId": "txn_abc123xyz",
    "createdAt": "2024-11-04T13:05:43.799Z",
    "updatedAt": "2024-11-04T13:05:43.799Z"
  },
  "isReactivation": false,
  "alreadyProcessed": false
}
{
  "code": 400,
  "type": "Bad Request",
  "statusMessage": "BAD_REQUEST",
  "errorCode": "INVALID_AMOUNT",
  "message": "The payment amount is negative or zero for a paid mango.",
  "result": "The payment amount is negative or zero for a paid mango.",
  "success": false
}
{
  "code": 401,
  "type": "Unauthorized",
  "statusMessage": "UNAUTHORIZED",
  "message": "Invalid token",
  "success": false
}

{
  "code": 403,
  "type": "Forbidden",
  "statusMessage": "FORBIDDEN",
  "errorCode": "USER_HOST_MISMATCH",
  "message": "The user is registered on a different tagmango account or whitelabel account.",
  "result": "The user is registered on a different tagmango account or whitelabel account.",
  "success": false
}

{
  "code": 404,
  "type": "Not Found",
  "statusMessage": "NOT_FOUND",
  "errorCode": "MANGO_NOT_FOUND",
  "message": "The specified mango does not exist or does not belong to this creator.",
  "result": "The specified mango does not exist or does not belong to this creator.",
  "success": false
}

{
  "code": 409,
  "type": "Conflict",
  "statusMessage": "CONFLICT",
  "errorCode": "DUPLICATE_TRANSACTION",
  "message": "An order with this transactionId already exists for this creator. The original order may be incomplete.",
  "result": "An order with this transactionId already exists for this creator. The original order may be incomplete.",
  "success": false
}

Get Mango Subscriptions Count GET

Get subscription count for each mango or filtered mangoes from query params. - Currently only active and manually active subscriptions from dashboard are counted.

Grant Subscription Access POST

Activate or reactivate an existing subscription without payment. Provide either subscriptionId OR userId + mangoId to identify the subscription. Returns 404 if not found, 409 if already active.