Sample call

{
  "rest_call": "get_surcharge_details_m",
  "output_format": "json",
  "client_no": 100234,
  "auth_key": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "surcharge_no": 30045
}

The rest_call and output_format fields are REST-layer envelope fields that Knowledge Central adds on top of the method’s own documented arguments; they are not part of the yml’s arguments block itself, but every REST call to this method requires them. The client_no and auth_key fields are required for every Admin Tools API call and identify the Aria client and the requestor making the call.

The method identifies the surcharge to look up using either surcharge_no or client_surcharge_id, which are declared as an alternative-field pair; you provide one, not both. This example uses surcharge_no, the Aria-assigned numeric identifier, rather than client_surcharge_id, the client-defined identifier, because a numeric identifier is the more common way to reference a surcharge once you already know it. The optional locale_name, locale_no, and include_translations fields are left out of this call because this example does not request translated text.

Sample response

{
  "error_code": 0,
  "error_msg": "OK",
  "surcharge_no": 30045,
  "surcharge_name": "International Transaction Surcharge",
  "client_surcharge_id": "INTL-TXN-SURCHARGE",
  "description": "Additional surcharge applied to transactions processed in a foreign currency.",
  "ext_description": "International Transaction Fee",
  "currency_cd": "USD",
  "surcharge_type_cd": "V",
  "inline_offset_ind": "O",
  "tax_group": 200,
  "gl_cd": "4200-INTL",
  "ar_gl_cd": "1200-AR",
  "apply_b4_or_after_discount_cd": "A",
  "scope_no": 5,
  "surcharge_rate_schedule_details": [
    {
      "schedule_no": 8801,
      "schedule_name": "International Transaction Tiered Schedule",
      "schedule_currency": "USD",
      "default_ind": 1,
      "include_zero": 0,
      "comments": "Default tiered rate schedule for international transaction volume.",
      "surcharge_rate_schedule_rates": [
        {
          "rate_seq_no": 1,
          "from_unit": 1,
          "to_unit": 1000,
          "rate_per_unit": 2.5,
          "rate_tier_description": "First 1,000 units"
        },
        {
          "rate_seq_no": 2,
          "from_unit": 1001,
          "to_unit": 5000,
          "rate_per_unit": 2,
          "rate_tier_description": "Next 4,000 units"
        },
        {
          "rate_seq_no": 3,
          "from_unit": 5001,
          "to_unit": null,
          "rate_per_unit": 1.5,
          "rate_tier_description": "Over 5,000 units"
        }
      ]
    }
  ],
  "plan_service": [
    {
      "plan_no": 20101,
      "service_no": [500]
    },
    {
      "plan_no": 20205,
      "service_no": [512]
    }
  ],
  "surcharge_scope": 3,
  "tax_inclusive_ind": 0,
  "installment_surcharge_ind": 0
}

An error_code of zero, together with an error_msg of “OK”, indicates that Aria found and returned the surcharge successfully. The surcharge_type_cd value of V means this is a volume percentage discount, one of three possible codes; F means a fixed discount and S means a standard percentage discount. The inline_offset_ind value of O means the surcharge appears as its own separate line item on the invoice, rather than being folded into the original line item, which is what a value of I would mean. The apply_b4_or_after_discount_cd value of A means Aria calculates this surcharge after other discounts are applied to the underlying charges, rather than before, which is what a value of B would mean.

The scope_no value of five means this surcharge applies to specified plan and service charges, one of twelve possible scope values Aria defines for surcharge eligibility. Because scope five ties the surcharge to particular plan-and-service combinations, the response includes the plan_service array, which pairs each eligible plan with the service or services tied to it; here the surcharge applies to service 500 under plan 20101 and to service 512 under plan 20205. Although the yml nests service_no under plan_service as a further mapping, that mapping contains only a single nested key of the same numeric-array shape used elsewhere in this method, so it represents a flat array of service numbers per plan, such as "service_no": [500], rather than an array of one-key objects. The surcharge_scope field is a separate, unrelated concept from scope_no: it is available only for Aria clients configured on the End of Month (EOM) billing model, and its value of three here means the surcharge can be applied to an account or to a master plan instance, rather than to only one or the other.

The surcharge_rate_schedule_details array, added in release seventy-three, describes the tiered rate schedule backing this volume-based surcharge. This example shows one schedule with three representative rate tiers; a surcharge could have additional schedules, for example one per currency, and each schedule could have additional tiers beyond the three shown here. The final tier’s to_unit is null because that tier is open-ended, covering every unit above 5,000. The tax_inclusive_ind value of zero means the surcharge amount is exclusive of tax, and the installment_surcharge_ind value of zero means the surcharge is not spread over an installment period when the underlying item is purchased on installments.

This example leaves out several fields entirely. The legacy surcharge_tier array, which described tiered pricing before the newer surcharge_rate_schedule_details structure existed, is omitted because this example already illustrates tiering through the newer field. The plan_no, client_plan_id, service_no, client_service_id, item_no, and client_sku fields, which are alternative ways of specifying scope-eligible plans, services, or items for other scope values, are omitted because the plan_service array already covers the plan-and-service pairing this scope-five example needs. The pay_method field is omitted because it only applies when scope_no is eleven, for surcharges scoped to a payment method, which is not the case here. The client_item_id field is omitted because it carries a deprecate_version of 43 in the yml and is no longer the recommended way to reference inventory items; client_sku replaced it. The apply_to_zero_invoice_ind field is omitted for the same reason, carrying a deprecate_version of 11.1. Finally, the surcharge_translation_details field, along with its nested surcharge_tier_t and surcharge_rate_schedule_t translation structures, is omitted because this call does not request translations.