API changelog and compatibility

ARC does not use a date-versioned GraphQL URL today. The live endpoint remains /graphql, and the generated reference is rebuilt from the current code-first schema at every docs deployment.

That makes the committed schema snapshot and this changelog important to integration owners:

• apps/api/src/schema.gql is generated by NestJS at API boot and is not hand-edited;
• /api/graphql is generated from that snapshot;
• deprecated fields remain visible with their replacement until they are removed;
• breaking changes are recorded on this page.

What to pin in your integration

1. Pin a schema snapshot or generated client version in your build.
2. Run GraphQL validation/code generation in CI against the schema you target.
3. Prefer additive field selection and named operations.
4. Treat a deprecated field as migration work, not as an invitation to ignore the warning.
5. Keep a compatibility test for each critical flow: catalog read, price resolution, quote/order create, and reconciliation.

What counts as a breaking change

Examples include removing or renaming a field/type, changing a required input, changing an enum in a way your client cannot handle, or changing a nullable field to non-null. A new optional field is generally additive, but your client should still tolerate unknown response fields.

Business behavior can also change without a GraphQL type change. Permission changes, plan gates, document state rules, pricing configuration, and tenant settings are runtime contracts; read the relevant guide and handle domain error codes.

When a change reaches your workspace

Entries are dated when a change is released. Workspaces are updated in waves, so a change can reach yours some days later. If a route listed here answers 404 with Cannot GET … (or Cannot POST …) on your host, your workspace has not received it yet; the rest of the API is unaffected. Ask your Growmax account manager if you need a date.

How this page is maintained

This page is written by hand. No CI job writes to it. The Growmax team adds an entry when a schema change or a docs release affects integrators. Entries are listed newest first. For the exact current schema, use the generated reference or download the public schema (see GraphQL API).

2026-10-20 — Cancel a bulk import from the Service API; import file format documented

Added:

• POST /api/service/products/bulk/:importId/cancel cancels an import that has not started committing and frees the workspace's single import slot. Before, an abandoned API import stayed active until a staff user cancelled it. See Cancel an import.
• The import file format: required and optional columns, accepted header names, price tiers and attributes.

Changed:

• The bulk-import create and approve bodies are validated: a missing filename or an unknown mode / modeOverride is now refused with 400 (it used to fail with 500), and fields the route does not define are ignored.

2026-10-20 — Service API write responses use the documented shape

Changed (may affect running integrations):

• POST /api/service/sales-quotes and POST /api/service/sales-orders now return the created document in the same shape as GET /api/service/sales-quotes/:id and GET /api/service/sales-orders/:id, instead of the internal record. Fields that were never documented — including internal notes, audit and user ids, nested product and variant records, and the creating user's and workspace's records — are no longer returned. The documented id, document number, status, totals, currency and lines are unchanged. If your integration read any other field, read it from the GET route's fields instead.
• GET /api/service/products/bulk/:importId now returns the import's status, counts and timestamps only; storage keys and user ids are no longer returned.

2026-10-20 — Service API read endpoints; per-key rate limit enforced

Added (additive; no GraphQL schema change):

• Read endpoints on the Service API, open to a tenant API key of either scope (READ_ONLY or READ_WRITE). A key reads as the user who created it, so each route needs that user's current read permission: GET /api/service/products, products/:id, uoms, payment-terms, warehouses, stock, customers, customers/:id, sales-orders, sales-orders/:id, sales-quotes and sales-quotes/:id. Lists page with limit (1 to 100, default 50) and cursor, and support delta pulls with updatedAfter. See Read endpoints.
• An integration no longer needs a staff user to look up customers, products, units or payment terms before creating a quote or order. See Make your first service API request.

Changed (may affect running integrations):

• Each API key's rateLimit (requests per minute, 100 by default, an integer from 1 to 10000) is now enforced per key across every /api/service/* route. Responses to key requests carry X-ApiKey-RateLimit-Limit, X-ApiKey-RateLimit-Remaining and X-ApiKey-RateLimit-Reset. Over the limit, ARC answers HTTP 429 with code API_KEY_RATE_LIMITED, retryAfterSeconds and a Retry-After header. A connector that sends more than its key's limit in a minute now gets refusals; pace it, or create a replacement key with a higher rateLimit. See Rate limits and request limits.

2026-10-20 — Developer docs release

New pages:

• Webhooks: endpoint setup, signature verification, retries and replay, and the event catalog.
• Environments, hosts and test data.
• Rate limits and request limits.
• Error reference: what errors look like on the GraphQL and REST wires, and the codes to handle.
• A downloadable public schema, /schema/arc-public.graphql, for code generation and query validation.

Deprecated in the current schema (still present; plan to migrate):

Field	Type	Reason
createInternalReturn	Mutation	Internal returns are not supported; move stock between warehouses with a stock transfer (transferInventory).
deleteInvoice	Mutation	Invoices are cancelled, never deleted. Use cancelInvoice. This mutation always refuses.
enrichProduct	Mutation	Blocks the request for about 140 seconds and exceeds the client HTTP timeout. Use startProductEnrichment and productEnrichmentJob.
receivePurchaseOrder	Mutation	Direct receiving is disabled; create a GRN (createGRN) to receive against a purchase order.
taxGroupId	Product	Use taxGroupIds instead.
taxRateId	Product	Use taxRateIds instead.

2026-07-30 — Baseline

• Schema baseline: commit 030291be on staging.
• Later entries appear above this one, newest first.

Before a production upgrade

• regenerate client types from the current schema;
• run a read-only contract test against the target tenant;
• exercise one idempotent create in a non-production tenant;
• inspect changed/deprecated fields in the changelog and reference;
• verify authentication, permissions, pagination, and error handling;
• record the schema commit/reference version with your release.

If your integration requires a long-lived compatibility window or a versioned endpoint, contact your Growmax account manager before building around an undocumented route.