Skip to content

Shop integrations

An integration pulls a shop’s catalog, customers and orders into a product’s CRM, first the history you choose and then every 15 minutes. It is set up in the admin under Customers → Integrations, or through the API.

Platform type Credentials
Magento 2 / Adobe Commerce magento2 { "accessToken" }: an integration’s access token (System → Extensions → Integrations). On 2.4.4 and later, allow OAuth access tokens as bearer tokens (Stores → Configuration → Services → OAuth).
Magento 1 / OpenMage magento1 { "apiUser", "apiKey", "currency" }: a SOAP/XML-RPC API user (System → Web Services), and the shop’s currency, which its API cannot tell.
Terminal window
curl -X POST "https://api.motenya.app/v1/products/$PRODUCT/integrations" \
-H "Authorization: Bearer $MOTENYA_KEY" -H "Content-Type: application/json" \
-d '{ "type": "magento2", "name": "Casa Verde RO", "baseUrl": "https://casa-verde.ro",
"credentials": { "accessToken": "…" }, "historyMode": "months", "historyMonths": 12 }'

The shop is contacted first; a refusal comes back as CONNECTION_REFUSED (credentials) or CONNECTION_FAILED (anything else), with a message saying what to check. POST …/integrations/test runs the same check without saving. Credentials are stored encrypted and never returned; credentialsHint shows which ones are stored.

Each website of the shop becomes a store. historyMode sets how far back the first sync reaches: none (only changes from now on), months (the last historyMonths, 12 by default) or full.

  • Catalog: products, with their SKU and price.
  • Customers: each one a client (a company when their default billing address names one) with their person as a contact. Someone already in the CRM with the same email is the same person.
  • Orders: with their store, buyer, status, payment status (from the order’s totals), totals, addresses and lines. Guest orders find or create the contact by email.

Records keep the shop’s ids under the integration’s source (magento2:<integration id>), so GET …/sync/orders/{source}/{orderId} finds an order by its Magento id.

An integration reports phase (history until the first sync finishes, then live), counts of records synced and refused, the last refused record, and syncedUntil: everything changed in the shop before it is in the CRM.

When the shop does not answer or asks to slow down, the integration retries in five minutes and says so in lastError. When it refuses the credentials, the integration’s status becomes error and it waits: replace the credentials or the address (PATCH …/integrations/{id}) and it starts again. POST …/integrations/{id}/sync runs it now. Deleting an integration keeps what it synced.

Managing integrations needs crm:configure; reading them, crm:read.