Add a file source
Sometimes a single part of your store lives somewhere else. A common example: you’re moving your storefront from one platform, but your gift cards are managed in a different system. Instead of connecting that second system, you can upload its data as a file and Graftport will treat it like any other source.
Two file formats are supported:
- CSV — a spreadsheet export, one row per record.
- JSONL — a JSON Lines file, one JSON object per line (
.jsonl). Use this when your export has nested values (objects or lists) that don’t fit neatly in a flat spreadsheet.
A resource can have several sources at once — the connected platform and one or more uploaded files. Each source has its own mapping, and its records are imported alongside the others.
Migrating entirely from files
Sometimes there’s no store to connect to at all — the shop is offline, custom-built, or its data only exists as exports. In that case pick File upload as the source platform when you create the migration.
Graftport then asks for no store credentials. On the Choose resources step, tick the resources you have files for; each is created with a blank mapping, ready for you to attach a file. Everything after that is identical to the steps below — the only difference is that no resource has a connected-platform row, because there’s no connected platform.
A resource with no file attached yet has nothing to run. If you start a run before uploading, Graftport stops with a message telling you the selected resources have no source — upload the file, then run again.
Add a file source to a resource
Add the resource
On the migration’s Resources tab, click Add resource and pick what the file contains (Gift cards, Discount codes, …). Resources that don’t have a built-in mapping start with a blank one you’ll fill in.
Open the source list
Each resource shows a list of its sources directly below the resource name. When the connected platform can supply that resource, it appears as the first row. Some resource types (such as Gift cards) aren’t provided by every platform; those have no platform row and are fed entirely from an uploaded file. Click Add source to attach a file.
Upload your file
Choose your .csv or .jsonl file or drag it onto the picker. Graftport
reads it — showing how many columns and rows it found. For a JSONL file the
columns are the fields (keys) found across your records.
Choose the original ID column
Pick the column that uniquely identifies each row — for gift cards that’s usually the card code or number. Graftport uses this to match rows across re-runs so the same record is never created twice.
Add source
Click Add source. Your file is stored securely, a mapping is created for it, and the data is imported right away so the mapping editor has real rows to work with.
For CSV, the separator is detected automatically — comma, semicolon, or tab — so spreadsheet exports from any region work without converting them first.
Map your columns
Each source gets its own mapping, because every file’s columns are different. Click the mapping link on the source’s row to open its editor. Your uploaded rows appear as the live sample, so you can see exactly what you’re working with. Map each column to the matching field on the target record, then Publish.
Until you’ve mapped at least the required fields for the resource, a run will produce empty or rejected records. Publish your mapping before starting a run.
Preparing a CSV file
- The first row must be a header row with column names.
- Use a comma
,as the separator and UTF-8 encoding (the default when you export from a spreadsheet). - Fields containing commas or line breaks should be wrapped in double quotes — again, the default for spreadsheet exports.
- Make sure your ID column has a value on every row; rows with a blank ID are skipped.
Preparing a JSONL file
- Put one JSON object per line (this is the JSON Lines /
.jsonlformat). Blank lines are ignored. - Every line must be a JSON object (
{ … }) — not an array or a bare value. - Use UTF-8 encoding.
- Nested objects and lists are kept as-is, so you can map them straight from your mapping.
- Make sure your ID field has a value in every record; records missing it are skipped.
Using an uploaded file as the only source
When the connected platform can supply a resource, it extracts from both the platform and any uploaded sources you add. If you want such a resource to come only from an uploaded file, remove the platform row from the source list using the × control on its row. Future runs will skip the platform extract for that resource and use only the uploaded sources shown. (Resources the platform can’t supply are upload-only already and have no platform row to remove.)
Removing the platform source requires at least one uploaded source to remain. A resource with no sources cannot run.
Replace a source’s file
Got a newer export, or fixed some rows and re-exported? Use the upload control on a source’s row to swap in the new file — no need to remove the source and add it back. You can also switch formats here (for example replace a CSV with a JSONL export). Your mapping stays exactly as you left it, so if the field names match, nothing else to do. If the new file has different or renamed fields, open the mapping afterwards and adjust the affected fields.
Replacing a file clears the records the old file brought in for that source; your next run re-imports from the new file.
Remove a source
Use the × control on a source’s row to remove it. Removing a source clears the records it brought in; it does not change anything already in your Shopify store.
You cannot remove the last remaining source for a resource — add another source first, or remove the resource entirely.
Removing a source also deletes its mapping. If you just want to update the file, use Replace a source’s file above instead — it keeps your mapping.