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:
- bash / zsh
- fish
- PowerShell
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)
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
set CATALOG_ID (jq -r '.id' catalog.json)
curl.exe --fail-with-body -X POST "$env:GHOSTPULL_URL/api/v1/commerce/catalogs" `
-H "x-api-key: $env:GHOSTPULL_API_KEY" -H "Content-Type: application/json" `
--data '{\"name\":\"My shop\",\"shopSystem\":\"shopify\",\"currency\":\"EUR\"}' --output catalog.json
$env:CATALOG_ID = (Get-Content catalog.json -Raw | ConvertFrom-Json).id
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:
- bash / zsh
- fish
- PowerShell
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
jq -n --argjson bytes (wc -c < products_export.csv | string trim) \
'{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
set 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
$body = @{ fileName = "products_export.csv"; bytes = (Get-Item ./products_export.csv).Length } | ConvertTo-Json -Compress
$body | Set-Content -Encoding utf8NoBOM import-request.json
curl.exe --fail-with-body -X POST "$env:GHOSTPULL_URL/api/v1/commerce/imports" `
-H "x-api-key: $env:GHOSTPULL_API_KEY" -H "Content-Type: application/json" `
--data-binary "@import-request.json" --output import.json
$import = Get-Content import.json -Raw | ConvertFrom-Json
$env:IMPORT_ID = $import.import.id
$import.upload.headers.psobject.Properties | ForEach-Object { "$($_.Name): $($_.Value)" } | Set-Content -Encoding utf8NoBOM upload-headers.txt
curl.exe --fail-with-body -X PUT "$($import.upload.url)" -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:
- bash / zsh
- fish
- PowerShell
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"
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"
curl.exe --fail-with-body -X POST "$env:GHOSTPULL_URL/api/v1/commerce/imports/$env:IMPORT_ID/read" `
-H "x-api-key: $env:GHOSTPULL_API_KEY" -H "Content-Type: application/json" --data '{}'
curl.exe --fail-with-body "$env:GHOSTPULL_URL/api/v1/commerce/imports/$env:IMPORT_ID" `
-H "x-api-key: $env: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:
- bash / zsh
- fish
- PowerShell
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\"}"
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\"}"
curl.exe --fail-with-body -X POST "$env:GHOSTPULL_URL/api/v1/commerce/imports/$env:IMPORT_ID/start" `
-H "x-api-key: $env:GHOSTPULL_API_KEY" -H "Content-Type: application/json" `
--data "{\`"catalogId\`":\`"$env: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.