Coupon Claim Success Callback

Updated: 2025-07-25 11:25:18

Purpose

With this feature, after a viewer claims a coupon in the live room, the server will notify your custom callback interface by sending a POST request to the configured URL.

Timeout and Retry

If the callback server does not receive a response from your server within 5 seconds after sending the notification, the notification is considered failed. Subsequent failures will be retried 2 more times at 5-second intervals.
The interface returns a JSON object. If the callback does not return a 200 status code, it will be retried 2 times. After 2 failed attempts, the log is discarded.

Callback Message Format

The event callback message is sent to your server via an HTTP/HTTPS POST request, where:

Character encoding format: UTF-8.
Request: The body format is JSON.
Response requirement: The response header must specify Content-Type: application/json.
Correct response: An HTTP status code of 200 indicates successful business processing. Any other status is considered a failure and will be retried.

Callback Parameter Description

Parameter	Type	Description
couponInfo	Object: UserCoupon	Coupon information
receiveInfos	Array: ReceiveInfo	Channel name

UserCoupon Structure

Parameter	Type	Description
couponId	string	Coupon ID
name	string	Coupon name
type	string	Coupon type: MAX_OUT - fixed reduction, DISCOUNT - percentage discount
receiveStartTime	long	Coupon claim start time, 13-digit millisecond timestamp
receiveEndTime	long	Coupon claim end time, 13-digit millisecond timestamp
useTimeType	string	Coupon usage time type: RANGE - time range, DAY - days
dayOfUse	int	Number of days available after claiming
availableAmount	string	Number of coupons issued, greater than or equal to 0
useStartTime	long	Coupon usage start time, 13-digit millisecond timestamp
useEndTime	long	Coupon usage end time, 13-digit millisecond timestamp
rule	Object: UserCouponRule	Coupon rule

UserCouponRule Structure

Parameter	Type	Description
condition	string	Coupon usage condition (UNCONDITIONAL - no threshold, FULL_REDUCE - minimum spend)
unconditional	Object: Unconditional	No threshold
fullReduce	Object: FullReduceBO	Minimum spend
limitPerPerson	int	Maximum number per person: -1 - unlimited

Unconditional Structure

Parameter	Type	Description
enable	boolean	Whether it is available
value	double	Value
unit	string	Unit: MONEY - yuan, DISCOUNT - percentage

FullReduce Structure

Parameter	Type	Description
enable	boolean	Whether it is available
full	double	Minimum spend amount
reduce	double	Reduction amount
unit	string	Unit: MONEY - yuan, DISCOUNT - percentage

ReceiveInfo Structure

Parameter	Type	Description
viewerId	string	Viewer ID
externalViewerId	string	External authorization, external user ID
receiveTime	long	Claim time, 13-digit millisecond timestamp
refId	string	Reference object ID (channel ID, page ID, etc.)
receiveSource	string	Claim source: CHANNEL - channel, AGGREGATE_PAGE - aggregate page, INFO_FLOW - information flow

Response Body:

{
    "couponInfo": {
        "availableAmount": 10,
        "couponId": "dd95z8jtjgwqxkakxxqjk4vlarb5zupi",
        "dayOfUse": 1,
        "name": "优惠券1号",
        "receiveEndTime": 1740585600000,
        "receiveStartTime": 1740538277000,
        "rule": {
            "condition": "UNCONDITIONAL",
            "fullReduce": {
                "enable": false,
                "full": 0.0,
                "reduce": 0.0,
                "unit": "DISCOUNT"
            },
            "limitPerPerson": -1,
            "unconditional": {
                "enable": true,
                "unit": "DISCOUNT",
                "value": 1.0
            }
        },
        "type": "DISCOUNT",
        "useTimeType": "DAY"
    },
    "receiveInfos": [
        {
            "receiveSource": "CHANNEL",
            "receiveTime": 1740540297284,
            "refId": "5461212",
            "viewerId": "d_4z74veo374b5u8c1aubpb8yl3x875xcx",
            "externalViewerId": "externalViewerId1234"
        },
        {
            "receiveSource": "CHANNEL",
            "receiveTime": 1740540296798,
            "refId": "5461212",
            "viewerId": "d_16qa575b49p89pvj0k6267t1t69q2v43"
        },
        {
            "receiveSource": "CHANNEL",
            "receiveTime": 1740540296118,
            "refId": "5461212",
            "viewerId": "d_eh4v9k26ay60qu1umnxb89cv9f64s46k"
        }
    ]
}

How to Configure

Configure via the backend:

Log in to your account - Go to [Cloud Live] - Click [Development Settings] - Click [Callback Settings] - Coupon Claim Success Callback

Note: The submitted interface address must start with http:// or https://.

Live Streaming Server API