Skip to main content

Connect Numeral

POST 

/api/numeral/instances

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.

Required scope: accounting:write

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

Body fields:

  • api_key (string, required): Numeral secret key (sk_test_… or sk_prod_…).
  • attested_no_direct_channels (boolean, required, must be true): confirms no sales channel is connected directly inside Numeral (a direct connection would double-count those sales).

Returns 201 with the connection. Numeral failures return 422 with a stable code: invalid_key (Numeral did not recognise this key), production_key_refused (a production key on a non-production SKU.io), rate_limited, api_error (Numeral refused the request; message carries its reason) or unreachable (Numeral could not be reached).

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

Request​

Responses​

Created

Response Headers
    Content-Type