Planning Your Integration

Before choosing a method, it helps to settle what data Tulip needs, where it comes from, and what order it has to arrive in. This page covers all three. It applies whichever path you use — Integration Builder, the API, or file imports.

What Tulip needs to go live

Five feeds get clienteling working. Everything after that makes it better.

Must have

The platform is usable once these are flowing.

FeedWhat it gives store teams
StoresThe store list, so people and activity can be attributed to a location
EmployeesAssociate accounts, so each person signs in and owns their own book of clients
CustomersThe client records associates search, open and follow up with
Product catalogWhat associates browse, recommend and share
OrdersPurchase history, which is what makes a recommendation informed rather than a guess

Nice to have

These deepen what the platform can do.

FeedWhat it adds
PricesCorrect pricing in the app, including by market
InventoryLive stock, so associates stop promising what is not there
Customer preferencesSizes, interests and notes that make outreach personal
LoyaltyTier and status alongside the customer record
Product imagesCatalog and shared looks that a customer wants to open

Feeds can arrive in any order and be added over time. You do not need all ten to start.

How your data lines up with Tulip

In most cases the mapping is more obvious than it first appears — the concepts match, only the field names differ.

What you call itWhere it lands in Tulip
Stores, locations, branches, doorsStores
Sales associates, staff, usersEmployees
Customer or client records, contactsCustomers
Product master, article master, PIM dataCatalog — Products
Sales, transactions, receiptsOrders
Price lists, price booksPrices
Multi-location stock, availabilityInventory

Field names, extra attributes and localized values are handled by mapping rules — see Data Bridge — so your systems do not have to change shape to send data to Tulip.

Identifiers: the one decision worth making early

Every record you send should carry the identifier your system already uses for it — its external ID. Tulip stores it alongside its own internal ID and matches on it from then on.

This is what makes a sync repeatable. Send the same customer again with the same external ID and it updates the existing record rather than creating a second one. Get it wrong, or change it later, and you get duplicates that are tedious to unpick.

Two things to settle before the first load:

  • Pick an identifier that is stable. A loyalty number or CRM record ID is a good choice. An email address is not — people change them.
  • Use shared keys where they exist. EAN or GTIN for products, and your customer reference for CRM records, make matching deterministic on both sides.

You do not need to store Tulip’s own generated ID in your system. Sending your external ID is enough to find, update and link a record, so nothing on your side has to change to accommodate Tulip’s identifiers.

See Understanding Tulip IDs for how internal and external IDs relate.

Dependencies and load order

Some records refer to others, so they have to exist first — a variant cannot be created before its product, and a product cannot be filed under a category that is not there yet.

A sequence that works for an initial load:

Stores → Employees → Catalogs → Categories → Products → Variants → Customers → Orders → Prices → Inventory

One trap worth knowing: if your products have variants, their option types and option values — size, colour and their possible values — must be created before the variants that use them. This is a common gotcha for first-time loads.

The full dependency map is in Resource Dependencies — Adding resources in the correct order. It is written against the Bulk API, but the dependencies it describes are the same whichever path you use.

Keeping data current

Once the initial load is done, the question becomes how updates arrive.

  • Send only what changed. Most feeds do not need a nightly full refresh. Sending changed records is faster, cheaper, and far less likely to overwrite something in the process.
  • Prefer update-or-create. Tulip’s PATCH endpoints update the fields you send and leave the rest alone, creating the record if it does not exist yet. That makes a re-run safe — a feed that runs twice does not do damage.
  • Match the frequency to the data. Customer and order updates are worth doing in real time, because an associate looking at a stale client record is the problem the platform exists to solve. Catalog changes are usually fine on a nightly or hourly schedule. Prices depend on the retailer: where they move with promotions, markdowns or local pricing, they may need to arrive as often as customer data; where they are stable, a scheduled refresh is enough.
  • Validate before you load. Catching an incomplete record at the door is much cheaper than finding it in an associate’s client book later. See Data Bridge validators.

What Tulip needs from you

For a delivery-led onboarding, three things:

  1. Access — API credentials, or a file drop we can read from
  2. Someone who knows the data — to confirm the mapping is right, which is faster than us inferring it
  3. A round of testing before go-live, against real records
← Introduction
Customer Merge →