syncBenefit

2023-04-28 21:00

POST /v1/marketing/benefit/sync

With this API call, an Independent Service Vendor (ISV) can synchronize one type of benefit to our server. Then our server processes the benefit internally and synchronizes it to the super app. After that, the super app releases the benefit manually for users to access.

Note:
Do not synchronize the benefit in draft status to our server because once synchronized, it is regarded as the final benefit and can be accessed by users.
The following fields cannot be modified after benefit synchronization:
clientCode
benefitContent
benefitBudget

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Request parameters

Field	Data type	Required	Description	Example
benefitSyncRequestId	String	Yes	Indicates the unique ID assigned by our server to identify a request of benefit synchronization. Maximum length: 64 characters Characters not allowed: special characters such as @ # ? Note: This field is an idempotency field. For synchronization requests which are initiated with the same benefitSyncRequestId, our server must return the same result. For details about API idempotency, see the Idempotency chapter.	-
benefitTemplateId	String	Yes	Indicates the unique ID assigned by our server to identify one type of benefit. Maximum length: 64 characters Characters not allowed: special characters such as @ # ?	-
benefitProductCode	String	Yes	Indicates the product code. The valid value is `SPICE_SECRET_VOUCHER`.	-
benefitTitle	String	Yes	Indicates benefit titles Maximum length: 128 characters Characters not allowed: special characters such as @ # ?	-
benefitBeginTime	String	Yes	Indicates the start time to collect a benefit. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".	UTC+05:30: "2019-04-04T12:08:56+05:30" UTC+0: "2019-04-04T12:08:56Z"
benefitEndTime	String	Yes	Indicates the end time to collect a benefit. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".	UTC+05:30: "2019-04-04T12:08:56+05:30" UTC+0: "2019-04-04T12:08:56Z"
benefitValidPeriod	BenefitValidPeriod	Yes	Indicates the validity period of a benefit after users collect the benefit.	-
clientCode	String	Yes	Indicates codes to identify different super apps. Valid values are: `TRUEMONEY`: TrueMoney `ALIPAY_HK`: Alipay HK `TNG`: Touch 'n Go `ALIPAY_CN`: Alipay CN `GCASH`: Gcash `DANA`: Dana `KAKAOPAY`: KakaoPay `BKASH`: bKash `CHOPE`: Chope `LAZADA`: Lazada Note: This field cannot be modified after benefit synchronization.	-
targetStatus	String	Yes	Indicates the benefit statuses. Valid values are: `ONLINE`: The benefit is online for users to access. First-time synchronization: Our server creates and releases the benefit. Already synchronized: Our server updates the benefit. `PAUSE`: Pause the benefit, which indicates that users cannot collect the benefit temporarily. Under this status, the benefit can be activated again. Our server does not modify other information of the benefit except its statuses. If the benefit is not synchronized to our server before, `BENEFIT_NOT_EXIST` is returned. `CLOSE`: The benefit is closed, which indicates that users cannot collect the benefit. Under this status, the benefit cannot be paused, updated or released again. Our server does not modify other information of the benefit except its statuses. If the benefit is not synchronized to our server before, `BENEFIT_NOT_EXIST` is returned.	-
benefitMerchant	MerchantInfo	Yes	Indicates the merchant information.	-
benefitContent	BenefitContent	Yes	Indicates the benefit content. Note: This field cannot be modified after benefit synchronization.	-
benefitBudget	BenefitBudget	Yes	Indicates the benefit budget. Note: This field cannot be modified after benefit synchronization.	-
benefitCollectRule	BenefitCollectRule	Yes	Indicates the rules to collect the benefit.
description	String	No	Indicates the benefit description. Maximum length: 2048 characters Can be empty.	-
extendInfo	String	No	Indicates the extended information about this API. Maximum length: 2048 characters Characters not allowed: special characters such as @ # ? Can be empty.	"{\"k1\":\"v1\",\"k2\":\"v2\"}"

Response parameters

Field	Data type	Required	Description
result	Result	Yes	Indicates the request result, such as status and error codes.

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request. The following table describes each result status:

Result status	Description
S	Our server has successfully accepted the request for benefit synchronization. The corresponding result.resultCode is `SUCCESS` and the result.resultMessage is `Success`.
U	The status of the request for benefit synchronization is unknown. The corresponding result.resultCode is `UNKNOWN_EXCEPTION` and result.resultMessage is "An API calling is failed, which is caused by unknown reasons.". For details, see the Common error codes section.
F	The request of benefit synchronization failed to be accepted by our server. The corresponding result.resultCode and result.resultMessage are various based on different situations. For details, see the following Error codes section.

Error codes

Error codes are usually classified into the following categories:

Common error codes are common across all openAPIs for ISVs.
API-specific error codes are listed in the following table:

Error code	Result status	Error message	Further action
BENEFIT_CLOSED	F	The benefit has closed and you cannot synchronize the benefit.	Use another benefit template ID to synchronize a new benefit.
BENEFIT_EXPIRED	F	The benefit is expired and you cannot synchronize the benefit.	Use another benefit template ID to synchronize the same information as the expired one.
BENEFIT_SYNC_PROCESSING	U	You cannot synchronize benefits that are synchronizing.	Try again later.
SPECIFIED_INFO_CANNOT_MODIFY	F	You cannot modify the specified information, including client codes, benefit content, and benefit budget.	-
BENEFIT_NOT_EXIST	F	The benefit does not exist.	Make sure the status of the benefit is online when you synchronize the benefit to our server for the first time.

Samples

Request

copy
{
    "benefitSyncRequestId": "20211111010101000001234",
    "benefitTemplateId": "202001010101011234",
    "benefitProductCode": "SPICE_SECRET_VOUCHER",
    "benefitTitle": "KFC 10 yuan discount",
    "benefitBeginTime": "2019-04-04T12:08:56+05:30",
    "benefitEndTime": "2029-04-04T12:08:56+05:30",
    "benefitValidPeriod": {
        "type": "ABSOLUTE",
        "activeTime": "2019-04-04T12:08:56+05:30",
        "expireTime": "2019-05-04T12:08:56+05:30",
        "activeSeconds": null,
        "expireSeconds": null
    },
    "clientCode": "ALIPAY_CN",
    "targetStatus": "ONLINE",
    "benefitMerchant": {
        "merchantId": "123455667",
        "name": "KCF China",
        "mcc": "5812",
        "logoImage": {
            "type": "URL",
            "name": "http://www.pic.com/some/pic/url.png"
        }
    },
    "benefitContent": {
        "type": "REDUCE_BY",
        "thresholdAmount": {
            "currency": "USD",
            "value": "50000"
        },
        "amount": {
            "currency": "USD",
            "value": "1000"
        },
        "ratio": "",
        "giftDescription": ""
    },
    "benefitBudget": {
        "type": "COUNT",
        "amount": null,
        "count": 300
    },
    "benefitCollectRule": {
        "type":"LIFE_TIME",
        "count":1
    },
    "description": "    Voucher：\nKFC 10 yuan discount\n\nUsage Rules：\n1. Valid from Monday to Sunday\n2. Used in stores such as xxx\n3. xxxxxx\n\n",
    "extendInfo": "{\"k1\":\"v1\",\"k2\":\"v2\"}"
}

Response

copy
{
    "result": {
        "resultStatus": "S",
        "resultCode": "",
        "resultMessage": ""
    }
}