Skip to content

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 the app provides: Store (sends orders), on Details (what the app provides).
  • The scopes: write_orders to send the orders, and read_orders to read them back (the reconciliation, the order webhooks). write_orders is 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 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:

Terminal window
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"

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.

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.

POST /v1/orders

external_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.

  • Money is a decimal string with at most four decimals, in the order's currency (ISO 4217). A line's total is after every discount, tax included; its tax is the tax in it. unit_price, discount and a shipping line's price are what the buyer saw, in the store's convention (prices_include_tax). Lines, shipping lines and fees add up to totals.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_code is ISO 3166-1 alpha-2; region as 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 be null.
  • Delivery is what the buyer asked, in our words: method address, pickup_point or store_pickup (mixed for lines asking different things); carrier our carrier code when the buyer picked one at checkout; for a pickup point, pickup_point.external_id (the point's id at its provider), name and address. A pickup delivery without the point's id holds the order's AWB until the merchant picks one. A shipping line's title is shown only: the method's name decides nothing.

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.

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.
{
"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.

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-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.

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.

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,1002
  • filter[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).

  1. Read GET /v1/organization; stop while caller.store.status is not connected.
  2. 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).
  3. Send in batches those missing from the list or whose source_updated_at there is older than the app's updated_at.

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.

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.