Add Billing Company Fee

Adds an agent (organization) fee rate.

Request parameters

Required: custodian_id (agent/custodian organization ID), billing_item_id (billing-item ID), threshold (minimum-charge threshold), fee_rate_type (rate type), calculation_method, rates (rate-rule details), currency, min (minimum charge), max (maximum charge), granularity, cutoff_method, cutoff_digits
Optional: billing_item (billing-item snapshot), metric_type, fixed_rates, max_metric/max_metric_type/max_metric_rate (cap-as-a-share-of-trade-amount config), min_metric/min_metric_type/min_metric_rate (penny-stock billing config), metric_cycle_type, special_fees (special-rate condition list), audit_frontend_resource (audit context)
See the field descriptions for the format, value range, and business meaning of each field.

Business notes

Obtain the candidate values for custodian_id via GET /v1/datasets/refs/clearing_agents_all and for currency via GET /v1/datasets/refs/tenant_currencies_by_channel. threshold is required when metric_type is not "per-contract-count" billing.

Risk warning

This operation changes live billing configuration and may affect how customers are actually charged. Verify the target record and parameters before calling.

Result

On success, the operation completes; the resulting state and returned data follow the 200 response definition.

POSThttps://b-api.lbkrs.com/billing/company_fee

Authorization

AuthorizationstringheaderRequired

Send the Broker ACCESS_TOKEN as Authorization: Bearer <token>.

Permission

lb_hk_charging.lb_hk_scene_update

The Broker ACCESS_TOKEN must be granted the permission above, or the call will be rejected.

Request body application/json

custodian_idstringrequired

Custodian; value comes from the clear_custodian_broker_no_all dynamic enum, not fixed.

Call GET /v1/datasets/refs/clearing_agents_all to retrieve the current data dictionary, and use the returned entry's key as this field's value.

billing_item_idstringrequired

The billing item ID, selected via the billing item selector.

billing_itemobject

The billing-item object, containing fields such as id/name_loc, submitted together with the selected billing scenario.

metric_typestring

The measurement type, filtered by the selected billing item.

Allowed values: 1 Traded quantity (fractional shares supported), 2 Traded amount, 3 Single charge per billing granularity, 4 Option contracts, 5 Unexpected upstream return fee, 6 Billed contract quantity, 7 Order count, 8 Execution count, 9 Position market value, 10 Secondary charge based on existing scenarios, 11 Securities lending market value, 13 Traded lots (transfer), 14 Market value (transfer), 15 EMS order count

Values

1: Transaction Quantity(Fractional support)
2: Transaction Amount
3: Single Billing By Corresponding granularity
4: Options Quantity
5: Upstream
6: Number Of Billing Contracts
7: Number Of Orders
8: Number Of Transactions
9: Value Of Positions
10: Calculation Based On Existing Scenarios
11: Market Value Of Securities Lending
13: Transaction Quantity Of Board Lot (Transfer Warehouse)
14: Market Value (Transfer Warehouse)
15: Number of Ems Orders

thresholdstringrequired

The measurement threshold; required when metric_type is not "charge by number of contracts". A numeric string with at most 10 decimal places.

fee_rate_typestringrequired

Rate type.

Allowed values: 1 Fixed rate, 2 Single-trade tiered rate, 3 Monthly tiered rate, 4 Floating rate, 5 Floating rate (single-trade tiered)

Agent billing does not support monthly-tiered type 3.

Values

1: Flat Rate
2: Tiered Rate Per Txn
3: Monthly Tiered Rate
4: Float Rate
5: Float Rate (Per Txn)

calculation_methodstringrequired

The calculation method, derived from fee_rate_type: floating types (2, 7) are "2", and all others are "1".

fixed_ratesarray<string>

Used for fixed rates. Each item has the form { fee_rate }; the value must be non-negative and may have up to 10 decimal places.

ratesarray<string>required

The final rate structure submitted, generated from fixed_rates/single_rates/float_rates/month_rates according to fee_rate_type; each element contains fields such as gt/lte/fee_rate.

currencystringrequired

Currency; values come from the global_currency_filter_by_account_channel dynamic enum, such as USD/HKD/CNH.

Call GET /v1/datasets/refs/tenant_currencies_by_channel to retrieve the current data dictionary, and use the returned entry's key as this field's value.

minstringrequired

This field is required.

maxstringrequired

A numeric string, default 999999999.

max_metricobject

Maximum-ratio limit object { max_metric_type, max_metric_rate }, shown only under specific measurement-type / business-type combinations.

max_metric_typestring

Specifies Max Metric Type.

Values

0: Disabled
1: Enabled

max_metric_ratestring

The rate value when the maximum ratio limit is enabled; multiplied by 100 for display and divided by 100 to restore it upon submission.

granularitystringrequired

Billing granularity, shown only in scenarios such as filled quantity / filled amount.

Allowed values: 1 Calculated per contract (merged), 2 Calculated per order, 3 Calculated per execution record, 4 Calculated per EMS order

Values

1: Contract
2: Order
3: Trade_done
4: Ems_order

min_metricobject

The minimum ratio limit object { min_metric_type, min_metric_rate }.

min_metric_typestring

Expanded from min_metric.min_metric_type.

min_metric_ratestring

Expanded from min_metric.min_metric_rate.

cutoff_methodstringrequired

Rounding method.

Allowed values: 1 Round to nearest, 2 Round up, 3 Round down

Values

1: Round
2: Round Up
3: Round Down

cutoff_digitsstringrequired

The number of rounding digits. Disabled when the rounding method is "Follow Scenario".

Allowed values: 0, 1, 2, 3

Values

0: 0
1: 1
2: 2
3: 3

metric_cycle_typenumber

Measurement-period type. Use 4 for monthly tiers and 0 otherwise. Broker billing always uses 0.

special_feesarray<string>

An array of differentiated rate conditions, filtered by business type (in the agent scenario, conditions whose business type includes 11 are filtered out).

audit_frontend_resourceobject

A frontend form snapshot attached upon submission for backend audit tracing; in the add scenario it is fixed as an add operation.

Responses

HTTP 200The request was processed successfully. The response data does not contain additional business fields.