Skip to content

Syncing another system

The sync endpoints let another system push its customers, products, orders, invoices and subscriptions into a product’s CRM without keeping Motenya’s ids. You address each record by your id for it, and repeating a call never creates a duplicate.

Every synced record is addressed by two values:

  • source: the system it comes from, named by you, such as erp, stripe or magento2:casa-verde. It is 1–64 characters: lowercase letters, digits and . _ : -. Use one source per system (or per shop, if you sync several), and keep it stable.
  • external id: the record’s id in that system, up to 128 characters.
PUT /v1/products/{productId}/sync/{type}/{source}/{externalId}

where {type} is stores, contacts, clients, catalog-items, orders or subscriptions. The body is the record’s fields; only the fields you send change. The response says whether the call created the record or updated an existing one:

{ "entity": "client", "id": "01JD3R…", "created": true, "record": { "id": "01JD3R…", "name": "Atelier Nord SRL", "…": "…" } }

The same record can be known to several sources: a person can be a Shopify customer and a Stripe customer at once.

The first time a source sends an external id, Motenya looks for a record it already holds before creating one:

Type Matched by
Contact Any of its emails. People who wrote in through tickets are not duplicated.
Client VAT number.
Catalog item SKU, in the same store (or both without a store).
Order Number, in the same store (or among orders without a store).
Store, subscription Not matched; always created.

A contact sync adds emails and never removes the ones added elsewhere.

A record can point at others by their ids in the same source, so you never look up Motenya ids:

Field On
storeExternalId catalog items, orders, subscriptions
contactExternalId, clientExternalId orders, subscriptions
subscriptionExternalId orders (a subscription’s invoice)
catalogItemExternalId subscriptions, and each order line
clientExternalIds contacts (the clients they belong to)

A reference to an id the source has not sent yet fails with 422 and a *_NOT_FOUND code naming the field. Send records in dependency order: stores, then clients and contacts, then catalog items, then subscriptions, then orders. You can also pass Motenya ids (storeId, contactId, …) directly.

For a buyer with no id in your system (a guest checkout), send contactEmail and contactName on the order: Motenya uses the contact with that email, or creates one.

An order carries its lines, totals and statuses. A subscription’s invoice is an order with subscriptionExternalId (or subscriptionId) and its billing period (periodStart, periodEnd). It needs no store; on creation it takes the subscription’s customer, currency and a line for the plan unless you send them.

Record a payment by updating the order’s paymentStatus (unpaid, partially_paid, paid, refunded, void) and paidAt. Send dueAt so unpaid ones show as overdue. An order with no payment status counts as paid, the way most shops report orders.

shipments and documents (invoices and credit memos) each carry their own externalId. Sending them replaces what this source sent for the order before; those added by hand or by another source stay.

Terminal window
curl -X PUT "https://api.motenya.app/v1/products/$PRODUCT/sync/orders/erp/INV-2026-0042" \
-H "Authorization: Bearer $MOTENYA_KEY" -H "Content-Type: application/json" \
-d '{
"subscriptionExternalId": "SUB-17",
"number": "INV-2026-0042",
"periodStart": "2026-11-01T00:00:00Z",
"periodEnd": "2026-12-01T00:00:00Z",
"paymentStatus": "paid",
"paidAt": "2026-11-03T08:12:00Z"
}'

POST /v1/products/{productId}/sync/batch takes one source and up to 100 records of any type:

{
"source": "erp",
"records": [
{ "entity": "client", "externalId": "C-1042", "data": { "name": "Atelier Nord SRL" } },
{ "entity": "contact", "externalId": "P-7", "data": { "name": "Ion Pop", "emails": ["ion@atelier-nord.ro"], "clientExternalIds": ["C-1042"] } },
{ "entity": "subscription", "externalId": "SUB-17", "data": { "clientExternalId": "C-1042", "planName": "Team", "amount": "290", "currency": "EUR", "interval": "month" } }
]
}

Records are applied in order, each on its own: a record can name one sent earlier in the batch, and a failing record is rolled back and reported while the rest still go through. The response has one result per record, in order:

[
{ "index": 0, "entity": "client", "externalId": "C-1042", "ok": true, "id": "01JD3R…", "created": true, "userErrors": [] },
{ "index": 1, "entity": "contact", "externalId": "P-7", "ok": true, "id": "01JD3S…", "created": true, "userErrors": [] },
{ "index": 2, "entity": "subscription", "externalId": "SUB-17", "ok": true, "id": "01JD3T…", "created": true, "userErrors": [] }
]

A failed record has "ok": false, a null id and its userErrors, such as { "code": "CLIENT_NOT_FOUND", "field": ["input", "clientExternalId"], "message": "…" }.

To import history, page through your system and send each page as a batch. Re-running an import is safe.

GET /v1/products/{productId}/sync/{type}/{source}/{externalId} returns the record a source knows by that id, or 404.

Syncing needs crm:write; stores are account configuration and need crm:configure. The CRM sync preset has both.