Add Charging Scene

Creates a billing scenario (billing item) configuration.

Request parameters

Required: biz_type (business type), name_id (fee-type ID), basis_type (basis type), basis (basis value), direction (charge direction), divisor, metric_type (metric method), granularity (metric granularity), cutoff_method (cutoff method), cutoff_digits (cutoff digits). The backend reads only these top-level fields; basis_object and cutoff_object are the console form structure and can be omitted
Optional: metric_type_bill_amount_item_ids (secondary billing-item ID list), benchmark_rate (benchmark rate formula)
See the field descriptions for the format, value range, and business meaning of each field.

Business notes

The allowed values of most fields narrow according to biz_type; the actual allowed values and defaults follow the per-business-type field rules returned by GET /billing/item_fields, and the candidate list for name_id comes from GET /billing/billing_item_name (queried by biz_type). A submitted billing item takes effect only after approval.

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/billing_item

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

biz_typestringrequired

Value from the billing_business_type_all reference data. It determines dependent options such as billing method and billing party.

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

name_idstringrequired

Load options from the names list returned by GET /billing/billing_item_name?biz_type=<biz_type> for the selected biz_type.

basis_objectobject

Deprecated: console form structure, ignored by the backend; send the top-level fields instead.

Structured object in the form { basis_type, basis }. See x-enum-details for the basis_type values (market, currency, or instrument). For basis, use global_market reference data for markets, tenant_currencies_by_channel reference data for currencies, or free text for instruments.

Allowed values: 1 Market, 2 Currency, 3 Instrument (for basis_type)

Child attributes

basis_typestring

Basis type; see this object's description for values (1 Market, 2 Currency, 3 Instrument).

Values

1: Market
2: Currency
3: Instrument

basisstring

Concrete basis value (market, currency, or instrument).

basis_typestringrequired

Billing basis type. This is the field the backend reads; basis_object is only the console form structure and is ignored.

Values

1: Market
2: Currency
3: Instrument

basisstringrequired

Billing basis value. This is the field the backend reads; basis_object is only the console form structure and is ignored. For basis_type 1 (market) use a value from the global_market dictionary, for 2 (currency) one from tenant_currencies_by_channel, and for 3 (instrument) the instrument code itself, such as ST/HK/700.

directionstringrequired

Value from the billing_item_direction reference data. The allowed values are determined by the field rules returned by GET /billing/item_fields for the selected biz_type.

Allowed values: 1 Matches buy orders / transfer-out / no direction, 2 Matches sell orders / transfer-in, 3 Matches all

Values

1: Match Trade Buy/Transfer Out/No Direction
2: Match Trade Sell/Transfer In
3: Match All

divisorstringrequired

Dropdown options are filtered by biz_type. The allowed values are determined by the field rules returned by GET /billing/item_fields for that business type.

metric_typestringrequired

Value from the billing_metric_type reference data. The allowed values are determined by the field rules returned by GET /billing/item_fields for the selected biz_type.

Allowed values: 1 Traded quantity (fractional shares supported), 2 Traded amount / other 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/Other 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

metric_type_bill_amount_item_idsarray<string>

Required only when metric_type is set to secondary billing based on existing. Values come from a backend data dictionary (maintained dynamically), not a fixed enum; use the options the service actually returns.

granularitystringrequired

Value from the billing_granularity reference data. The allowed values are determined by the field rules returned by GET /billing/item_fields for the selected biz_type.

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

benchmark_ratestring

Show and submit this field only when the selected biz_type supports benchmark-rate configuration. The allowed values follow GET /billing/item_fields; enter a numeric value with up to 10 decimal places.

cutoff_objectobject

Deprecated: console form structure, ignored by the backend; send the top-level fields instead.

Structured object in the form { cutoff_method, cutoff_digits }. See x-enum-details for the cutoff_method values.

Allowed values: 1 Round to nearest, 2 Round up, 3 Round down (for cutoff_method)

Child attributes

cutoff_methodstring

Cut-off method; see this object's description for values (1 Round to nearest, 2 Round up, 3 Round down).

Values

1: Round
2: Round Up
3: Round Down

cutoff_digitsstring

Number of digits kept when cutting off.

cutoff_methodstringrequired

Cutoff method. This is the field the backend reads; cutoff_object is only the console form structure and is ignored.

Values

1: Round
2: Round Up
3: Round Down

cutoff_digitsstringrequired

Cutoff digits. This is the field the backend reads; cutoff_object is only the console form structure and is ignored. Allowed digits follow the item_fields rules; other values fail with cutoff_digits not allow value.

audit_frontend_resourceobject

Caller-provided audit context object.

Responses

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

Standard response envelopecodemessagedata

dataobjectdata structure

idstring

created_atstring

updated_atstring

biz_typeobject

account_channelobject

Account channel

Child attributes

idstring

account_channelstring

basis_typeinteger

Basis type

basisstring

Basis

metric_typeinteger

Metric type

directioninteger

Direction

config_typeinteger

Config type

name_idstring

Name id

coefficientinteger

Coefficient

divisorinteger

Divisor

cutoff_methodinteger

Cutoff method

cutoff_digitsinteger

Cutoff digits

fee_rate_typeinteger

Fee rate type

nameobject

Child attributes

idstring

name_zhstring

name_enstring

biz_typeinteger

notestring

name_zh_hkstring

codestring

granularityinteger

account_channel_v2string

HTTP 400Bad request. Check the business error code in code and the error details in message.

Standard response envelopecodemessagedata

dataobjectdata structure

No nested fields

HTTP 401The user is not authenticated, or the login session has expired.

Standard response envelopecodemessagedata

dataobjectdata structure

No nested fields

HTTP 403The current account is not authorized to use this feature. Grant the required permission to the account in User Permission.

Standard response envelopecodemessagedata

dataobjectdata structure

No nested fields

HTTP 408The request timed out. Check the business error code in code and the error details in message.

Standard response envelopecodemessagedata

dataobjectdata structure

No nested fields

Request

curl --request POST \
  --url 'https://b-api.lbkrs.com/billing/billing_item' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json'
  --data '{
  "biz_type": "1",
  "name_id": "100",
  "basis_type": "1",
  "basis": "HK",
  "direction": "1",
  "divisor": "1",
  "metric_type": "1",
  "metric_type_bill_amount_item_ids": [],
  "granularity": "1",
  "benchmark_rate": "0.001",
  "cutoff_method": "1",
  "cutoff_digits": "2"
}'

Response

{
  "code": 0,
  "message": "success",
  "data": {}
}