Get Client's Coupons/Cards List

GEThttps://api.lbkrs.com/rewards/card_list

Parameters

currentstringqueryRequired

Page number, starting from 1

page_sizestringqueryRequired

Items per page, max 50

card_statusstringqueryOptional

Coupon/voucher status filter：

-1 - Not expired
2 - Expired

-12

card_typestringqueryOptional

Card type filter; empty returns all. Aggregate tabs: ipo_tab (IPO benefit card aggregated), quote_tab (merged quote/fundamental cards); single card types: cash, quote, fundamental, commission, ipo, ipo_interest, ipo_commission, stock, stock_fragment, platform_fee_deduct, finance_interest, fund_interest, coffee_coupon

tag_keystringqueryOptional

Card tag_key; 0 means all; used for tab-mode filtering

account_channelstringqueryRequired

Broker channel

Responses

HTTP 200The request succeeded. The response body contains the result of the “Get Client's coupons/cards list” operation.

Standard response envelopecodemessagedata

dataobjectdata structure

top_listarray<object>

Pinned cards list

Child attributes

card_idstring

Card/Coupon id

member_idstring

The member_id of the Client who holds the card.

card_typestring

Card/Coupon type: cash Cash card, quote Market data card, fundamental Fundamental card, commission Commission-free card, ipo IPO privilege card, ipo_interest IPO financing interest card, ipo_commission IPO fee card, stock Stock card, stock_fragment Fractional share card, platform_fee_deduct Platform fee deduction card, finance_interest Margin financing interest card, fund_interest Fund interest-boost card, coffee_coupon Coffee coupon

cashquotefundamentalcommissionipoipo_interestipo_commissionstockstock_fragmentplatform_fee_deductfinance_interestfund_interestcoffee_coupon

titlestring

Card/Coupon title

title_secstring

Card/Coupon subtitle

coverstring

Cover image

descriptionstring

Client-facing description.

start_timestring

Usable start timestamp (seconds)

end_timestring

Expiry timestamp (seconds)

card_statusinteger

Coupon/voucher status：

0 - Not activated
1 - Used
2 - Expired
3 - In use
4 - Activated

01234

detailstring

Card/Coupon details

currencystring

Currency unit, applicable to Cash cards, Commission-free cards, IPO financing interest cards, IPO fee cards

amountstring

Associated amount

activate_timestring

Card/Coupon activation time

invisibleboolean

Is invisible (used only in available-cards list scenario)

backgroundstring

Card/Coupon background image

stylestring

Card/Coupon style

account_channelstring

Account channels applicable to the card/coupon

new_flagboolean

New card indicator

cashobject

Cash card information

Child attributes

receive_durationstring

Cash arrival time required (seconds)

quoteobject

Market data card / Fundamental card information

Child attributes

quote_durationstring

Permission duration (seconds)

marketsarray<string>

Entitlement market(s)

superpositionboolean

Is time stackable

quote_marketstring

Market data market

current_end_timestring

Current expiration time

manual_activateboolean

Requires manual activation

need_certifyboolean

Requires professional investor accreditation

fundamentalobject

Market data card / Fundamental card information

Child attributes

quote_durationstring

Permission duration (seconds)

marketsarray<string>

Entitlement market(s)

superpositionboolean

Is time stackable

quote_marketstring

Market data market

current_end_timestring

Current expiration time

manual_activateboolean

Requires manual activation

need_certifyboolean

Requires professional investor accreditation

commissionobject

Commission-free card information

Child attributes

marketsarray<string>

Commission-free markets, e.g. US, SH, SG, HK

rebate_ratestring

Commission-free ratio, 1 represents 100%

bz_typesarray<integer>

Applicable instrument types

commission_durationstring

Commission-free card duration (seconds)

commission_balancestring

Commission-free card balance

unlimitedinteger

Commission-free mode：

0 - Proportional commission-free (collect first, rebate later; time-limited)
1 - Full commission-free (collect first, rebate later; time-limited)
2 - Lifetime commission-free (direct deduction; no usage limit)
6 - Fixed-amount per-use card (usage count limit, time-limited)
7 - Discount per-use card (usage count limit, time-limited)

01267

commission_expired_timestring

Commission-free expiry time (for commission-free cards currently in use)

superpositionboolean

Is time stackable

settlement_modelstring

Settlement mode: payback charge-first-refund-later, compensate direct deduction

paybackcompensate

usage_countstring

Commission-free card usage count

lave_usage_countstring

Remaining available uses

amount_limitstring

Per-use amount cap (unit: cents); absence means no limit

ipoobject

IPO privilege card information

Child attributes

subscription_idstring

Reservation id; empty means generalized IPO card

ipo_interestobject

IPO financing interest card information

Child attributes

discount_ratestring

Subsidy interest rate, 1 represents 100%

ipo_commissionobject

IPO fee card information

Child attributes

bz_typesarray<integer>

IPO method

financing_limitstring

Financing IPO quota threshold, 0 means no threshold

counter_idstring

Specified IPO stock id; empty means no restriction

stockobject

Stock card information

Child attributes

counter_idstring

Stock id

amountnumber

Number of shares issued, supports fractional shares

redemption_typestring

Redemption type: by_card_value redeem by card face value, shares_number fixed shares redemption (default)

by_card_valueshares_number

stock_fragmentobject

Fractional-share card information.

Child attributes

counter_idstring

Applicable stock id; empty means fractional-share general card

marketsarray<string>

Applicable market

amountsobject

Issuance quantity per market

underlying_typeinteger

Underlying/instrument type：

0 - Stock trading
1 - US equity options
2 - HK warrants
3 - Exchange-traded funds (ETF)
4 - Off-exchange funds (LOF)

01234

platform_fee_deductobject

Platform fee deduction card information

Child attributes

usage_countstring

Usage count

lave_usage_countstring

Remaining available uses

superpositionboolean

Is time stackable

marketsarray<string>

Applicable market

bz_typesarray<integer>

Applicable instrument types

counter_idstring

Applicable stock id

finance_interestobject

Financing interest card information

Child attributes

discount_modeinteger

Discount method

discount_ratenumber

Discount rate

superpositionboolean

Is stackable/extendable

fund_interestobject

Fund interest-boost card information (structure is dynamic JSON; fields are not fixed)

coffee_couponobject

Coffee coupon information

Child attributes

coupon_channelstring

Card/Coupon channel

coupon_nostring

Third-party card/coupon number

use_limitstring

Usage limit type: total total-use limit, period periodic-use limit

totalperiod

thresholdstring

Maximum uses

period_typestring

Period type (effective when use_limit is period), e.g. day

coupon_idstring

Third-party card/coupon id

store_id_listarray<string>

Store IDs where the coupon can be used.

is_available_all_storeboolean

Whether the coupon can be used at every store.

settled_store_idstring

ID of the store where the coupon was redeemed.

store_listarray<object>

Stores where the coupon can be used. The item schema is not defined.

cryptoobject

Virtual asset card information. The object schema is not defined.

ai_benefitobject

AI benefit card information.

Child attributes

benefit_tagstring

Entitlement tag

benefit_daysinteger

Entitlement days

benefit_startstring

Entitlement start time

benefit_endstring

Entitlement end time

receive_durationstring

Time for cash to arrive (seconds). Deprecated and pending removal; semantics same as cash.receive_duration; retained only for compatibility with legacy Broker App.

quote_durationstring

Permission duration (seconds). Deprecated and pending removal; semantics same as quote.quote_duration; retained only for compatibility with legacy Broker App.

marketsarray<string>

Commission-free markets. Deprecated and pending removal; semantics same as commission.markets; retained only for compatibility with legacy Broker App.

rebate_ratestring

Commission-free rebate rate. Deprecated and pending removal; semantics same as commission.rebate_rate; retained only for compatibility with legacy Broker App.

bz_typesarray<integer>

Applicable underlying types. Deprecated and pending removal; semantics same as commission.bz_types; retained only for compatibility with legacy Broker App.

commission_balancestring

Commission-free card balance. Deprecated and pending removal; semantics same as commission.commission_balance; retained only for compatibility with legacy Broker App.

commission_durationstring

Commission-free card duration (seconds). Deprecated and pending removal; semantics same as commission.commission_duration; retained only for compatibility with legacy Broker App.

subscription_idstring

IPO privilege card subscription id. Deprecated and pending removal; semantics same as ipo.subscription_id; retained only for compatibility with legacy Broker App.

listarray<object>

Cards list

Child attributes

card_idstring

Card/Coupon id

member_idstring

The member_id of the Client who holds the card.

card_typestring

cashquotefundamentalcommissionipoipo_interestipo_commissionstockstock_fragmentplatform_fee_deductfinance_interestfund_interestcoffee_coupon

titlestring

Card/Coupon title

title_secstring

Card/Coupon subtitle

coverstring

Cover image

descriptionstring

Client-facing description.

start_timestring

Usable start timestamp (seconds)

end_timestring

Expiry timestamp (seconds)

card_statusinteger

Coupon/voucher status：

0 - Not activated
1 - Used
2 - Expired
3 - In use
4 - Activated

01234

detailstring

Card/Coupon details

currencystring

Currency unit, applicable to Cash cards, Commission-free cards, IPO financing interest cards, IPO fee cards

amountstring

Associated amount

activate_timestring

Card/Coupon activation time

invisibleboolean

Is invisible (used only in available-cards list scenario)

backgroundstring

Card/Coupon background image

stylestring

Card/Coupon style

account_channelstring

Account channels applicable to the card/coupon

new_flagboolean

New card indicator

cashobject

Cash card information

Child attributes

receive_durationstring

Cash arrival time required (seconds)

quoteobject

Market data card / Fundamental card information

Child attributes

quote_durationstring

Permission duration (seconds)

marketsarray<string>

Entitlement market(s)

superpositionboolean

Is time stackable

quote_marketstring

Market data market

current_end_timestring

Current expiration time

manual_activateboolean

Requires manual activation

need_certifyboolean

Requires professional investor accreditation

fundamentalobject

Market data card / Fundamental card information

Child attributes

quote_durationstring

Permission duration (seconds)

marketsarray<string>

Entitlement market(s)

superpositionboolean

Is time stackable

quote_marketstring

Market data market

current_end_timestring

Current expiration time

manual_activateboolean

Requires manual activation

need_certifyboolean

Requires professional investor accreditation

commissionobject

Commission-free card information

Child attributes

marketsarray<string>

Commission-free markets, e.g. US, SH, SG, HK

rebate_ratestring

Commission-free ratio, 1 represents 100%

bz_typesarray<integer>

Applicable instrument types

commission_durationstring

Commission-free card duration (seconds)

commission_balancestring

Commission-free card balance

unlimitedinteger

Commission-free mode：

0 - Proportional commission-free (collect first, rebate later; time-limited)
1 - Full commission-free (collect first, rebate later; time-limited)
2 - Lifetime commission-free (direct deduction; no usage limit)
6 - Fixed-amount per-use card (usage count limit, time-limited)
7 - Discount per-use card (usage count limit, time-limited)

01267

commission_expired_timestring

Commission-free expiry time (for commission-free cards currently in use)

superpositionboolean

Is time stackable

settlement_modelstring

Settlement mode: payback charge-first-refund-later, compensate direct deduction

paybackcompensate

usage_countstring

Commission-free card usage count

lave_usage_countstring

Remaining available uses

amount_limitstring

Per-use amount cap (unit: cents); absence means no limit

ipoobject

IPO privilege card information

Child attributes

subscription_idstring

Reservation id; empty means generalized IPO card

ipo_interestobject

IPO financing interest card information

Child attributes

discount_ratestring

Subsidy interest rate, 1 represents 100%

ipo_commissionobject

IPO fee card information

Child attributes

bz_typesarray<integer>

IPO method

financing_limitstring

Financing IPO quota threshold, 0 means no threshold

counter_idstring

Specified IPO stock id; empty means no restriction

stockobject

Stock card information

Child attributes

counter_idstring

Stock id

amountnumber

Number of shares issued, supports fractional shares

redemption_typestring

Redemption type: by_card_value redeem by card face value, shares_number fixed shares redemption (default)

by_card_valueshares_number

stock_fragmentobject

Fractional-share card information.

Child attributes

counter_idstring

Applicable stock id; empty means fractional-share general card

marketsarray<string>

Applicable market

amountsobject

Issuance quantity per market

underlying_typeinteger

Underlying/instrument type：

0 - Stock trading
1 - US equity options
2 - HK warrants
3 - Exchange-traded funds (ETF)
4 - Off-exchange funds (LOF)

01234

platform_fee_deductobject

Platform fee deduction card information

Child attributes

usage_countstring

Usage count

lave_usage_countstring

Remaining available uses

superpositionboolean

Is time stackable

marketsarray<string>

Applicable market

bz_typesarray<integer>

Applicable instrument types

counter_idstring

Applicable stock id

finance_interestobject

Financing interest card information

Child attributes

discount_modeinteger

Discount method

discount_ratenumber

Discount rate

superpositionboolean

Is stackable/extendable

fund_interestobject

Fund interest-boost card information (structure is dynamic JSON; fields are not fixed)

coffee_couponobject

Coffee coupon information

Child attributes

coupon_channelstring

Card/Coupon channel

coupon_nostring

Third-party card/coupon number

use_limitstring

Usage limit type: total total-use limit, period periodic-use limit

totalperiod

thresholdstring

Maximum uses

period_typestring

Period type (effective when use_limit is period), e.g. day

coupon_idstring

Third-party card/coupon id

store_id_listarray<string>

Store IDs where the coupon can be used.

is_available_all_storeboolean

Whether the coupon can be used at every store.

settled_store_idstring

ID of the store where the coupon was redeemed.

store_listarray<object>

Stores where the coupon can be used. The item schema is not defined.

cryptoobject

Virtual asset card information. The object schema is not defined.

ai_benefitobject

AI benefit card information.

Child attributes

benefit_tagstring

Entitlement tag

benefit_daysinteger

Entitlement days

benefit_startstring

Entitlement start time

benefit_endstring

Entitlement end time

receive_durationstring

Time for cash to arrive (seconds). Deprecated and pending removal; semantics same as cash.receive_duration; retained only for compatibility with legacy Broker App.

quote_durationstring

Permission duration (seconds). Deprecated and pending removal; semantics same as quote.quote_duration; retained only for compatibility with legacy Broker App.

marketsarray<string>

Commission-free markets. Deprecated and pending removal; semantics same as commission.markets; retained only for compatibility with legacy Broker App.

rebate_ratestring

Commission-free rebate rate. Deprecated and pending removal; semantics same as commission.rebate_rate; retained only for compatibility with legacy Broker App.

bz_typesarray<integer>

Applicable underlying types. Deprecated and pending removal; semantics same as commission.bz_types; retained only for compatibility with legacy Broker App.

commission_balancestring

Commission-free card balance. Deprecated and pending removal; semantics same as commission.commission_balance; retained only for compatibility with legacy Broker App.

commission_durationstring

Commission-free card duration (seconds). Deprecated and pending removal; semantics same as commission.commission_duration; retained only for compatibility with legacy Broker App.

subscription_idstring

IPO privilege card subscription id. Deprecated and pending removal; semantics same as ipo.subscription_id; retained only for compatibility with legacy Broker App.

bottom_listarray<object>

Bottom-pinned cards list

Child attributes

card_idstring

Card/Coupon id

member_idstring

The member_id of the Client who holds the card.

card_typestring

cashquotefundamentalcommissionipoipo_interestipo_commissionstockstock_fragmentplatform_fee_deductfinance_interestfund_interestcoffee_coupon

titlestring

Card/Coupon title

title_secstring

Card/Coupon subtitle

coverstring

Cover image

descriptionstring

Client-facing description.

start_timestring

Usable start timestamp (seconds)

end_timestring

Expiry timestamp (seconds)

card_statusinteger

Coupon/voucher status：

0 - Not activated
1 - Used
2 - Expired
3 - In use
4 - Activated

01234

detailstring

Card/Coupon details

currencystring

Currency unit, applicable to Cash cards, Commission-free cards, IPO financing interest cards, IPO fee cards

amountstring

Associated amount

activate_timestring

Card/Coupon activation time

invisibleboolean

Is invisible (used only in available-cards list scenario)

backgroundstring

Card/Coupon background image

stylestring

Card/Coupon style

account_channelstring

Account channels applicable to the card/coupon

new_flagboolean

New card indicator

cashobject

Cash card information

Child attributes

receive_durationstring

Cash arrival time required (seconds)

quoteobject

Market data card / Fundamental card information

Child attributes

quote_durationstring

Permission duration (seconds)

marketsarray<string>

Entitlement market(s)

superpositionboolean

Is time stackable

quote_marketstring

Market data market

current_end_timestring

Current expiration time

manual_activateboolean

Requires manual activation

need_certifyboolean

Requires professional investor accreditation

fundamentalobject

Market data card / Fundamental card information

Child attributes

quote_durationstring

Permission duration (seconds)

marketsarray<string>

Entitlement market(s)

superpositionboolean

Is time stackable

quote_marketstring

Market data market

current_end_timestring

Current expiration time

manual_activateboolean

Requires manual activation

need_certifyboolean

Requires professional investor accreditation

commissionobject

Commission-free card information

Child attributes

marketsarray<string>

Commission-free markets, e.g. US, SH, SG, HK

rebate_ratestring

Commission-free ratio, 1 represents 100%

bz_typesarray<integer>

Applicable instrument types

commission_durationstring

Commission-free card duration (seconds)

commission_balancestring

Commission-free card balance

unlimitedinteger

Commission-free mode：

0 - Proportional commission-free (collect first, rebate later; time-limited)
1 - Full commission-free (collect first, rebate later; time-limited)
2 - Lifetime commission-free (direct deduction; no usage limit)
6 - Fixed-amount per-use card (usage count limit, time-limited)
7 - Discount per-use card (usage count limit, time-limited)

01267

commission_expired_timestring

Commission-free expiry time (for commission-free cards currently in use)

superpositionboolean

Is time stackable

settlement_modelstring

Settlement mode: payback charge-first-refund-later, compensate direct deduction

paybackcompensate

usage_countstring

Commission-free card usage count

lave_usage_countstring

Remaining available uses

amount_limitstring

Per-use amount cap (unit: cents); absence means no limit

ipoobject

IPO privilege card information

Child attributes

subscription_idstring

Reservation id; empty means generalized IPO card

ipo_interestobject

IPO financing interest card information

Child attributes

discount_ratestring

Subsidy interest rate, 1 represents 100%

ipo_commissionobject

IPO fee card information

Child attributes

bz_typesarray<integer>

IPO method

financing_limitstring

Financing IPO quota threshold, 0 means no threshold

counter_idstring

Specified IPO stock id; empty means no restriction

stockobject

Stock card information

Child attributes

counter_idstring

Stock id

amountnumber

Number of shares issued, supports fractional shares

redemption_typestring

Redemption type: by_card_value redeem by card face value, shares_number fixed shares redemption (default)

by_card_valueshares_number

stock_fragmentobject

Fractional-share card information.

Child attributes

counter_idstring

Applicable stock id; empty means fractional-share general card

marketsarray<string>

Applicable market

amountsobject

Issuance quantity per market

underlying_typeinteger

Underlying/instrument type：

0 - Stock trading
1 - US equity options
2 - HK warrants
3 - Exchange-traded funds (ETF)
4 - Off-exchange funds (LOF)

01234

platform_fee_deductobject

Platform fee deduction card information

Child attributes

usage_countstring

Usage count

lave_usage_countstring

Remaining available uses

superpositionboolean

Is time stackable

marketsarray<string>

Applicable market

bz_typesarray<integer>

Applicable instrument types

counter_idstring

Applicable stock id

finance_interestobject

Financing interest card information

Child attributes

discount_modeinteger

Discount method

discount_ratenumber

Discount rate

superpositionboolean

Is stackable/extendable

fund_interestobject

Fund interest-boost card information (structure is dynamic JSON; fields are not fixed)

coffee_couponobject

Coffee coupon information

Child attributes

coupon_channelstring

Card/Coupon channel

coupon_nostring

Third-party card/coupon number

use_limitstring

Usage limit type: total total-use limit, period periodic-use limit

totalperiod

thresholdstring

Maximum uses

period_typestring

Period type (effective when use_limit is period), e.g. day

coupon_idstring

Third-party card/coupon id

store_id_listarray<string>

Store IDs where the coupon can be used.

is_available_all_storeboolean

Whether the coupon can be used at every store.

settled_store_idstring

ID of the store where the coupon was redeemed.

store_listarray<object>

Stores where the coupon can be used. The item schema is not defined.

cryptoobject

Virtual asset card information. The object schema is not defined.

ai_benefitobject

AI benefit card information.

Child attributes

benefit_tagstring

Entitlement tag

benefit_daysinteger

Entitlement days

benefit_startstring

Entitlement start time

benefit_endstring

Entitlement end time

receive_durationstring

Time for cash to arrive (seconds). Deprecated and pending removal; semantics same as cash.receive_duration; retained only for compatibility with legacy Broker App.

quote_durationstring

Permission duration (seconds). Deprecated and pending removal; semantics same as quote.quote_duration; retained only for compatibility with legacy Broker App.

marketsarray<string>

Commission-free markets. Deprecated and pending removal; semantics same as commission.markets; retained only for compatibility with legacy Broker App.

rebate_ratestring

Commission-free rebate rate. Deprecated and pending removal; semantics same as commission.rebate_rate; retained only for compatibility with legacy Broker App.

bz_typesarray<integer>

Applicable underlying types. Deprecated and pending removal; semantics same as commission.bz_types; retained only for compatibility with legacy Broker App.

commission_balancestring

Commission-free card balance. Deprecated and pending removal; semantics same as commission.commission_balance; retained only for compatibility with legacy Broker App.

commission_durationstring

Commission-free card duration (seconds). Deprecated and pending removal; semantics same as commission.commission_duration; retained only for compatibility with legacy Broker App.

subscription_idstring

IPO privilege card subscription id. Deprecated and pending removal; semantics same as ipo.subscription_id; retained only for compatibility with legacy Broker App.

totalstring

Total count

expired_countstring

Number of expired cards

tagsarray<object>

Filter tags

Child attributes

keyinteger

Tag key

textstring

Tag name, e.g., "All", "Reservation Card"

activatedboolean

Is currently selected tag

valid_card_typesarray<string>

Valid card types list (protobuf annotation: to be deprecated)

valid_typesobject

Key is card type; value indicates whether there are new records for that type (used to show a red-dot indicator)

Request

let request = WhaleCoreHTTPRequest(
    method: .get,
    path: "/rewards/card_list"
)
request.query = [
    "current": 1,
    "page_size": 10,
    "card_status": -1,
    "tag_key": 0,
    "account_channel": "lb"
]

let response = try await WhaleCoreService.requestService.send(request)
print(response.bodyString)

Response Example

{
  "code": 0,
  "message": "success",
  "data": {
    "top_list": [],
    "list": [
      {
        "card_id": "<CARD_ID>",
        "card_type": "coffee_coupon",
        "title": "Lifetime Half-Price Coffee Coupon",
        "title_sec": "",
        "member_id": "<MEMBER_ID>",
        "cover": "https://assets.lbctrl.com/uploads/045892a9-67c6-490a-96b6-b051b94b5fb0/e_voucher_icon.png",
        "description": "Redeemable at Longbridge Café",
        "start_time": "1759075200",
        "end_time": "8078543998",
        "card_status": 0,
        "detail": "",
        "currency": "HKD",
        "amount": "40",
        "activate_time": "0",
        "invisible": false,
        "background": "#CD8949",
        "style": "",
        "cash": null,
        "quote": null,
        "fundamental": null,
        "commission": null,
        "ipo": null,
        "ipo_interest": null,
        "ipo_commission": null,
        "stock": null,
        "stock_fragment": null,
        "platform_fee_deduct": null,
        "finance_interest": null,
        "fund_interest": null,
        "receive_duration": "0",
        "quote_duration": "0",
        "markets": [],
        "rebate_rate": "",
        "bz_types": [],
        "commission_balance": "",
        "commission_duration": "0",
        "subscription_id": "",
        "account_channel": "lb",
        "new_flag": false,
        "coffee_coupon": {
          "coupon_channel": "Eats365",
          "coupon_no": "coffee-50",
          "use_limit": "period",
          "threshold": "1",
          "period_type": "day",
          "coupon_id": "",
          "store_id_list": [],
          "is_available_all_store": true,
          "settled_store_id": "0",
          "store_list": []
        },
        "crypto": null,
        "ai_benefit": null
      }
    ],
    "bottom_list": [],
    "total": "3",
    "tags": [],
    "expired_count": "98",
    "valid_card_types": [
      "stock",
      "ipo_tab",
      "quote_tab",
      "commission",
      "coffee_coupon"
    ],
    "valid_types": {
      "coffee_coupon": false,
      "commission": false,
      "ipo_tab": false,
      "quote_tab": false,
      "stock": false
    }
  }
}