TagMango Documentation

Process a refund for an externally created order. Use action "initiate" to start a refund (halts subscription, sends notifications), then "complete" after processing on your payment gateway.

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.

action*string

Action to perform: "initiate" to start a refund, "complete" to confirm it

Value in"initiate" | "complete"

transactionId?string

The transaction ID used when creating the subscription. Provide this OR orderId.

orderId?string

The order id for the subscription . Provide this OR transactionId.

amount?number

Refund amount. If not provided, defaults to full remaining refundable amount. For partial refunds, specify the amount to refund.

currency?string

Currency of the refund amount. Defaults to the order's payment currency (in which user paid during transaction).

Value in"USD" | "INR" | "EUR"

refundTransactionId?string

Your payment gateway refund transaction ID — stored for reconciliation. Relevant for the "complete" action. If not provided a random id will be created as refund ID

refundNotes?string

Notes about the refund or additional information regarding refund action

Response Body

`application/json`

curl -X POST "https://api-prod-new.tagmango.com/api/v1/external/subscriptions/refund" \  -H "x-whitelabel-host: string" \  -H "Content-Type: application/json" \  -d '{    "action": "initiate"  }'

{
  "_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"
  }
}

{
  "code": 400,
  "type": "Bad Request",
  "statusMessage": "BAD_REQUEST",
  "errorCode": "ORDER_NOT_SUPPORTED",
  "message": "The order was created through an internal payment provider. Only support orders created via external API endpoint",
  "result": "The order was created through an internal payment provider. Only support orders created via external API endpoint",
  "success": false
}

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

{
  "code": 404,
  "type": "Not Found",
  "statusMessage": "NOT_FOUND",
  "errorCode": "ORDER_NOT_FOUND",
  "message": "Order does not exist for requested creator",
  "result": "Order does not exist for requested creator",
  "success": false
}

{
  "code": 409,
  "type": "Conflict",
  "statusMessage": "CONFLICT",
  "errorCode": "REFUND_ALREADY_COMPLETED",
  "message": "This order has already been fully refunded. No further refunds can be processed.",
  "result": "This order has already been fully refunded. No further refunds can be processed.",
  "success": false
}

Refund Subscription

Authorization

Header Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

404application/json

409application/json

ORDER_NOT_SUPPORTED

REFUND_NOT_ELIGIBLE

REFUND_AMOUNT_EXCEEDS_ORDER

ORDER_NOT_FOUND

SUBSCRIPTION_NOT_FOUND

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`