IoneShop Developers

API architecture

Surfaces

SurfaceStatusUse when
REST /v1Available (public beta)Almost all integrations
WebhooksAvailableNear-real-time sync without polling
GraphQLIn developmentFlexible queries (same auth/scopes as REST when shipped)
Async jobsExpandingLarge imports, bulk updates, exports

GraphQL is currently in development and is not a public endpoint yet. Integrate against REST /v1 + webhooks now.

Prefer webhooks + incremental pull over aggressive polling.

Base URLs

Production:  https://api.ioneshop.cloud/v1/
Sandbox:     https://sandbox-api.ioneshop.cloud/v1/

JSON request/response bodies use snake_case in public partner APIs (unless noted). Timestamps are ISO-8601 UTC (2026-08-01T12:00:00Z). Money fields use integer minor units plus currency (ISO 4217), e.g. { "amount": 1999, "currency": "EUR" } = €19.99.

Versioning

/v1/...
/v2/...

Compatibility rules

  1. Additive changes inside /v1 are non-breaking: new optional fields, new endpoints, new enum values (clients must ignore unknown fields).
  2. Breaking changes require /v2 (or a negotiated Enterprise private version).
  3. Deprecation: minimum 180 days notice for stable endpoints; changelog + migration guide required.
  4. Deprecated endpoints return header Deprecation: true and Sunset: <HTTP-date> when a removal date is set.
  5. Sandbox may receive preview flags earlier than production (X-IoneShop-Api-Preview: <name>).

Migration guides

Each major version ships:

  • Diff of resources and field renames
  • Parallel-run window (call both versions)
  • Cutover checklist
  • Sunset date

Request identity

Every response includes:

X-Request-Id: req_01JABCDEF...

Echo this ID in support tickets and integrator logs.

Tenant context

API credentials are bound to a single tenant. You never pass tenant_id to “select” another shop. Cross-tenant access returns 403 (TENANT_MISMATCH or equivalent) or 401.

Enterprise multi-store operators use one credential set per store. A future OAuth multi-tenant app grant (when OAuth ships) may allow explicit shop selection in consent — never shared database credentials.

Response envelope

  • Lists: { "data": [ … ], "pagination": { "limit", "next_cursor", "has_more" } }
  • Single resources: { "data": { … } }
  • Errors: { "error": { "code", "message", "request_id", … } } — see Error handling

GraphQL (in development)

REST + webhooks cover ERP/WMS/n8n reliably today. GraphQL is being built as a complementary surface; it will share the same auth, scopes, rate limits, and idempotency rules. Watch the changelog for sandbox preview availability.