Skip to main content

Import products

Upload your shop's product export, check what Ghostpull read from it, then import it into a catalog. Ghostpull reads the CSV exports of Shopify, Shopware and WooCommerce, up to 50 MB. Importing needs products:write; following an import and reading products needs products:read.

Before you start​

Set GHOSTPULL_URL and GHOSTPULL_API_KEY as in the quickstart, and export the products from your shop as CSV, here products_export.csv.

1. Create a catalog​

createCatalog answers the catalog with its id. Create one catalog per shop and import into it again later:

curl --fail-with-body -X POST "$GHOSTPULL_URL/api/v1/commerce/catalogs" \
-H "x-api-key: $GHOSTPULL_API_KEY" -H "Content-Type: application/json" \
--data '{"name":"My shop","shopSystem":"shopify","currency":"EUR"}' --output catalog.json
CATALOG_ID=$(jq -r '.id' catalog.json)

2. Upload the export​

createProductImport answers the import and where to upload the file. PUT the file there with every upload header, without an API key:

jq -n --argjson bytes "$(wc -c < products_export.csv)" \
'{fileName:"products_export.csv",bytes:$bytes}' > import-request.json
curl --fail-with-body -X POST "$GHOSTPULL_URL/api/v1/commerce/imports" \
-H "x-api-key: $GHOSTPULL_API_KEY" -H "Content-Type: application/json" \
--data-binary @import-request.json --output import.json
IMPORT_ID=$(jq -r '.import.id' import.json)
jq -r '.upload.headers | to_entries[] | "\(.key): \(.value)"' import.json > upload-headers.txt
curl --fail-with-body -X PUT "$(jq -r '.upload.url' import.json)" \
-H @upload-headers.txt --data-binary @products_export.csv

The upload URL works for one hour, and a file once uploaded cannot be replaced: for another file, create another import.

When the export is at a public https URL, for example a shop's export link, importProductFileFromUrl fetches it instead, with {"url":"https://…"}, and starts reading it at once: go on with getProductImport in step 3. The download must finish within 45 seconds.

3. Read it​

readProductImport reads the file as the shop system its header row names. Nothing is stored yet. Ask getProductImport every few seconds until state is ready:

curl --fail-with-body -X POST "$GHOSTPULL_URL/api/v1/commerce/imports/$IMPORT_ID/read" \
-H "x-api-key: $GHOSTPULL_API_KEY" -H "Content-Type: application/json" --data '{}'
curl --fail-with-body "$GHOSTPULL_URL/api/v1/commerce/imports/$IMPORT_ID" \
-H "x-api-key: $GHOSTPULL_API_KEY"
{ "state": "ready", "shopSystem": "shopify", "preview": { "products": 1240, "variants": 3712, "images": 2980, "skippedCount": 2, "skipped": [{ "row": 17, "reason": "unreadable_price" }], … }, … }

preview counts what the import will store and lists the rows it leaves out, with the reason. A file that is no export Ghostpull knows ends as failed with commerce.unknown_shop_system; read it again with {"shopSystem":"shopware"} if you know better.

4. Import it​

startProductImport writes the products into the catalog. Ask getProductImport until state is done; written grows meanwhile:

curl --fail-with-body -X POST "$GHOSTPULL_URL/api/v1/commerce/imports/$IMPORT_ID/start" \
-H "x-api-key: $GHOSTPULL_API_KEY" -H "Content-Type: application/json" \
--data "{\"catalogId\":\"$CATALOG_ID\"}"
{ "state": "done", "written": 1240, "created": 12, "updated": 31, "unchanged": 1197, … }

Products are matched by their ID in the shop: a changed product is updated, an unchanged one only counted. A catalog runs one import at a time. A failed import can be started again.

5. Remove what the shop no longer has​

An import never deletes. After a complete import of all the shop's products, getCatalogImport with the import's ID counts the catalog's products the file did not hold, and removeMissingProducts removes them. Do not remove after importing a selection or a search: the shop still has the products it left out.

Send products without a file​

To keep a catalog in sync from your own code, send products in the product schema of the API reference with importCatalogProducts: make one UUID for the whole import, send it with every batch of at most 200 products and 2 MB, then remove what it did not send as in step 5. Sending a batch again is safe; a 429 names in Retry-After when to send it again.

Next​