inquireMemberAssets

2023-04-28 21:00

POST /v2/pds/memberships/inquireMemberAssets

With this API call, Mini Program Platform can request the merchant to query the membership assets of a user.

The message structure of this API is defined by us. Follow the specifications below when the merchant develops this API.

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
cardNo	String	Yes	Indicates the unique card number generated by Mini Program Platform to identify a card, which is returned in the issueCard API. Maximum length: 64 characters. Characters not allowed: special characters such as @, #, ? and so on.	"011164508621375700010170***"
assetTypes	Array<String>	Yes	Indicates the types of the assets. Maximum size: 3 elements Valid values are: `BENEFIT`: The member benefits `POINT`: The reward points `BALANCE`: The balance of the membership card	[ "BENEFIT", "POINT", "BALANCE" ]
queryConditions	String	No	Indicates the conditions for making an asset query. This parameter can be specified based on the following: useThresholdByOrderItems: Indicates an asset query based on a list of order items in the order, which is in JSON format containing an Array<OrderItem> object. The maximum size of the array is 120 elements. useThresholdByOrderType: Indicates an asset query based on the type of the order. Valid values are: `PICKUP`: Food that is picked up by users themselves. `DINEIN`: Food that is eaten in the restaurant where it is ordered. `DELIVERY`: Food that requests delivery to a specific destination. benefitStatus: Indicates an asset query based on the statuses of the benefits, which is in JSON format containing an Array<String> object. The maximum size of the array is 3 elements. Valid values are: `ACTIVATED`: The benefit is activated. `USED`: The benefit is used. `EXPIRED`: The benefit is expired. benefitPage: Indicates an asset query based on the paging of the benefit results, which is in JSON format and must contain the following fields: offset: An integer that indicates the starting number of the benefit lists to be queried (Value range: 0-2147483647). limit: An integer that indicates a specific limit on the number of query results (Value range: 1-100). Note: For detailed scenarios, see More information. For sample implementations, see Sample request.	-
extendInfo	String	No	Indicates the extended information about this API. Maximum length: 2048 characters Characters not allowed: special characters such as @ # ?	-

Response parameters

Field	Data type	Required	Description
result	Result	Yes	Indicates the request result, such as status and error codes.
assetDetails	Array<AssetDetail>	Yes	Indicates the details of the membership assets. Maximum size: 3 elements
extendInfo	String	No	Indicates the extended information about the response. Maximum length: 2048 characters Characters not allowed: special characters such as @ # ?

Result Process Logic

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

resultStatus	Description
S	The request to query membership assets is successful. The corresponding `result.resultCode` is `SUCCESS` and the `result.resultMessage` is `Success`.
U	The status of the request to query membership assets is unknown. The corresponding `result.resultCode` is `UNKNOWN_EXCEPTION` and the `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 to query membership assets failed. The corresponding `result.resultCode` and `result.resultMessage` can vary based on different situations. For details, see the following Error codes section.

More information

The scenarios for querying assets are listed below:

When the value of assetTypes is BENEFIT, specify the benefitStatus and benefitPage parameters to query all the benefits specified.

Sample request
Sample response

When the value of assetTypes is POINT and BALANCE, specify the useThreholdsByOrderItems and useThresholdByOrderType parameters to query the available points and balance.

Sample request
Sample response

When the value of assetTypes is BENEFIT, POINT, and BALANCE, specify the benefitStatus, benefitPage, useThreholdsByOrderItems, and useThresholdByOrderType parameters to query the available benefits, points, and balance. Note: In this scenario, assetDetails.assetValue.amount must be returned in the response.

Sample request
Sample response

Error codes

Error codes are usually classified into the following categories:

Common error codes are common for all Mini Program OpenAPIs in V2.
API-specific error codes:

Error code	Result status	Error message
EXPIRED_CRM_BIND_TOKEN	F	The CRM authentication token of the user is expired.

Sample

The data flow of sending a request to query membership assets is illustrated as follows:

The above diagram consists of the following steps:

Mini Program Platform calls this API to send a request to the merchant to query the benefit details of a member.
The merchant processes the request and queries the benefit details.
The merchant returns the result of the query to Mini Program Platform.

Request

Query benefits based on `benefitStatus`

The following provides the sample request for querying benefits based on the benefit statuses:

copy
{
    "cardNo": "CARD_2102010113769***",
    "assetTypes": [
        "BENEFIT"
    ],
    "queryConditions": {
        "benefitStatus": [
            "ACTIVATED",
            "USED",
            "EXPIRED"
        ],
        "benefitPage": {
            "offset": 0,
            "limit": 10
        }
    }
}

Query available points and balance

The following provides the sample request for querying the available points and balance based on the order items and the order type:

copy
{
  "cardNo": "CARD_2102010113769***",
  "assetTypes": [
    "POINT",
    "BALANCE"
  ],
  "queryConditions": {
    "useThresholdByOrderItems": [
      {
        "categoryId": "100",
        "itemId": "11010",
        "requestSubOrderId": "2022050400311864775",
        "notAvailableOption": "Remove it from my order",
        "priceInfo": {
          "currency": "SGD",
          "saleAmount": 869
        },
        "quantity": 1,
        "skuId": "76251",
        "storeId": "121",
        "modifierGroupDetails": "[{\"groupId\":\"14524\",\"itemDetail\":[{\"categoryId\":\"100\",\"itemId\":\"11011\",\"requestSubOrderId\":\"2022050400311864775\",\"notAvailableOption\":\"Remove it from my order\",\"priceInfo\":{\"currency\":\"SGD\",\"saleAmount\":10},\"quantity\":2,\"storeId\":\"121\"}]}]"
      },
      {
        "categoryId": "100",
        "itemId": "11012",
        "requestSubOrderId": "2022050400311864775",
        "notAvailableOption": "Remove it from my order",
        "priceInfo": {
          "currency": "SGD",
          "saleAmount": 300
        },
        "quantity": 2,
        "storeId": "121"
      }
    ],
    "useThresholdByOrderType": "PICKUP"
  }
}

Query available benefits, points, and balance

The following provides the sample request for querying the available benefits, points, and balance based on the benefit statuses, order items, and order type:

copy
{
  "cardNo": "CARD_2102010113769***",
  "assetTypes": [
    "BENEFIT",
    "POINT",
    "BALANCE"
  ],
  "queryConditions": {
    "useThresholdByOrderItems": [
      {
        "categoryId": "100",
        "itemId": "11010",
        "requestSubOrderId": "2022050400311864775",
        "notAvailableOption": "Remove it from my order",
        "priceInfo": {
          "currency": "SGD",
          "saleAmount": 869
        },
        "quantity": 1,
        "skuId": "76251",
        "storeId": "121",
        "modifierGroupDetails": "[{\"groupId\":\"14524\",\"itemDetail\":[{\"categoryId\":\"100\",\"itemId\":\"11011\",\"requestSubOrderId\":\"2022050400311864775\",\"notAvailableOption\":\"Remove it from my order\",\"priceInfo\":{\"currency\":\"SGD\",\"saleAmount\":10},\"quantity\":2,\"storeId\":\"121\"}]}]"
      },
      {
        "categoryId": "100",
        "itemId": "11012",
        "requestSubOrderId": "2022050400311864775",
        "notAvailableOption": "Remove it from my order",
        "priceInfo": {
          "currency": "SGD",
          "saleAmount": 300
        },
        "quantity": 2,
        "storeId": "121"
      }
    ],
    "useThresholdByOrderType": "PICKUP",
    "benefitStatus": [
      "ACTIVATED",
      "USED",
      "EXPIRED"
    ],
    "benefitPage": {
      "offset": 0,
      "limit": 10
    }
  }
}

Response

Query benefits based on `benefitStatus`

The following provides the sample response for querying benefits:

copy
{
    "assetDetails": [
        {
            "assetType": "BENEFIT",
            "assetValue": [
                {
                    "benefitInstanceId": "011164508621375700010170***",
                    "status": "ACTIVATED",
                    "benefitTitle": {
                        "defaultLanguage": "en-US",
                        "languageValues": {
                            "en-US": "xxx",
                            "zh-CN": "xxx"
                        }
                    },
                    "useRules": {
                        "defaultLanguage": "en-US",
                        "languageValues": {
                            "en-US": "xxx",
                            "zh-CN": "xxx"
                        }
                    },
                    "useScenarios": {
                        "defaultLanguage": "en-US",
                        "languageValues": {
                            "en-US": "xxx",
                            "zh-CN": "xxx"
                        }
                    },
                    "iconUrl": "https://cdn.example.com/icon/xxx.icon",
                    "createdTime": "2022-02-14T00:00:00+08:00",
                    "expireTime": "2023-01-26T00:00:00+08:00"
                }
            ]
        }
    ],
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "Success",
        "resultStatus": "S"
    }
}

Query available points and balance

The following provides the sample response for querying the available points and balance:

copy
{
    "assetDetails": [
        {
            "assetType": "POINT",
            "assetValue": {
                "pointMaxAmount": {
                    "currency": "SGD",
                    "value": 100
                },
                "pointUnitAmount": {
                    "currency": "SGD",
                    "value": 1
                }
            }
        },
        {
            "assetType": "BALANCE",
            "assetValue": {
                "currency": "SGD",
                "value": 100
            }
        }
    ],
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "Success",
        "resultStatus": "S"
    }
}

Query available benefits, points, and balance

The following provides the sample response for querying the available benefits, points, and balance:

copy
{
    "assetDetails": [
        {
            "assetType": "BENEFIT",
            "assetValue": [
                {
                    "benefitInstanceId": "011164508621375700010170***",
                    "status": "ACTIVATED",
                    "amount": {
                        "currency": "SGD",
                        "value": 100
                    },
                    "benefitTitle": {
                        "defaultLanguage": "en-US",
                        "languageValues": {
                            "en-US": "xxx",
                            "zh-CN": "xxx"
                        }
                    },
                    "useRules": {
                        "defaultLanguage": "en-US",
                        "languageValues": {
                            "en-US": "xxx",
                            "zh-CN": "xxx"
                        }
                    },
                    "useScenarios": {
                        "defaultLanguage": "en-US",
                        "languageValues": {
                            "en-US": "xxx",
                            "zh-CN": "xxx"
                        }
                    },
                    "iconUrl": "https://cdn.example.com/icon/xxx.icon",
                    "createdTime": "2022-02-14T00:00:00+08:00",
                    "expireTime": "2023-01-26T00:00:00+08:00"
                }
            ]
        },
        {
            "assetType": "POINT",
            "assetValue": {
                "pointMaxAmount": {
                    "currency": "SGD",
                    "value": 100
                },
                "pointUnitAmount": {
                    "currency": "SGD",
                    "value": 1
                }
            }
        },
        {
            "assetType": "BALANCE",
            "assetValue": {
                "currency": "SGD",
                "value": 100
            }
        }
    ],
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "Success",
        "resultStatus": "S"
    }
}

inquireMemberAssets

Structure

Request parameters

Response parameters

Result Process Logic

More information

Error codes

Sample

Request

Query benefits based on benefitStatus

Query available points and balance

Query available benefits, points, and balance

Response

Query benefits based on benefitStatus

Query available points and balance

Query available benefits, points, and balance

Query benefits based on `benefitStatus`

Query benefits based on `benefitStatus`