> For the complete documentation index, see [llms.txt](https://docs.flowretail.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowretail.com/docs/integrations/e-commerce.md).

# E-commerce

How to connect a webshop to Flow Retail: who owns what, how an order gets in and a delivery gets back, how to show correct stock, and which endpoints to use.

**A webshop is an online store in Flow Retail. The shop owns checkout, customer login and payment. Flow Retail owns products, prices, stock and fulfilment.**

Orders go in once, from your server. Everything else comes back as a signal to fetch.

![The webshop sends each order and customer to Flow Retail once. Flow Retail announces product, stock and delivery changes by webhook, and the shop fetches the detail and sweeps prices as a safety net.](https://593715853-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0GCVniU8V4PZKEK4axWz%2Fuploads%2Fv8UiWxFAKvpSmPL90Shs%2Fintegration-ecommerce.svg?alt=media)

{% hint style="info" %}

#### What you need

An [Integration user and token](https://docs.flowretail.com/docs/developers/authentication.md), an online store in Flow Retail with at least one warehouse, an external payment method on that store, and a stage tenant to build against. Read [Webhooks](https://docs.flowretail.com/docs/developers/webhooks.md) first.
{% endhint %}

## Who owns what?

**Write this down before you build.** The join key between the two systems is the SKU.

| Data                           | Owner                                     | Direction               | Trigger                             |
| ------------------------------ | ----------------------------------------- | ----------------------- | ----------------------------------- |
| Products, images, brand, group | Flow Retail                               | Flow → shop             | Webhook, then fetch                 |
| Web visibility                 | Flow Retail, per product                  | Flow → shop             | Same                                |
| Prices and campaign prices     | Flow Retail                               | Flow → shop             | Webhook, plus an hourly sweep       |
| Stock                          | Flow Retail, per warehouse                | Flow → shop             | Webhook, delta poll, periodic sweep |
| Customer accounts and consent  | Shop                                      | Shop → Flow             | When an order is sent               |
| Orders                         | Shop creates, Flow Retail owns fulfilment | Shop → Flow, once       | Server-side order event             |
| Payments                       | Payment provider                          | Recorded in Flow Retail | With the order                      |
| Shipping methods               | Flow Retail                               | Flow → shop             | Read once, refresh rarely           |

## How does an order get into Flow Retail?

**One call creates the whole order.** `POST /tenants/{tenantUid}/stores/{storeUid}/orders/import` takes lines, payment, delivery and customer together, and applies all of it or none.

* **Send `validUntil: null`.** The call is rejected without the field.
* **Your prices are kept.** Imported lines skip Flow Retail's price and campaign calculation, so the shop is the price owner for the order. Line totals must match `orderTotals.grandTotal` within 1.00, and payments must add up to it exactly.
* **Name your own keys.** Derive `orderUid`, `orderItemUid`, `deliveryUid` and `settlementUid` from the shop's ids (letters, digits, `-` and `_`).
* **Add `externalIds`** with the shop's order number, so you can search for it later.

### How do you record the payment?

**The simplest path: the customer has paid at checkout, so send the payment with the order.**

1. Set `reservationType` to `WAREHOUSE` on every goods line, and `NONE` on freight.
2. Add one settlement with status `CAPTURED` on an external payment method.
3. The order becomes <kbd>COMPLETE</kbd>: settled and closed for edits, but not shipped. The goods stay reserved and the delivery is <kbd>NOT\_STARTED</kbd>.

{% hint style="danger" %}

#### Never send a captured payment on lines with reservation `NONE`

Flow Retail treats the order as a counter sale and delivers it at once, so stock is taken out and nothing is left to pick.
{% endhint %}

Capture the payment at your provider first. An `AUTHORIZED` settlement on an external method never becomes deliverable. If you want to keep the order editable until picking starts, import with no payment, move the order to <kbd>CONFIRMED</kbd>, and add the payment with `POST …/orders/{orderUid}/settlements` when handling starts. For pay-later methods, import without payment and settle when the provider reports it paid. Test your chosen path on stage with your own payment method before you go live.

### How do you make it safe to repeat?

**Branch on the error `code`, and read the order back after any timeout.** A second import with the same `orderUid` is rejected as a duplicate. After a timeout or a `5xx`, call `GET /tenants/{tenantUid}/stores/{storeUid}/orders/{orderUid}`. A `200` means it went through. A `404` means you can send the same body again.

Customers work the same way. Create with your own `customerUid`, and store the link. If an email or mobile number already exists you get a conflict (`ErrCustomerEmailAlreadyExists`, `ErrCustomerPhoneNumberAlreadyExists` or both). Reuse the existing customer instead. A guest can travel on the order itself in `customerAddress` and `invoiceAddress`.

**Create orders from your server's order event, never from a browser callback.** A closed tab must not lose an order.

## How do you show correct stock?

**Trigger on `STOCK_CHANGE`, fetch in batches, and keep a sweep behind it.**

Flow Retail returns `quantityStock` and `quantityReserved` per warehouse, and no ready-made "available". Compute stock minus reserved, divide by 100 and round down. Reserved includes the shop's own unshipped orders, so do not subtract them a second time.

| Step                    | Call                                                                                            |
| ----------------------- | ----------------------------------------------------------------------------------------------- |
| Fetch for many products | `POST /tenants/{tenantUid}/products/stock` with `productSkus` or `productUids`                  |
| Only what changed       | `POST /tenants/{tenantUid}/stores/{storeUid}/stock` with `modifiedAfter`, cursor kept per store |
| Safety net              | The same fetch for the whole range every 30 to 60 minutes                                       |

Wait a few seconds after an event so bursts become one fetch. For 10,000 products a full sweep is about 20 calls. A loop over single products is 10,000.

## How do products and prices reach the shop?

**Webhook, then fetch.** On `PRODUCT_CREATE`, `PRODUCT_UPDATE` or `PRODUCT_MEDIA_CHANGE`, fetch with `POST /tenants/{tenantUid}/stores/{storeUid}/products/search`. It returns price, campaign price and stock totals together. Whether a product shows on the web is set per product with `availableForWeb`, `visibility` and `discontinuedFrom`.

Prices have no changed-since filter, so sweep hourly. Deletes send no webhook, so compare lists nightly. Look products up with `exactMatch: true`, or a fuzzy match can skip hidden products or return a neighbouring SKU.

## How does a delivery get back to the shop?

**Subscribe to `ORDER_LINE_DELIVERED` and `ORDER_DELIVERED`, then read the deliveries.** `GET /tenants/{tenantUid}/stores/{storeUid}/orders/{orderUid}/deliveries` has the tracking number, the delivered lines and the provider and method. Flow Retail stores no carrier name or tracking link, so map them from the shipping method. A delivery can be partial. Create one shop shipment per delivery.

Map each shop shipping method to a delivery provider and method once, from `GET /tenants/{tenantUid}/delivery-providers`.

If the shop or a warehouse partner does the fulfilment, register deliveries per line with `POST …/orders/{orderUid}/items/{orderItemUid}/deliveries`. The order must be settled, and Flow Retail then takes the stock out.

## What about cancellations and returns?

* **Cancel** with `DELETE` on the order. It works only while the order is open or unpaid. A settled order is refused, and a person credits it in Flow Retail.
* **Edited in the shop after export?** Compare quantities with what you sent, and hold the order for a person instead of letting the two diverge.
* **Customer returns** are a credit line linked to the original line, plus a negative payment. The return-order endpoints are for returns to suppliers, not customers. Plan customer returns as a manual step until you have tested the credit flow.

## What should the connector look like?

**A thin service of its own, with a small database.** Keep a link table (shop variant, `productUid`, SKU), an order table (shop order, `orderUid`, state, hold reason), an event inbox and a stock cursor per store. Verify the webhook credential, store the pointer, return `200`, and work from a queue. Every webhook has a poll behind it.

**Never drop an order.** It is exported, waiting, or held with a reason a merchant can fix.

## What goes wrong, and how do you avoid it?

* **Counter-sale surprise.** See the warning above.
* **Stale product links.** One outdated link sent the wrong colour on every order. Validate the link on each export.
* **Searching for the customer every time.** It created duplicates and phone conflicts. Store the link.
* **Promotions not split per line.** The export stopped on "difference exceeds 1.00". Allocate discounts by line, and split lines so every øre lands.
* **A stock cursor reset each run.** Keep it, and use the start of time only for a store that never synced.
* **Slow webhook handlers.** Product work inside the handler took 9.6 seconds against a 10 second limit. Acknowledge first.
* **Answering a webhook with a `4xx`.** The event is lost. Accept and quarantine.
* **Cancelled orders in stock sums.** Lines keep `quantityReserved` after the reservation is released. Skip cancelled orders.
* **Side steps that stop an order.** Logging and label printing must never be able to fail an export.

## How many calls is that?

| Job                           | Calls         |
| ----------------------------- | ------------- |
| Catalog load, 10,000 products | About 20      |
| One order, guest              | 1             |
| One order, new customer       | About 3       |
| Delivery back to the shop     | 2             |
| Whole life of an order        | About 8 to 12 |

## Which APIs does this use?

| For                             | API group                                                                                                                                                                                                                                                                                    |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Orders, import and cancel       | [Order](https://docs.flowretail.com/docs/developers/api-documentation/order)                                                                                                                                                                                                                 |
| Payments                        | [Order Settlement](https://docs.flowretail.com/docs/developers/api-documentation/order-settlement)                                                                                                                                                                                           |
| Deliveries and tracking         | [Order Delivery](https://docs.flowretail.com/docs/developers/api-documentation/order-delivery)                                                                                                                                                                                               |
| Picking                         | [Order Handling](https://docs.flowretail.com/docs/developers/api-documentation/order-handling)                                                                                                                                                                                               |
| Products, search and visibility | [Product](https://docs.flowretail.com/docs/developers/api-documentation/product), [Stock Info](https://docs.flowretail.com/docs/developers/api-documentation/stock-info)                                                                                                                     |
| Images                          | [Product Media](https://docs.flowretail.com/docs/developers/api-documentation/product-media)                                                                                                                                                                                                 |
| Prices                          | [Prices](https://docs.flowretail.com/docs/developers/api-documentation/prices)                                                                                                                                                                                                               |
| Customers                       | [Customer](https://docs.flowretail.com/docs/developers/api-documentation/customer)                                                                                                                                                                                                           |
| Shipping                        | [Delivery Provider](https://docs.flowretail.com/docs/developers/api-documentation/delivery-provider), [Delivery Method](https://docs.flowretail.com/docs/developers/api-documentation/delivery-method), [Timeslots](https://docs.flowretail.com/docs/developers/api-documentation/timeslots) |
| Events                          | [Webhooks](https://docs.flowretail.com/docs/developers/api-documentation/webhooks)                                                                                                                                                                                                           |

Want an engineer to look at your design before you build? Email <integration@flowretail.no>.

*Last updated 30.10.2026*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flowretail.com/docs/integrations/e-commerce.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
