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.
accounting:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Body fields:
- api_key (string, required): Numeral secret key (
sk_test_…orsk_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
- 201
- 401
- 403
- 422
- 429
Created
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.