Read one Sume usage row: list, model and agent fee micros

Every captured Sume charge stores its own proof. Under pricing_units you will find price_book_list_usd_micros, price_book_model_usd_micros, price_book_agent_fee_usd_micros and price_book_agent_fee_bps. List x 1.25 should equal the model field, and the fee field should be 5.5% of the model field.

Where the fields live

The four fields sit in capture_metadata.pricing_units on the usage row. If a capture has no metadata, the reservation's reservation_metadata.pricing_units is the fallback. The Usage page, the CSV export, invoice lines and the commitment card all read the same fields, so the numbers you see in one place match the others.

price_book_agent_fee_bps is 550 by default, meaning 5.5% in basis points.

Check a row by hand

Micros are millionths of a dollar. Suppose a row shows a list value of 1,000,000. That is $1.00. The model field should read 1,250,000, and the fee field should read 68,750. The charge is their sum, 1,318,750 micros, or $1.31875.

Pull the ledger

The public API returns usage ledger entries: reservations, captures, refunds and top-ups. This is the call from the cookbook:

curl https://api.sume.com/v1/usage \
  -H "Authorization: Bearer $SUME_API_KEY"

When the numbers do not add up

If a capture was clipped to its hold, the row carries price_book_clipped_to_hold: 1 and settlement.over_ceiling_usd_micros records how much was left uncollected. In that case the charge is lower than list x 1.31875 because the hold capped it. This is the one routine reason a row will not reconcile.

Discounts are the other. If your org has custom terms, the discount comes off before the 1.25 step, so the list field will be higher than the model field divided by 1.25.

Which readers use the fields

The same four fields feed every place a charge appears. Usage shows the per-row amounts. The CSV export carries them into a spreadsheet, where you can total each column and check that the fee column is 5.5% of the model column. Invoice lines are built from the same rows, and the commitment card reads them to show spend against a commitment.

Because they share one source, a disagreement between two screens is not a pricing difference. It is usually a filter, such as a date range or a job id, that differs between the two.

A reconciliation recipe

To audit a month, export the CSV and add up three columns: list, model and fee. The model total should be 1.25 times the list total for every SKU that has a vendor list price. The fee total should be 5.5% of the model total.

Rows that fail the test are the interesting ones. They are either clipped to a hold, discounted by custom terms, or one of the services that keep their own price: Fastlane and HumanPost are not multiplied by 1.25. Free services, such as voice clone, have all-zero rows and appear as zeros in every column.