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.
Source and external id
Section titled “Source and external id”Every synced record is addressed by two values:
- source: the system it comes from, named by you, such as
erp,stripeormagento2: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.
Matching records the CRM already has
Section titled “Matching records the CRM already has”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.
References
Section titled “References”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.
Orders, invoices and payments
Section titled “Orders, invoices and payments”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.
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" }'Batches
Section titled “Batches”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.
Looking a record up
Section titled “Looking a record up”GET /v1/products/{productId}/sync/{type}/{source}/{externalId} returns the record a source knows by that id, or 404.
Scopes
Section titled “Scopes”Syncing needs crm:write; stores are account configuration and need crm:configure. The CRM sync preset has both.