create_surcharge_m Sample Call and Response
This example shows a client creating a volume percentage surcharge that offsets fluctuating fuel costs, tiered by unit volume and applied to two specified plans. It is based on the create_surcharge_m method as defined in methods_m_r73.yml, Admin Tools API.
This example includes every required field, plus a representative set of optional fields covering general ledger coding, a plan scope, one rate schedule, and tax handling. It does not attempt to show every optional field the method accepts, such as the fields that apply only to service-scoped or item-scoped surcharges.
Sample call
{
"rest_call": "create_surcharge_m",
"output_format": "json",
"client_no": 700123,
"auth_key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"surcharge_name": "Fuel Adjustment Surcharge",
"client_surcharge_id": "SUR-FUELADJ-001",
"description": "Surcharge applied to offset fluctuating fuel costs on delivery-related plan charges.",
"ext_description": "Fuel adjustment surcharge",
"surcharge_type_cd": "V",
"inline_offset_ind": "O",
"apply_b4_or_after_discount_cd": "A",
"tax_group": 205,
"gl_cd": "4000-SUR",
"ar_gl_cd": "1200-AR",
"scope_no": 3,
"plan_no": [10021, 10034],
"surcharge_tier": [
{
"from": 1,
"to": 10,
"rate": 0.5,
"description": "First ten units"
},
{
"from": 11,
"rate": 0.75,
"description": "Eleventh unit and beyond"
}
],
"schedule": [
{
"schedule_name": "Standard USD Schedule",
"currency_cd": "usd",
"is_default": 0,
"min_surcharge_to_apply": 5.00,
"include_zero": 1
}
],
"surcharge_scope": 3,
"tax_inclusive_ind": 0,
"installment_surcharge_ind": 0
}
The rest_call and output_format fields are not part of the method’s own documented arguments. The REST layer adds them to every call: rest_call names the method being invoked, and output_format requests a JSON response rather than the default WDDX format. Within the method’s own arguments, client_no and auth_key identify and authenticate the client making the call. The required fields are surcharge_name, description, ext_description, surcharge_type_cd, inline_offset_ind, apply_b4_or_after_discount_cd, scope_no, and surcharge_tier. surcharge_type_cd is set to "V" for a volume percentage surcharge, one of three values alongside "F" for a fixed surcharge and "S" for a standard percentage surcharge. inline_offset_ind is set to "O," meaning the surcharge appears as its own separate line item on the invoice rather than folded into the original line items. apply_b4_or_after_discount_cd is set to "A," meaning the surcharge is calculated after discounts are applied. scope_no is set to three, "All Plan Charges, Specified Plans," which is one of the two scope values that make plan_no (or its alternative, client_plan_id) required; this example supplies plan_no, the Aria-assigned plan numbers, rather than client_plan_id. Because the scope does not involve services or items, service_no, client_service_id, item_no, and client_sku are all left out. surcharge_tier is a required, repeatable group representing the rate tiers, shown here as an array of two tiers: the first spanning units one through ten at a rate of 0.5, and the second beginning at unit eleven with no upper bound, since the "to" field is only mandatory except on the last tier. schedule is an optional, repeatable group; this example includes one schedule entry, with is_default set to zero, which per the method’s own value definitions means this schedule is taken as the default for its currency, and include_zero set to one, meaning zero-amount tiers are included in the schedule. surcharge_scope, available only for European, Middle Eastern, and African (EOM) clients, is set to three, meaning the surcharge can be applied to both the account and a master plan instance. tax_inclusive_ind is set to zero, its default, meaning the surcharge amount is tax exclusive, and installment_surcharge_ind is set to zero, meaning the surcharge is not spread over an installment period. This example leaves out currency_cd and apply_to_zero_invoice_ind, both of which carry a deprecate_version in the yml, and client_item_id, which also carries a deprecate_version.
Sample response
{
"error_code": 0,
"error_msg": "OK",
"surcharge_no": 61230
}
An error_code of zero, paired with an error_msg of “OK,” indicates that Aria created the surcharge successfully. The surcharge_no field returns the Aria-assigned unique identifier for the new surcharge. The method’s returns block consists only of these three fields, so there is no additional output to show.