Prepare your source data

Data source replication

When pushing data into Endear, you are able to replicate your source data 1-1. A customer record in your source will have an identical record in Endear. Similarly, an order record in your source will have an identical record in Endear.

Update semantics

The bulkUpsert* mutations perform a full replacement of each record, not a partial merge. As a result, to update a record, you must send the entire updated record again.

Unique identifiers

All syncing endpoints require that you pass a unique identifier to represent each record you pass to Endear. When choosing a unique identifier we recommend always using a unique, opaque primary key for each record. If you do not have primary keys, you can use an email address to represent a customer record; however, if your system does not enforce uniqueness on email address, records may be overwritten when they have the same email address.

Timestamps

Timestamps give Endear concurrency control: when two updates for the same record arrive close together (or out of order), the timestamp tells Endear which version is newer so the latest state always wins.

For real-time integrations, we strongly recommend passing timestamps with every record. Each update must carry a timestamp greater than the last one Endear has seen — if the timestamp does not increase, the update will be dropped.

For batch or one-off backfills, timestamps can be omitted. Endear will accept records in the order it receives them.

Backfilling vs. ongoing sync

Most integrations follow a two-phase lifecycle:

1. Backfill — A one-time bulk import of your historical data. Omit timestamps and send batches of up to 100 records per request. Work through data types in the Import order below.
2. Incremental sync — Ongoing updates as records change in your source. Pass timestamps so out-of-order events resolve correctly if sending updates in real-time. If you send updates in hourly or daily batches, you can omit timestamps.

Once you switch a record over to real-time, every subsequent update must carry a higher timestamp than the previous one or it will be dropped. If you send an update without a timestamp, Endear will always accept and apply that update.

Import order

When importing data, load data types in this order so referential dependencies resolve correctly:

1. Customers
2. Marketing subscriptions
3. Products
4. Product variants
5. Locations
6. Users
7. Orders
8. Order items
9. Refunds
10. Marketing events

Steps 1–6 can be run in parallel; step 7 should only start after steps 1–6 are complete, since orders reference customers, locations, users, products, and variants. Step 10 can also be run in parallel with steps 1–9.

Deletes

Set deleted_at on a record to soft delete it. Soft-deleted records are removed from the active dataset but retained for historical reporting and analytics.

For GDPR-style hard deletion of a customer and all associated personal data, use requestCustomerDeletion instead — deleted_at does not erase data.

Money values

All monetary fields use the MoneyInput shape:

{
  "amount": 19999,
  "precision": 2,
  "currency": "USD"
}

amount is an integer expressed in the smallest unit at the given precision. With precision: 2, an amount of 19999 represents $199.99. Always send integers — sending a decimal like 199.99 will be rejected.

Supported data types

Endear exposes a bulkUpsert mutation for each of the data types below. Required types form the foundation Endear needs to operate. Recommended types aren't strictly necessary, but they unlock significant additional functionality and we strongly suggest syncing them. The remaining types are optional.