Numeral
Test Numeral API Key
Validates an unsaved Numeral secret key live (Numeral `GET /tax/ping`) and reports its mode. Nothing is saved.
Connect Numeral
Connects the account's Numeral account. The key is validated live first — nothing is saved on any failure — then stored encrypted; responses only ever expose its last four characters. Sending sales stays off until it is switched on with Update Numeral Settings. Only one active Numeral connection is allowed per account (422 `already_connected`); reconnecting after a disconnect resumes the previous connection and its history.
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.
Update Numeral Settings
Updates any subset of the connection settings. Keys may be sent flat or nested under `settings`; omitted keys are left unchanged.
Disconnect Numeral
Stops sending sales to Numeral. Sync records are kept as read-only history and nothing is deleted in Numeral. Connecting again resumes this connection.
Replace Numeral API Key
Replaces the stored secret key after validating it live. Clears a previous key error. Switching between a test and a production key re-sends every record to the new account on its next push.
Test Numeral Connection
Re-validates the stored key. Success stamps `last_verified_at` and clears a key error; a rejected key flags the connection (`connection_error: auth_error`) and pauses sending until the key is replaced.
List Numeral Product Categories
Returns Numeral's product category codes (Numeral has no list endpoint; the list is versioned in SKU.io). `meta.version` is the date the list was taken from Numeral's documentation. Use a `code` as a product's `numeral_product_category`.
Get Numeral Connection Status
Whether the account has an active Numeral connection and, if so, its instance id and default product category. Use it to decide whether to offer per-product Numeral tax categories. `instance_id` and `default_product_category` are null when not connected (no connection, or disconnected).
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).
List Numeral Sync Records
Paginated push records — one per sales order (per-order invoicing) or issued sales invoice (other invoicing policies). Amounts are integer minor units in `currency_code`.
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.
Resend Numeral Sync Record
Queues the record to be sent again even if Numeral already holds an identical payload. Refused for an excluded record (422 `record_excluded`).
Exclude Numeral Sync Record
Stops sending this document to Numeral until it is included again. If Numeral accepted (or may hold) it, it is sent once more with every line zeroed, then held (`reason_code` manually_excluded); otherwise it is held right away. Later edits never re-queue it.
Include Numeral Sync Record
Includes an excluded document again: it is queued and sent with its real values.
Retry Numeral Sync Record
Queues the record to be sent again on the next dispatch (within a minute). Resets its attempt count.
Bulk Retry Numeral Sync Records
Queues several records to be sent again — either by id, or every record matching the same filters as List Numeral Sync Records.
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`).
Recalculate Numeral Tax for Sales Order
Prices the sales order with a live Numeral tax calculation again now, even when nothing on the order changed — for example after fixing a ship-to address an earlier calculation refused. Only for orders SKU.io computes tax for itself (manual and B2B portal orders, and orders from channels without their own tax) while live tax calculation (`live_calculation_enabled`) is on and the connection is healthy; otherwise 422. No request body.
Preview Numeral History Send
Counts what sending sales history would send and estimates how long it takes at 15 documents per second. Credits are not sent yet (`credit_count` is always 0).
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`).
Get Numeral Reconciliation
What SKU.io sent to Numeral, aggregated per month × ship-to state, next to what Numeral itself reports for the same cells.
Get Numeral Access Token
The read-only access token this account has given Numeral, masked. `issued` is false when there is none.
Revoke Numeral Access Token
Revoke Numeral's access token; it stops working immediately. Returns the (now empty) token status. Succeeds when there is no token too.
List Numeral Registrations
The sales-tax registrations mirrored from Numeral, and the sync status. Numeral is polled every few hours; rows are created, updated and removed to match it, and they feed the sales-tax registration list and the economic nexus report.
Sync Numeral Registrations
Sync registrations and filings from Numeral now, as a background job. Returns the `tracked_job_log_id` to follow. No request body.
List Numeral Filings
Numeral's sales-tax filings per state and period, newest period first. Served from a cache refreshed by the registration sync; `refresh=1` re-reads Numeral now.