Odoo and Square integration

What moves between them

The primary flow moves Square payments and refunds into Odoo for accounts receivable posting. When a Square payment is created or updated, ml-connector reads the payment detail, customer, and line items, then creates or updates an Odoo invoice and posts the payment into the matching GL account. Products are synced from Odoo into Square's catalog, and customer records are aligned in both directions so an Odoo contact maps to the matching Square customer. Square disputes and payment refunds are also mirrored into Odoo as credit memos or reversals. Invoices created in Odoo can optionally push into Square for a unified customer view.

How ml-connector handles it

ml-connector stores Odoo API keys and Square OAuth2 tokens encrypted. For Odoo, it passes the API key on every XML-RPC or JSON-2 call using the authenticated user's identity; for Square, it refreshes the bearer token every 25 days to avoid the 30-day expiry window. ml-connector subscribes to Square webhooks for payment.created, payment.updated, refund.created, and order.updated events, verifying each webhook signature with HMAC-SHA256 before processing. On the Odoo side, it polls GL accounts and products on a fixed schedule to keep Square's catalog current. Because Odoo's write-date filter allows efficient high-water-mark polling, ml-connector uses that to retrieve only changed records since the last run. Square payments are deduplicated by Square payment ID, and Odoo invoices by their external reference ID. If a Square webhook arrives before the Odoo invoice exists, ml-connector queues the transaction and retries after creating the customer and invoice line items. Every record carries a full audit trail, so any failed posting can be inspected and manually corrected downstream.

A real-world example

A small-to-mid-size e-commerce and services business runs Odoo for accounting and inventory, and Square for payments and point-of-sale. Before the integration, the accounting team received Square payment notifications by email and manually entered each transaction into Odoo's accounts receivable ledger, reconciling daily. They also duplicated product SKUs and prices across both systems and handled customer record conflicts when the same buyer purchased both online and in-store. With Odoo and Square connected, each payment posts automatically into the ledger with the correct customer and amount, product catalog changes in Odoo flow into Square within hours, and customer records are unified. Monthly reconciliation is reduced from a 2-day manual process to a single-day review.

What you can do

• •Post Square payments and refunds into Odoo's accounts receivable and credit memo accounts with the correct invoice and customer mapping.
• •Sync Odoo products, prices, and categories into Square's catalog in real time, keeping SKUs and pricing current across channels.
• •Align customer records bidirectionally so Odoo contacts match Square customers and address changes propagate both ways.
• •Authenticate Odoo with API keys and Square with OAuth 2.0 bearer tokens, handling token refresh every 25 days and webhook signature verification.
• •Poll Odoo's write-date filters and subscribe to Square webhooks to detect changes with minimal lag, with deduplication and a full audit trail on every record.

Questions

Which direction does data move between Odoo and Square?

Square payments and refunds move into Odoo as GL postings and credit memos. Products, prices, and categories flow from Odoo into Square's catalog. Customer records sync bidirectionally. Invoices created in Odoo can also optionally push into Square for a unified customer view. This design keeps the commerce layer and accounting ledger in agreement.

How does the integration handle Odoo's API key authentication and Square's OAuth 2.0 tokens?

ml-connector stores both credential sets encrypted. For Odoo, it passes the API key on every call using the authenticated user's identity. For Square, it refreshes the bearer token every 25 days, well before the 30-day expiry, and handles the refresh-token lifecycle automatically. Both systems' credentials are rotated through Railway's encrypted env vars.

Does Odoo polling lag behind Square payments, or does the integration handle real-time updates?

ml-connector subscribes to Square webhooks for payment events, so new payments are detected in real time with HMAC-SHA256 signature verification. Odoo products and customers are polled on a fixed schedule using write-date filters for efficiency. If a webhook arrives before the Odoo invoice exists, ml-connector queues the transaction and retries, ensuring no data is lost.