Skip to main content

Numeral

📄️Get Numeral Connection

Returns the Numeral connection: mode, masked key, health (`connection_status` connected | error | disconnected, `connection_error` auth_error | production_key_on_non_production | null), settings (including `live_calculation_enabled` and `live_calculation_enabled_at`, when live tax calculation for SKU.io orders was last turned on), every sales channel with its tax-collection responsibility (`responsibility` is null while the channel is unclassified), whether it is included and its order count since the start date, record counts by status, and `permissions.can_classify_channels` (whether the current user may set a channel's tax-collection responsibility, which requires the `accounting.manage_tax_settings` permission). The API key is never returned.

📄️Get Numeral Summary

Overview of what has reached Numeral. All amounts are integer minor units of the account's base currency (`currency_code`), converted per document with its exchange rate. Includes record counts by status, the last accepted document, problem groups (held / needs action / failed, grouped by reason, largest value first — `sales_minor` is the documents' net sales in minor units, `province_codes` the six most common states, `examples` the two largest records), sent vs not-sent value per state for the current calendar month, and the latest history send (`backfill.status` running | completed | cancelled | failed | null).

📄️Get Numeral Sync Record

One record's detail: the list fields plus the last attempted request and Numeral's response, the last request Numeral accepted, every line id ever sent (lines removed later are re-sent as zero), the SKU.io `document` (customer, channel, ship-to), the `lines` Numeral holds mapped back to SKU.io products and charges, the `tax_context` (responsibility, customer exemption, whether the wholesale flag was sent), `numeral` ids (`order_id`, `mli_id`, and for a live-calculation record `transaction_id`, `calculation_id` — the calculation it was committed from — and `refund_id`, plus `is_live_calculation`), which actions apply (`permissions`) and the activity-log count. Amounts are integer minor units. `filed_period_warning` is set when a change was re-sent into a period Numeral has already filed (see List Numeral Sync Records); it is null otherwise. A sales credit record (`syncable_type` sales_credit) links to the credit and carries negative amounts. The request body never contains the API key.

📄️List Numeral Sync Record Events

The record's activity log, newest first: queued (and by what — order edit, order or invoice event, import / policy / discount change, deletion, history send, reconciliation), accepted / zeroed / rejected / retry scheduled / failed send outcomes (with the request sent and Numeral's response), holds, releases, unchanged settles, live-calculation entries (calculated, committed as a tax transaction, refunded, voided, released to a transaction record when live calculation was turned on), edits re-sent into an already filed period, key pauses and user actions (retried, re-sent, excluded, included) with the user. At most the newest 200 entries are kept per record.

📄️List Numeral Sync Records for Sales Order

The Numeral records of one sales order: the order's own record (per-order invoicing) or its invoices' records, plus the records of its sales credits. Each record has the same fields as List Numeral Sync Records, including `filed_period_warning`. `data` is empty and `meta.connected` false when Numeral is not connected. `meta.live_calculation` reports live tax calculation for the order: `enabled` (the setting is on), `active` (a calculation can be requested now — on, connected and the key accepted), `applies` (SKU.io computes this order's tax itself, so live calculation is used for it) and `calculation` — the order's latest calculation or null: `status` calculated | fallback (Numeral refused the address; the order keeps its own tax) | failed (any other error), `is_fallback`, `calculation_id`, `expires_at` / `is_expired` (an uncommitted calculation expires and is recalculated before it is committed), `calculated_at`, `currency_code`, `currency_exponent`, `total_amount_minor`, `total_tax_minor`, `error_type`, `error_message`, the `origin` and `ship_to` addresses sent, and `lines` (each with `reference`, `kind` sol (order line) or fl (charge), `source_id`, `amount_minor`, `quantity`, `tax_minor`, `product_category`).

📄️Send Numeral Sales History

Starts a background send of every reportable sale dated on or after `start_date` (named 'Numeral: send sales history (since YYYY-MM-DD)'). Live changes are always sent before history. Moves the connection start date earlier when needed. Cancelling the background job holds every not-yet-sent history record (reason backfill_cancelled); records already sent stay sent. Sending must be switched on first (422 `push_disabled`). Only one history send runs at a time (422 `backfill_running` with the running `tracked_job_log_id`).