Skip to main content

List Numeral Sync Records

GET 

/api/numeral/instances/:instance/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.

Required scope: accounting:read

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Statuses: pending (queued), synced (sent), held (deliberately not sent yet: unclassified_channel, excluded_channel, before_start_date, backfill_cancelled, manually_excluded, awaiting_live_calculation, awaiting_order_close, awaiting_original_transaction), needs_action (missing_country, missing_address, missing_region, invalid_region, missing_postal_code, unknown_currency, numeral_validation, mixed_invoice_context, address_invalid, changed_after_refund), failed (retries_exhausted), skipped (not_reportable, cancelled_never_sent, invoiced_separately, no_lines, deposit_invoice, sent_as_transaction). currency_exponent is the minor-unit exponent of currency_code.

Record types (syncable_type): sales_order, sales_invoice and sales_credit are sent as manual line items. When live tax calculation is on (live_calculation_enabled), orders SKU.io computes tax for itself are committed through Numeral's transactions API under their own types instead, with is_live_calculation true: order_transaction (a per-order invoiced sales order, committed when the order closes), invoice_transaction (each issued invoice of any other invoicing policy) and credit_refund (a sales credit on such an order, sent as a Numeral tax refund once the sale it refunds is committed). Their numeral_transaction_id (and numeral_refund_id for a refund) hold Numeral's ids; both are null for manual-line-item records. Hold reasons for these: awaiting_live_calculation (live calculation is off — its manual-line-item twin is skipped as sent_as_transaction once it is on), awaiting_order_close, awaiting_original_transaction.

Sales credit records (syncable_type sales_credit) send a refund as negative lines under the original document's Numeral order id, so their sales_minor / taxes_minor are negative. filed_period_warning is null unless the document was changed and re-sent into a period Numeral has already filed; it then holds message, filing_id, filing_status, country_code, region_code, period_start, period_end, document_date and flagged_at — Numeral reflects such a change on the next filing for that state, so the filed return will not match SKU.io.

Filters: filter[status], filter[syncable_type] (sales_order, sales_invoice, sales_credit, order_transaction, invoice_transaction, credit_refund), filter[sales_channel_id], filter[reason_code] (comma-separated lists accepted), filter[is_backfill], filter[date_from] / filter[date_to] (document date, Y-m-d or m/d/Y), filter[search] (document number or Numeral order id). Operator filters are also accepted for id, sales_channel_id (numeric), syncable_type, document_number, status, reason_code, currency_code, country_code, province_code (text), sales_minor, taxes_minor, attempts (numeric), marketplace, edited_after_push (checkbox), document_date (date), last_pushed_at, created_at, updated_at (datetime).

Allowed sorts: id, created_at, updated_at, document_date, last_pushed_at, sales_minor, taxes_minor, status, document_number (prefix with - for descending; default -updated_at). Pagination: page, per_page (default 10, max 500).

Authentication: Requires a Bearer token. Requires the integrations.sync permission.

Request​

Responses​

OK

Response Headers
    Content-Type