A regional chain with 18 physical stores launches Shopify in March. By June, the IT manager discovers there are three "truths" for stock: Shopify, the store POS and an Excel spreadsheet the warehouse keeps "just in case". The problem is not Shopify. It is the absence of a single source of truth across channels — and that absence was created the moment someone decided to "connect the systems" without deciding which of them is in charge.
Retail turnover in Portugal grew by 4.7% in 2024 (INE, 2024). More transactions, more SKUs, more channels. The pressure on the back office does not ease with growth; it intensifies. And when the back office is not prepared to be the source of truth, online growth creates operational chaos rather than revenue.
This article takes a clear position: the integration between MAXIRETAIL and Shopify only works if it is treated as a redefinition of the operating model — not as a technical connection between two systems. The technical component is the easy part. What fails is always data governance.
The mistake that happens before connecting Shopify to the back office
The decision to "integrate" is taken before defining which of the two systems is in charge. Who is the source of truth for stock? Who publishes the price? Who closes the tax record? When this hierarchy is not documented and signed off internally, the result is predictable: Shopify ends up with its own stock, the POS has its own stock, and the back office runs manual reconciliations every night — or stops running them altogether.
Connecting Shopify to the back office without defining the data hierarchy is like installing two accountants in the same company without saying who signs the balance sheet.
The hierarchy nobody documents
In a well-designed integration with MAXIRETAIL, the back office is always the source of truth. Shopify is a sales channel — not a management system. The product catalogue (references, descriptions, technical images) is created and maintained in MAXIRETAIL and published to Shopify via API. Stock available for online sale is calculated in MAXIRETAIL — with store reservations, pending orders and safety stock already deducted — and communicated to Shopify in real time or in configurable windows. The retail selling price, including promotions and seasonal campaigns, originates in the back office; Shopify does not manage prices autonomously. When a Shopify order is confirmed, it enters MAXIRETAIL as a sales document, generates a stock movement and triggers the tax flow (electronic invoicing in accordance with DL 28/2019, with ATCUD).
This hierarchy looks obvious on paper. In practice, it is systematically violated when the e-commerce team has direct access to Shopify and starts making stock adjustments "so as not to lose sales". Configure permissions. Audit manual changes in Shopify on a weekly basis during the first eight weeks after go-live. This is not paranoia — it is the only mechanism that detects the drift before it becomes irreversible.
Integration architectures: the three real options
There is no single way to connect MAXIRETAIL to Shopify. There are three patterns with distinct trade-offs. The choice depends on transaction volume, catalogue complexity and internal IT capacity.
| Architecture | Mechanism | Stock latency | Implementation complexity | Suitability |
|---|---|---|---|---|
| Scheduled flat file (FTP/SFTP) | CSV/XML export from MAXIRETAIL → Shopify import via script | 15 min to 4 hours | Low | Stable catalogues, fewer than 500 SKUs, low volume |
| Bidirectional REST API | Shopify webhooks → MAXIRETAIL endpoint; MAXIRETAIL publishes stock via Shopify API | Under 60 seconds | Medium | Dynamic catalogues, frequent promotions, BOPIS |
| iPaaS middleware (Make, Boomi, Zapier Enterprise) | Integration platform manages queues, retry, data transformation | Configurable (seconds to minutes) | High — but more resilient to failures | Multi-store, multi-warehouse, more than 5,000 SKUs |
The flat-file option is underrated. For a specialised retail chain with a stable catalogue — opticians, tools, seasonal-collection clothing — a synchronisation every 30 minutes is sufficient and eliminates the complexity of managing webhooks. The mistake is applying the bidirectional API architecture to everything because "it's more modern". Modernity without need is maintenance cost that nobody budgeted for.
Shopify webhooks: what fails and how to prevent it
The Shopify API works well under normal conditions. It fails in three situations that are rarely anticipated in the design. During traffic peaks — Black Friday, January sales — Shopify may delay or drop webhooks when the event volume is very high; implement a message queue (RabbitMQ, Azure Service Bus) between Shopify and MAXIRETAIL to ensure no order is lost. When the MAXIRETAIL server takes more than 5 seconds to respond, Shopify marks the webhook as failed and retries; configure the endpoint to respond immediately with HTTP 200 and process the logic asynchronously. Finally, Shopify deprecates API versions with prior notice — set a six-monthly review schedule for the version in use before the deprecation happens in production.
Stock available for online sale: the calculation Shopify does not perform
Shopify shows the stock communicated to it. It does not know that a particular pair of shoes is reserved for a store customer who called in the morning, nor that the warehouse has 12 units but 4 are in quarantine following a return. MAXIRETAIL calculates stock available for online sale as:
Physical stock − Store reservations − Pending orders from other channels − Safety stock configured per channel
This value — and not the gross physical stock — is what should be published to Shopify. Configuring this calculation correctly is the difference between selling what exists and selling what does not.
Electronic invoicing and SAF-T: what cannot fail
A Shopify order paid online is, for the purposes of the Tax Authority, a sale subject to electronic invoicing under DL 28/2019. MAXIRETAIL, certified by the AT, issues the invoice with ATCUD and reports via SAF-T (Portaria 195/2020). There are five points the integration must guarantee without exception.
The Shopify order enters MAXIRETAIL with the customer's tax data (NIF, billing address) before any stock movement. MAXIRETAIL issues the invoice and sends the PDF to the customer by email — not Shopify, which is not AT-certified software. The ATCUD generated by MAXIRETAIL is unique per document; there can be no duplication through webhook retransmission. Online returns generate a credit note in MAXIRETAIL, not a simple stock adjustment in Shopify. And the monthly SAF-T file includes all online sales — check that MAXIRETAIL does not exclude them because they originate from an external channel.
Shopify is not AT-certified software. The one who issues the invoice is the back office. Always.
This point seems elementary. In practice, there are implementations where Shopify issues its own "receipt" and the back office issues a separate invoice — two documents for the same transaction, with different numbering. The AT does not accept this duplication. Define in the contract with the implementation partner who issues the tax document and how uniqueness is guaranteed. Put it in writing before signing off the project.
GDPR and customer data: where Shopify stores what
Shopify stores customers' personal data on its servers — which may be outside the EU depending on the plan and configuration. The GDPR (EU Regulation 2016/679), transposed by Law 58/2019, requires the data controller to know where the data is and on what legal basis it is processed. Configure Shopify for data storage in the EU (available on Shopify Plus plans with explicit configuration). MAXIRETAIL, as the back-office system, is the main repository of customer data for CRM and loyalty purposes; Shopify should be configured not to duplicate profiles — use the NIF or email as the deduplication key. The right to erasure (Article 17 GDPR) must be executed in both systems; document the procedure before go-live, not after the first complaint.
Operational scenarios: BOPIS, ship-from-store and returns
BOPIS: buy online, pick up in store
BOPIS (Buy Online, Pick Up In Store) is the scenario that stresses the integration the most. The customer buys on Shopify, chooses a store for collection, and expects confirmation within minutes. The Shopify order reaches MAXIRETAIL with the collection store identified. MAXIRETAIL checks stock in that specific store — not global stock — and, if available, reserves the item and sends confirmation to the customer. The store POS shows the order pending collection without any manual intervention by the store manager. At the moment of collection, the POS records the outbound movement and closes the tax document.
The fourth step is where most implementations fail. If the store manager has to consult an email or a separate system to know there is an order to hand over, the process degrades rapidly. The POS has to show pending BOPIS orders on the main screen, without the operator needing to look for them. This requirement must be specified — not assumed.
Ship-from-store: the warehouse that already exists
For chains with stores well distributed geographically, ship-from-store reduces transport costs and delivery times. MAXIRETAIL can configure order allocation rules based on geographic proximity, available stock and each store's dispatch capacity. Shopify receives the dispatch confirmation with the tracking number — generated by the store, not by the central warehouse. Centralised versus fragmented stock management has direct implications here: ship-from-store only works if each store's stock is visible and reliable in real time in the back office.
Online returns: the reverse flow that nobody designs well
The customer returns an item bought online — in store or by post. MAXIRETAIL must issue a credit note referenced to the original invoice (a tax obligation), record the returned item in quarantine or available stock depending on its condition, update the stock in Shopify if the item becomes available for sale again, and process the refund — which may be via Shopify Payments, MB Way, bank transfer or store credit. Configure the returns flow before go-live. It is the flow with the most variations and the one most frequently left unspecified in integration projects.
Decision matrix: which architecture for your profile
| Retailer profile | SKU volume | Physical stores | Recommended architecture | Configuration priority |
|---|---|---|---|---|
| Specialised retail (opticians, tools, clothing) | Fewer than 500 | 1–5 | Scheduled flat file (30 min) | Price hierarchy + AT invoicing |
| Regional food or specialised chain | 500–3,000 | 5–20 | Bidirectional REST API | BOPIS + stock per store + returns |
| Franchising or multi-brand | 1,000–10,000 | More than 20 | iPaaS middleware + API | Customer deduplication + consolidated SAF-T |
| Retail with dynamic pricing or daily promotions | Any | Any | REST API with price webhooks | Price synchronisation in under 5 minutes |
What works in practice
Differentiated safety stock per channel
A clothing retail chain with 12 stores in northern Portugal can configure a safety stock of 2 units per reference for the online channel — regardless of total physical stock. If a reference has 3 units in the warehouse, Shopify shows 1 available. This eliminates the situation of selling online what is reserved for store replenishment. The cost is a slightly lower online conversion rate; the benefit is zero stockouts with impact in store. For most regional chains, the trade-off is favourable.
Online catalogue as a subset of the total catalogue
Not all back-office items should be on Shopify. A construction-materials distribution company with a presence in the Lousada/Paços corridor can publish online only items with regular stock and sufficient margin to absorb dispatch costs — filtering in MAXIRETAIL by category, supplier or minimum margin. Shopify receives only that subset. This prevents the online catalogue from ending up with discontinued, out-of-stock or outdated-price items. It is a business decision, not a technical limitation — and it must be taken before connecting the systems.
KPIs for the integration monitored in the back office
Configure a dashboard in Qlik Sense with the integration's critical indicators: webhook success rate, average stock synchronisation time, Shopify orders without an invoice generated, returns pending a credit note. These KPIs are not business metrics — they are integration health metrics. Without them, problems are only detected when the customer complains.
The integration does not fail suddenly. It degrades slowly — a lost webhook here, an outdated stock figure there — until the day the IT manager receives 40 complaints over a single weekend.
Implementation: a sequence without shortcuts
- Define the data hierarchy (week 1): document who is the source of truth for stock, price, catalogue and customer data. Sign off internally. Do not proceed without this document.
- Map the catalogue (weeks 2–3): identify which items to publish on Shopify, which fields are mandatory (EAN, description, image, VAT, dispatch weight) and which are missing in the back office. Clean the data before connecting.
- Configure AT invoicing (week 4): validate with the MAXIRETAIL partner that Shopify orders generate an invoice with ATCUD and that the SAF-T includes them. Run a test with a real order before opening to the public.
- Implement and test the returns flow (week 5): simulate a return in store and one by post. Check the credit note, stock movement and refund.
- Activate monitoring (week 6): configure alerts for failed webhooks, negative stock in Shopify and orders without an invoice. Assign someone responsible for each alert — not a group, a person.
- Phased go-live (weeks 7–8): open with a subset of the catalogue. Validate over two weeks before publishing the full catalogue.
For franchisees with a shared back office, the sequence has important variations — see how the MAXIRETAIL back office manages franchisees before defining the integration architecture.
What MAXIRETAIL solves that a generic connector does not
There are generic Shopify connectors on the market. They work for general-purpose ERPs that have no retail logic built in. MAXIRETAIL already has POS, store back office, loyalty and promotion management integrated — which changes the nature of the integration. Promotions configured in MAXIRETAIL (quantity discount, seasonal campaign, member price) are published to Shopify without reconfiguration; a generic connector does not know that an item has a different price for a loyalty customer. BOPIS is native — the store POS already has the concept of an order for collection, it is not a workaround. And AT invoicing is managed by MAXIRETAIL, which is certified software; the generic connector leaves this responsibility for the retailer to resolve externally — which, in practice, means it remains unresolved until the first inspection.
For chains with complex promotion management, see also promotion and seasonality management across a store chain — the topic intersects directly with price synchronisation to Shopify. Integration with KORA Inventory Suite is relevant when online fulfilment is carried out from a dedicated warehouse or a dark store: picking, the packing list and dispatch are integrated with the same back office that feeds Shopify.
The mistake the manuals do not mention
There is a failure pattern we see repeated in omnichannel retail implementations in Portugal: the e-commerce team and the store team never speak to each other during the project. IT does the technical integration, e-commerce configures Shopify, and the store manager discovers BOPIS on the day of go-live. The result is a technically correct process that operationally does not work — because the store operator does not know what to do when an order for collection appears on the POS.
Include the store manager — or the warehouse supervisor, in the case of ship-from-store — in the specification sessions. Not in the technical validation sessions: in the specification sessions. It is they who identify the exception cases IT does not anticipate: the customer who wants to collect half the order today and half tomorrow, the item that arrived damaged and cannot be handed over, the promotion Shopify shows but the store does not recognise. These cases are not rare — they are the everyday reality of any store with a reasonable volume.
Omnichannel retail trends for 2026 point to a growing convergence between physical and digital channels. Those who do not resolve data governance now will have to resolve it with more stores, more SKUs and more customers complaining.
Those who treat the MAXIRETAIL-Shopify integration as a system connection will have three "truths" for stock within six months. Those who treat it as a redefinition of the sales flow will have an online channel that works — and a back office that can still be audited.
Sources
- INE — Statistics Portugal. Retail Trade Turnover Index, 2024. Available at: www.ine.pt
- Decree-Law No 28/2019, of 15 February — Rules applicable to the processing of invoices and other fiscally relevant documents. Diário da República, 1st series, No 32.
- Ordinance No 195/2020, of 13 August — Monthly reporting of SAF-T (PT) file elements to the Tax and Customs Authority. Diário da República, 1st series, No 157.
- Regulation (EU) 2016/679 of the European Parliament and of the Council (GDPR), of 27 April 2016. Official Journal of the European Union, L 119.
- Law No 58/2019, of 8 August — Implementation of the GDPR in national law. Diário da República, 1st series, No 151.
- Shopify API Reference — versioning and webhooks. Available at: shopify.dev/docs/api
Frequently asked questions
What is the "single source of truth" in a Shopify integration with MAXIRETAIL?
It is the clear definition of which system controls each type of data. In the correct model, MAXIRETAIL is always the source of truth: it manages the catalogue, the stock available for sale (with reservations and pending orders already deducted) and prices. Shopify functions as a sales channel, not a management system. Without this documented hierarchy, multiple "truths" arise — stock in Shopify, stock in the POS, stock in Excel — creating operational chaos.
What is the difference between physical stock and stock available for online sale?
Physical stock is the total number of units in the warehouse. Stock available for online sale is calculated by subtracting store reservations, pending orders from other channels and safety stock. Shopify should always receive this adjusted value, not the gross stock. Otherwise, it sells products that are not actually available, causing returns and customer dissatisfaction.
What are the three possible integration architectures?
Scheduled flat file (CSV/XML via FTP, latency 15 min to 4 hours, low complexity); bidirectional REST API with webhooks (under 60 seconds, medium complexity); iPaaS middleware such as Make or Boomi (configurable, high complexity but more resilient). The choice depends on transaction volume, catalogue complexity and internal IT capacity.
When is flat-file integration appropriate?
For specialised retail chains with a stable catalogue (opticians, tools, seasonal-collection clothing), fewer than 500 SKUs and low transaction volume. A synchronisation every 30 minutes is sufficient and eliminates the complexity of managing webhooks. It is an underrated option that reduces maintenance costs without compromising the operation.
What happens when Shopify fails to communicate an order via webhook?
During traffic peaks (Black Friday, sales), Shopify may drop webhooks if the volume is very high. Implementing a message queue (RabbitMQ, Azure Service Bus) between Shopify and MAXIRETAIL ensures no order is lost. The endpoint should respond immediately with HTTP 200 and process the logic asynchronously to avoid timeouts.
How can the back office be kept from becoming outdated by manual changes in Shopify?
Configure restrictive permissions and audit manual changes in Shopify on a weekly basis during the first eight weeks after go-live. The e-commerce team should not have direct access to adjust stock "so as not to lose sales". This audit detects the drift before it becomes irreversible and compromises data integrity.
What is the legal obligation of a Shopify order in Portugal?
A Shopify order paid online is a sale subject to electronic invoicing under Decree-Law 28/2019. MAXIRETAIL must automatically generate the sales document, stock movement and electronic invoicing with ATCUD. This integration is not optional — it is mandatory for tax compliance.