Store apps
A store app is a store platform (or a connector to one, or a merchant's own shop) that works as one of the organization's stores: it sends its orders, and from there they go through everything an order of a Shopify or WooCommerce store goes through (the import rules, the checks, the delivery choice, the AWB, the invoice, the automations).
What it takes
Section titled "What it takes"- What the app provides: Store (sends orders), on Details (what the app provides).
- The scopes:
write_ordersto send the orders, andread_ordersto read them back (the reconciliation, the order webhooks).write_ordersis asked only together with what the app provides (scopes), and granted only by someone who may manage integrations in the organization. The approver sees both: sending orders and reading them are granted apart. - The store section (a public app): the app is listed under Stores, as its primary or its secondary section.
All of it is versioned like the rest of the app, and reviewed for a public app.
A private store app
Section titled "A private store app"A merchant's own shop (or a platform an agency connects for one client) is a private app providing Store (sends orders): no store listing, no section, no review. Once an administrator of its organization approves it through its install link, its server takes a token with client credentials and sends its orders with POST /v1/orders, exactly as below:
curl -X POST "https://connectato.com/oauth/token" \ -d grant_type=client_credentials \ -d client_id="$CLIENT_ID" \ -d client_secret="$CLIENT_SECRET" \ -d scope="write_orders read_orders"Installation
Section titled "Installation"Installing the app adds a store to the organization: an integration of category store, named after the app, shown in My applications and on every order it sends. Its id (int_...) is the integration_id of those orders in GET /orders, and caller.store on GET /organization names it.
One installation is one store: an app is installed once per organization, so there it sends the orders of one store.
| The store is | What a send answers |
|---|---|
connected |
The order is taken in. |
paused (by the merchant) or disabled (on hold: the app suspended, or a permission missing) |
409 integration_paused: nothing is stored. Send the orders again once it is connected. |
| disconnected (the capability no longer provided) | 403 not_a_store. Its orders stay in the organization. |
| uninstalled | 401: the installation's tokens are refused. Its orders stay in the organization. |
An app installed without what it provides is answered 403 not_a_store on every send; an app without write_orders (or a private app's token asked without it) is answered 403 insufficient_scope.
The store
Section titled "The store"GET /v1/organization{ "id": "org_01jcq2b8h4n6r0t5v9x3z7k1mp", "name": "Test ERP", "timezone": "Europe/Bucharest", "caller": { "scopes": ["write_orders", "read_orders"], "app_id": "9d3f6a52-7c1e-4b8a-a0f2-5e6c7d8b9a10", "store": { "integration_id": "int_01jcq4m5x2v7k9t3r8n6p0w1yz", "status": "connected", "import_cutoff_date": "2026-11-16" } }}caller.store is the store the app is in this organization, null for an app that provides no store. It needs no scope, like the rest of GET /organization.
import_cutoff_date is the cut-off: orders placed before that day (from the organization's midnight) are not imported. Until the merchant sets one, it is the day the store was installed, so the store's history stays out. The merchant may move it earlier in the store's Import settings; read it before sending the history. null takes every order.
Sending an order
Section titled "Sending an order"POST /v1/ordersexternal_id, in the body, is the app's own id of the order: required, at most 255 characters, no comma (a list filter separates ids with one), matched exactly (letter case included). It is the order's identity in the store: sending it again updates the same order, never makes a second one. The app never needs our id to send: a first send, a retry, a change and a resend after the reconciliation are the same call.
The whole order every time. Every field replaces what is held (lines, addresses, totals); there is no partial update. A cancellation is the order sent again with source_state cancelled.
{ "external_id": "1001", "number": "1001", "source_state": "active", "source_status": "processing", "fulfillment_status": "unfulfilled", "test": false, "currency": "RON", "prices_include_tax": true, "totals": { "subtotal": "100.00", "discount": "0", "shipping": "20.00", "tax": "19.16", "total": "120.00" }, "payment": { "method": "card", "status": "paid", "gateway": "stripe", "gateway_label": "Card", "cod": null }, "billing_address": { "first_name": "Ana", "last_name": "Pop", "company": null, "email": "ana@example.com", "phone": "0722123456", "address_line_1": "Strada Mare 1", "address_line_2": null, "city": "Cluj-Napoca", "region": "Cluj", "region_code": null, "postal_code": "400001", "country_code": "RO", "tax_id": null }, "shipping_address": { "first_name": "Ana", "last_name": "Pop", "phone": "0722123456", "address_line_1": "Strada Mare 1", "city": "Cluj-Napoca", "region": "Cluj", "postal_code": "400001", "country_code": "RO" }, "line_items": [ { "external_id": "line-1", "sku": "TSHIRT-M", "name": "Tricou", "quantity": 2, "unit_price": "50.00", "discount": "0", "tax_rate": "19", "tax": "15.97", "total": "100.00", "weight_kg": "0.300" } ], "shipping_lines": [ { "external_id": "ship-1", "code": "courier", "title": "Curier rapid", "price": "20.00", "tax_rate": "19", "tax": "3.19", "total": "20.00" } ], "fees": [], "delivery": { "method": "address", "carrier": null, "pickup_point": null }, "total_weight_kg": "0.600", "placed_at": "2026-11-16T09:58:12Z", "updated_at": "2026-11-16T09:58:12.481Z"}Every field and its rules are in the reference.
The shape
Section titled "The shape"- Money is a decimal string with at most four decimals, in the order's
currency(ISO 4217). A line'stotalis after every discount, tax included; itstaxis the tax in it.unit_price,discountand a shipping line'spriceare what the buyer saw, in the store's convention (prices_include_tax). Lines, shipping lines and fees add up tototals.total. A fee may be negative. - Text the buyer typed (names, addresses, a product's name) is kept as sent, whatever its length; where a step cannot hold it (an AWB's address), the order shows an issue for the merchant to fix. Identifiers and codes are at most 255 characters.
- Addresses:
country_codeis ISO 3166-1 alpha-2;regionas written (we resolve it),region_code(ISO 3166-2 without the country,CJ) when known; a phone is stored in E.164 when it reads as a number of the address's country. Either address may benull. - Delivery is what the buyer asked, in our words:
methodaddress,pickup_pointorstore_pickup(mixedfor lines asking different things);carrierour carrier code when the buyer picked one at checkout; for a pickup point,pickup_point.external_id(the point's id at itsprovider),nameandaddress. A pickup delivery without the point's id holds the order's AWB until the merchant picks one. A shipping line'stitleis shown only: the method's name decides nothing.
The states
Section titled "The states"The app sends our codes, beside its own status:
| Field | Codes |
|---|---|
source_state (required) |
active, cancelled, closed (done in the store, nothing left to do) |
source_status |
The app's own status, as its platform names it. Shown on the order, and what the merchant's import rules leave out by. |
payment.method (required) |
cod, card, bank_transfer, cash, gift_card, store_credit, other |
payment.status |
pending, authorized, partially_paid, paid, partially_refunded, refunded, voided, failed, not_applicable |
fulfillment_status |
unfulfilled, partial, fulfilled, shipped, delivered, returned, restocked, on_hold |
payment.cod is what is left to collect at delivery, for cod. test: true marks a test order: left out unless the merchant takes test orders in.
Our order status (checking, to_process, processed...) is derived from these and from what happens at our end; it is never sent.
Ordering with updated_at
Section titled "Ordering with updated_at"updated_at is when the order last changed at the app, an RFC 3339 moment with at least milliseconds (2026-11-16T09:58:12.481Z). It decides which of two sends is newer, whatever order they arrive in:
updated_at, against the version held |
Answer |
|---|---|
| Newer | The order is replaced: 200 updated. |
| The same | The same version again: 200, result stale, nothing written, whatever it holds. Send a later updated_at to change the order. |
| Older | Nothing changes: 200, result stale, and order is the version held. |
| More than 5 minutes ahead of the current time | 422: it would hold off every later change. |
The answer
Section titled "The answer"{ "external_id": "1001", "result": "created", "reason": null, "order": { "id": "ord_01jcq4m5x2v7k9t3r8n6p0w1yz", "external_id": "1001", "integration_id": "int_01jcq4m5x2v7k9t3r8n6p0w1yz", "status": "checking", "source_updated_at": "2026-11-16T09:58:12.481000Z", "...": "the whole order" }}order is the whole order exactly as GET /orders/{id} shows it, read after the send: our id (ord_...), our status, and source_updated_at, the updated_at of the version held, to the microsecond. It is null when the order is refused.
| Status | result |
|
|---|---|---|
201 |
created |
First seen. |
200 |
updated |
Stored as sent. |
200 |
stale |
A newer version was held; nothing changed. |
202 |
refused |
Left out by the store's import rules; nothing stored, order is null. reason: before_cutoff (placed before import_cutoff_date), excluded_status (its source_status is one the merchant leaves out), test_order. |
The import rules judge an order only the first time it is seen: once imported, every later send is taken, whatever its status becomes, so a cancellation or a refund is never lost.
An order already processed
Section titled "An order already processed"The app keeps owning what a store owns (the customer, the lines, the totals, the payment, its status); the organization owns what happens at its end (the delivery service chosen, the AWB, the invoice, its own changes to the addresses and the weight). A send after the AWB or the invoice is applied to what the store owns; the AWB and the invoice keep what they were made with, and the merchant's changes stay laid over the app's values. An order cancelled while its AWB or invoice stands waits for the merchant (needs_attention) instead of cancelled.
Idempotency
Section titled "Idempotency"Idempotency-Key is honoured on every send (idempotency): a retry with the same key and body answers what the first one did. A send is safe to repeat even without it: the same updated_at again is the same version of the order and is never written again, whatever it holds (200, result stale); a change is sent with a later updated_at. Two sends of the same order at once are taken in one after the other: the second reads what the first wrote. One still waiting after 10 seconds is refused with 409 order_in_progress; send it again. Neither 409 (integration_paused, order_in_progress) is kept under the key: the same request, with the same key, passes once the store resumes or the other send ends.
Batches
Section titled "Batches"POST /v1/orders/batch{ "orders": [ { "external_id": "1001", "source_state": "active", "currency": "RON", "...": "the order, as sent alone" }, { "external_id": "1002", "...": "..." } ]}Up to 50 orders, each named by its own external_id, once per batch. Each is taken in as if sent alone; the answer has one result per order, in the batch's order, each shaped as the answer to a single send:
{ "data": [ { "external_id": "1001", "result": "created", "reason": null, "order": { "id": "ord_...", "...": "the whole order" } }, { "external_id": "1002", "result": "refused", "reason": "before_cutoff", "order": null } ]}One invalid order refuses the whole batch (422, the errors per orders.<n>.<field>), so fix it and send the batch again. Batches are for the store's history and for what the reconciliation finds missing: their orders are checked behind the live ones, and they are counted in a rate limit of their own (10 batches a minute), apart from the per-minute limit live sends count in. Send a new order alone, as it happens.
Reconciliation
Section titled "Reconciliation"The store's orders are read like any other, from the orders list, with read_orders:
GET /v1/orders?filter[integration]=int_01jcq4m5x2v7k9t3r8n6p0w1yz&filter[external_id]=1001,1002filter[integration]keeps the orders of one store:caller.store.integration_id.filter[external_id]keeps the orders with those ids, exact and case-sensitive, up to 100, comma-separated;filter[external_id][is_not]=keeps the others.
{ "data": [ { "id": "ord_01jcq4m5x2v7k9t3r8n6p0w1yz", "external_id": "1001", "source_updated_at": "2026-11-16T09:58:12.481000Z", "...": "the whole order" } ], "next_cursor": null}Each order's source_updated_at is the updated_at of the version held, to the microsecond. Compare it with the app's own as moments, not as text: the app may send three digits, the answer always shows six.
A store app pushes; nothing reads the app back. Compare from time to time and send again, in batches, what is missing or older (a refused order, by design, is missing).
- Read
GET /v1/organization; stop whilecaller.store.statusis notconnected. - Take the app's orders changed since the last run's start and list them, up to 100 ids at a time:
GET /v1/orders?filter[integration]=<caller.store.integration_id>&filter[external_id]=<their ids>, every page (pagination). - Send in batches those missing from the list or whose
source_updated_atthere is older than the app'supdated_at.
What happens next
Section titled "What happens next"The order's life at our end reaches the app through webhooks, for the scopes the app also asks:
| Events | Scope |
|---|---|
order.created, order.updated (its status, issues, delivery service) |
read_orders |
shipment.created, shipment.status_changed, shipment.cancelled (the AWB and tracking) |
read_shipments |
invoice.created, invoice.status_changed |
read_invoices |
Each names the order by its ord_ id; GET /orders/{id} shows its external_id.
Errors
Section titled "Errors"| Code | Status | When |
|---|---|---|
not_a_store |
403 |
The caller is no store of the organization. |
integration_paused |
409 |
The store is paused or on hold; send again once it resumes. |
order_in_progress |
409 |
Another send of the same order is still being taken in; send it again. In a batch, the orders before it are taken. |
insufficient_scope |
403 |
The installation lacks write_orders (to send) or read_orders (to read). |
validation_failed |
422 |
The order (or one of the batch) is invalid; errors per field. |