PrestaShop POS Integration (Square, Zettle, SumUp): documentation

How it works

PrestaShop is the stock master. Every stock change of a mapped product is sent to the POS as an absolute quantity. Every POS sale is imported, deducted from the PrestaShop stock with the “POS sale” movement reason, then the new level goes back to the other POS. Returns put the items back in stock with the “POS return” reason.

• Square: two-way stock, sales, returns, catalog export.
• Zettle by PayPal: two-way stock, sales, refunds, catalog export.
• SumUp: sales import only. The SumUp public API exposes neither stock nor catalog.

Requirements

• PrestaShop 8.0 to 9.x.
• A cron job on your hosting.
• HTTPS on the shop for the Zettle webhook.
• A Square, Zettle or SumUp account with developer access.

Installation

1. In Modules > Module Manager, click Upload a module and send the ZIP.
2. The module adds the Catalog > POS Connector menu.
3. The dashboard shows a “Getting started” list that ticks itself as you set things up.

Connect your POS

Open the Connections tab. Each POS has its own panel with an Enabled box. Credentials are encrypted in the database: a field left empty keeps the saved value.

Square

1. Create an application in the Square Developer Dashboard and copy its production access token.
2. Paste it into Access token, choose the environment, save, then click Test the connection.
3. Choose the location that receives the stock. If you have several, tick the ones whose sales must be imported (10 at most).
4. For instant import, create a webhook subscription on the order.updated event with the notification URL shown, then paste the signature key into the module. The URL must be exactly the same on both sides.

Zettle by PayPal

1. In the Zettle Developer Portal, create a self-hosted API key with the READ:PURCHASE, READ:PRODUCT, READ:USERINFO and WRITE:PRODUCT scopes.
2. Enter the Client ID and the API key, save, then test the connection.
3. Click Activate the webhook to receive sales within seconds.
4. Stock tracking must be enabled on the products in Zettle. Products sent by the module have it automatically.

SumUp

1. Enter your secret API key (sup_sk_...), save, then test the connection. The merchant code is detected automatically.
2. SumUp sales are mapped by item name: exact reference or exact name of a product without combinations.

Synchronization rules

At the top of the Connections tab:

• Send PrestaShop stock levels to the POS, and optionally right after each change.
• Import POS sales and deduct them from the PrestaShop stock.
• Put returned items back in stock (Square and Zettle).
• Automatic mapping by reference, by EAN-13 / UPC, and by name for SumUp.
• Import POS sales from: earlier sales are ignored. A sale already imported is never duplicated.

Scheduled task and webhooks

The dashboard shows two URLs. Schedule the first one every 5 minutes and the second one (with full=1) once a night:

*/5 * * * * curl -s "https://your-shop.com/module/dfposconnector/cron?token=YOUR_TOKEN" >/dev/null
0 3 * * * curl -s "https://your-shop.com/module/dfposconnector/cron?token=YOUR_TOKEN&full=1" >/dev/null

The cron imports new sales, sends pending stock and detects gaps created outside PrestaShop (SQL import, ERP). The nightly sync resends every mapped level. Cron and webhooks also work in maintenance mode.

Map your products

Product mapping tab:

• Read the catalog of Square or Zettle: maps automatically by SKU and barcode.
• Suggest products by name: proposes a product for each remaining item, with a score. Suggestions at 90% or more can be accepted in bulk, the others one by one.
• Manual mapping: search a product by name, reference or EAN.
• Send all stock to the POS, or import stock from the POS into PrestaShop (use it once, at setup, if the POS stock is the reliable one).

Send the catalog to the POS

Send catalog tab: choose the POS, a category (subcategories included), the price sent (tax incl. or tax excl., without discounts) and whether only active products are concerned.

1. Check what will be sent first reads the POS catalog and maps what already exists, then shows the number of products and variations to create.
2. Create them in the POS sends the products in batches with a progress bar. Combinations become variations. Each created item is mapped and receives its stock.

Not sent: products already mapped in that POS, virtual products, packs, images and categories. Zettle accepts at most 99 variants per product.

Stock check

The Stock check tab reads the real quantities from Square or Zettle and lists the gaps with PrestaShop, largest first. For each line:

• Send PrestaShop stock: the POS receives the PrestaShop value.
• Take POS stock: PrestaShop receives the POS value, with a stock movement.

PrestaShop orders for in-store sales

PrestaShop orders panel, off by default. Once enabled, each sale whose items are all mapped creates an order:

• dedicated walk-in customer at the shop address;
• free “POS sale” carrier, never offered at the checkout;
• ticket prices, a ticket-level discount being spread over the lines;
• order dated at the time of the sale, with the POS reference in the internal note;
• “POS sale” state (paid, delivered, no invoice, no email), which you can change in the settings.

The order then deducts the stock itself. No email is sent during creation. A sale with unmapped items gets no order: its mapped items are deducted directly.

Sales journal

The POS sales tab lists each sale with its lines, POS, location, payment and, when relevant, the link to the order. Filters: POS, status (to map, matched, returns, with order), search by ticket, item or location, date range. The Export CSV button exports the selection, one row per item.

Email alerts

Email alerts panel: an email is sent when the scheduled sync fails 3 times in a row (at most one every 6 hours), then another one when it works again. Leave the address empty to use the shop email. The Send a test alert button checks delivery.

Troubleshooting

“Inventory not initialized” on Zettle

Enable stock tracking on at least one product in Zettle, or send a product from the Send catalog tab.

Square webhook rejected (invalid signature)

The notification URL declared in Square must match the module URL character for character, and the signature key must belong to that subscription.

Stock is not sent after a change in the back office

PrestaShop does not run a module’s hooks for an employee who lacks the “View” permission on that module. The cron gap check catches these changes on the next run. You can also grant the permission in Advanced Parameters > Team > Permissions.

A sale did not create an order

The technical log gives the reason: unmapped items, sale currency missing in PrestaShop, carrier restriction on a product, or a quantity below one unit. The stock was then deducted directly.

Uninstallation

Uninstalling deletes the module tables (mappings, sales journal, queue, technical log) and its settings, and disables the “POS sale” carrier. Orders created, the order state, the walk-in customer and the stock movement reasons are kept, because the history refers to them.