Migrate from Circle Commerce to Dolibarr ERP

Circle Commerce customer records map to Dolibarr Third Party objects. Circle's customer-specific custom fields (any attributes beyond standard contact fields) are mapped to Dolibarr's Extrafields (custom fields) table via the Module CustomFields configuration. We resolve the customer-company relationship during import: if Circle stores customers as standalone records, they become Dolibarr Third Parties with type=Contact; if customers are company-assigned, they become Dolibarr contacts linked to a parent Third Party with type=Company. All addresses, email, phone, and account-level custom fields migrate as Extrafields into llx_societe_extrafields.

Circle Commerce order headers and line items map to Dolibarr Customer Order objects. The Circle order number becomes the Dolibarr ref, order status maps to a Dolibarr OrderStatus value (DRAFT, VALIDATED, SHIPPED, CLOSED), and order total and tax amounts map to total_ht, total_tva, and total_ttc. Circle custom order fields migrate as Extrafields. Line items from the Circle order export are written as Dolibarr CommandefDet (order line) records with product reference or description, quantity, unit price, and VAT rate resolved from the field map.

Circle Commerce product records map to Dolibarr Product objects. The Circle product name becomes the Dolibarr label, SKU maps to ref, and pricing data maps to cost price (prix de revient) and selling price (prix_vente). Circle's custom product attributes (any customer-defined fields on the product object) are mapped to Dolibarr Extrafields on llx_product_extrafields. We handle the Circle-to-Dolibarr product type mapping: if Circle products are physical goods they become type=0 (Product) in Dolibarr; if they are services they become type=1 (Service). Bundle and kit relationships from Circle are decomposed into Dolibarr product BOM (bill of materials) or handled as grouped line items per the customer's preference.

Circle Commerce channel-specific inventory records (online, BOPIS, warehouse) map to Dolibarr Stock and Entrepot objects. We create Dolibarr warehouses matching Circle's channel definitions (e.g., online-fulfillment, retail-floor, warehouse-A) and write stock quantities as reel (real stock) values per product-warehouse combination. If Circle's inventory is a single pool, we consolidate to one Dolibarr warehouse by default; if channel-level allocation must be preserved, we create multiple warehouses and map quantities accordingly. Stock value (prix考核) is computed from the product cost price at migration time.

Circle Commerce shipment records with carrier, tracking number, and status map to Dolibarr Expedition objects. The shipment order reference links to the corresponding Dolibarr Order, tracking URL maps to tracking_url, and shipping status maps to expedition status. We extract the carrier name from Circle's shipment export and map it to a Dolibarr carrier configuration or store as a text Extrafield if no matching carrier record exists in Dolibarr. Partial shipments and backorder records are handled as separate Expedition rows linked to the same order.

Circle Commerce purchase orders map to Dolibarr Supplier Order objects. Vendor name maps to the Dolibarr supplier Third Party (type=Supplier); expected delivery date maps to date_livraison; PO line items map to CommandefournisseurLigne records with product reference, quantity, and buy price. Where vendors exist only as free-text in CircleHub (no structured vendor record), we flag them during discovery and create Dolibarr Third Party records for each unique vendor name before importing the PO lines.

All customer-defined custom fields from CircleHub across any object are mapped to Dolibarr Extrafields. During scoping we introspect the customer's live CircleHub schema to identify every custom field (name, data type, object assignment). We then create matching Dolibarr Extrafields using the appropriate field type: varchar for short text, text for long text, int or float for numeric values, datetime for timestamps, select for enumerated values. The Extrafields migration is done before the primary object import so that the custom field columns exist in Dolibarr at insert time. Data type conversion is applied per field (e.g., Circle boolean stored as text 'true'/'false' converted to Dolibarr's integer 0/1).

Circle Commerce custom reports and KPI definitions built on the customer's own field names have no export API path. We capture report metadata during discovery — report name, filters, calculated fields, and output structure — and document it in the migration handoff. We do not migrate report definitions as data records. The underlying data (orders, customers, products) migrates to Dolibarr, and the customer's admin rebuilds reports using Dolibarr's built-in report engine or a Dolistore reporting module (such as those available on NextGestion). We flag which Dolibarr fields correspond to each Circle custom field used in a report so the admin can rebuild efficiently.

Circle Commerce owners (users who created or are assigned to records) map to Dolibarr User records. We resolve by matching the owner email address to the Dolibarr user email field. Any Circle owner without a matching Dolibarr user goes to a reconciliation queue for the customer's admin to provision before record import continues, because OwnerId is a required reference on orders and other assigned records in Dolibarr.

All date and timestamp fields from Circle Commerce (order creation date, shipment date, customer creation date) are preserved as their corresponding date fields in Dolibarr (date_creation, date_valid, date_livraison) at migration time. We do not alter or reset timestamps to the migration date. Time zone handling is documented during scoping — if Circle stores times in a specific timezone and Dolibarr's server PHP timezone differs, we apply an explicit offset during transformation so that order chronology is accurate in the destination.

File attachments stored in Circle Commerce (order documents, product images, shipment labels) are exported and stored in Dolibarr's /documents directory structure. We map each attachment to the appropriate Dolibarr object using the ECM (Electronic Content Management) module or the object-level document links. Image files for products are linked to the Dolibarr Product via the product image upload mechanism. PDF documents and other order attachments are linked as document records on the corresponding Order or Third Party.

If the Circle Commerce customer runs multiple entities or divisions under one CircleHub instance, we handle this in Dolibarr through either separate Third Party records with a custom entity field or through Dolibarr's multi-company module if the customer's Dolibarr installation has this module enabled. We document the entity mapping during scoping and apply the chosen strategy consistently across all migrating objects. This is a scoping-phase decision because Dolibarr's multi-company module changes the import batch architecture.