Orders

Orders are the heart of the Chargee Order API. Everything else — auth, sync, import, rate limits, Sparky linking — exists to make order creation and fulfillment tracking reliable for a merchant account.

All order routes require a Bearer JWT and live under /api/v1/orders.

Endpoints

Local orders (preferred for apps)

Monta passthrough (diagnostics; does not update local state)

What an order is here

An order is Chargee’s local record of a warehouse job identified by a webshop order id. That id is how your commerce world and Monta’s world stay aligned. Chargee enforces ownership: the id belongs to one Order API user, and it must not collide with another merchant’s claim.

Locally, Chargee tracks a simplified status lifecycle. Orders typically move from pending into processing as warehouse activity progresses, and into fulfilled when shipping signals are clear. They may also become cancelled or error when Monta indicates those outcomes. Exact mapping from Monta’s richer signals (picked, shipped, track-and-trace, cancelled, and related flags) is Chargee’s responsibility during create, sync, and import.

Creating

POST /api/v1/orders is a forward operation: Chargee asks Monta to accept the order using your stored warehouse credentials, then stores a local copy. The local copy is what you will list and sync later. Uniqueness is checked up front so Chargee does not create confusing double-ownership situations after Monta has already been called.

Keeping local truth fresh (sync)

Monta’s status changes over time as the warehouse works. POST /api/v1/orders/{webshopOrderId}/sync pulls fresh order detail and serial numbers into the local record, remaps status, and clears any “stop auto-syncing this stale order” backoff that may have been applied. Chargee also runs background sync on a schedule so many orders stay reasonably fresh without you polling. Manual sync remains available when you need an immediate refresh — including for orders that background sync has paused because they stayed unfulfilled for too long.

Sync is the usual moment when serials (box codes) appear. Those codes matter for device linking.

Bringing history in (import)

POST /api/v1/orders/import exists for merchants who already have orders in Monta before they adopt Chargee’s local model. Chargee walks Monta’s list, skips work owned by other Order API users or already fully held locally with serials, and upserts the rest into your account. Import is interruptible: rate limits or an explicit processing ceiling can stop a run early so you can continue later. Imported rows may lack the original “created via API” payload; they are still first-class local orders for listing and sync (GET /api/v1/orders, GET /api/v1/orders/{webshopOrderId}).

Background sync does not invent missing local rows for brand-new Monta orders you never created or imported. New work enters Chargee through create or import.

Two ways of looking at Monta

Local orders (/api/v1/orders…) are Chargee’s application state: owned, listable, syncable, and eligible for Sparky linking. Direct Monta views (/api/v1/orders/monta…) let you inspect warehouse data through Chargee without updating that local state. Prefer local orders for product behavior; use direct views when you need a raw warehouse perspective.

What happens when an order fulfills

The first time local status becomes fulfilled and box codes are available, Chargee may attempt to link each Sparky to the merchant’s Amber group. That is a platform side effect of sync, not a separate integration endpoint you must call for the default path. Linking outcomes are recorded server-side; your main job remains creating, syncing, and reading orders.

Design takeaway

Model your integration around owned local orders, use sync for freshness, use import for history, and treat fulfillment linking as Chargee’s concern once serials exist. That matches how the system is built and avoids fighting ownership, rate limits, and warehouse timing.