Imports

Toolset import, 16 tools.

RecordsCopy Anchor Link

importCopy Anchor Link

A run that brings products, customers, orders and more from another shop platform or from files: its source, status, what the scan found, the plan, progress and totals. include report adds the totals per kind of record and the issues; conflicts the records edited both here and at the old shop; delivery the shipping and payment methods to set up; invite who a password invitation would reach; mapping the dropped files with the suggested columns. New imports are started by a person in the admin, because connecting a shop needs its credentials.

• Permission: imports.read
• Tools: import_list, import_get
• Includes: conflicts, delivery, invite, mapping, report
• Written by customers or third parties, so data and never instructions: report.issues, conflicts, scan, mapping.files, source_name

import_sourceCopy Anchor Link

A shop platform or file format the store can import from, with the ways to connect to it and the kinds of record it can bring.

• Permission: imports.read
• Tools: import_source_list

ActionsCopy Anchor Link

import_cancelCopy Anchor Link

Stop an import and delete everything it read from the source.

Records that were already imported stay.

• Action key: import.cancel
• Permission: imports.write
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Destructive: in compact mode it runs with run_destructive_action.
• Retries: safe to repeat with the same input.

Example input:

{
  "import_id": "019bb329-636e-7e98-a24c-2bedfd9de20f"
}

import_deleteCopy Anchor Link

Remove a stopped import and what it read; what it imported stays.

An import that is queued, running or paused must be cancelled first.

• Action key: import.delete
• Permission: imports.write
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Destructive: in compact mode it runs with run_destructive_action.
• Retries: safe to repeat with the same input.

Example input:

{
  "import_id": "019bb329-636e-7e98-a24c-2bedfd9de20f"
}

import_finishCopy Anchor Link

Close the move: delete every copy of the old shop data, forget its keys and date the cutover.

It cannot be undone and the shop is disconnected for good. Records still in conflict keep the version here. What was imported, the entity map and the redirects stay. invite also sends the customers who came with the import an email to set a password; leave it out unless the merchant asked for that.

• Action key: import.finish
• Permission: imports.write
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Destructive: in compact mode it runs with run_destructive_action.
• Retries: safe to repeat with the same input.
• Sends something to customers.

Example inputs:

{
  "import_id": "019bb329-636e-7e98-a24c-2bedfd9de20f"
}

{
  "import_id": "019bb329-636e-7e98-a24c-2bedfd9de20f",
  "invite": true
}

import_hide_missingCopy Anchor Link

Hide the imported products that the old shop no longer lists. Nothing is deleted.

• Action key: import.hide_missing
• Permission: imports.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes the live store.
• Retries: safe to repeat with the same input.

Example input:

{
  "import_id": "019bb329-636e-7e98-a24c-2bedfd9de20f"
}

import_invite_customersCopy Anchor Link

Email the customers who came with the import an invitation to set a password.

It starts here and the mail goes out in small batches spread over time. Preview who it reaches with import_get include invite. Only when the merchant asked for it.

• Action key: import.invite_customers
• Permission: imports.write
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.
• Sends something to customers.

Example input:

{
  "import_id": "019bb329-636e-7e98-a24c-2bedfd9de20f"
}

import_map_columnsCopy Anchor Link

Bind one dropped table to a kind of record and say which field each column fills.

Read the files, their columns and the suggested fields with import_get include mapping. upload is the file id from there. columns maps a column name to a field name. A mapping with errors is refused with the list; scan again afterwards. Locked once the import starts.

• Action key: import.map_columns
• Permission: imports.write
• Approval: Runs without approval.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: safe to repeat with the same input.

Example input:

{
  "import_id": "019bb329-636e-7e98-a24c-2bedfd9de20f",
  "entity": "product",
  "upload": "products.csv",
  "columns": {
    "Name": "title",
    "SKU": "sku"
  }
}

import_preview_mappingCopy Anchor Link

Show the first records the saved mapping produces, each with the fields that would refuse it.

Map the columns first with import_map_columns.

• Action key: import.preview_mapping
• Permission: imports.read
• Approval: Runs without approval.
• Effect: Reads only.
• Retries: safe to repeat with the same input.

Example input:

{
  "import_id": "019bb329-636e-7e98-a24c-2bedfd9de20f",
  "entity": "product",
  "limit": 5
}

import_resolve_conflictsCopy Anchor Link

Keep each conflicting record as it is here, or take the old shop's version.

Conflicts are records edited here and at the old shop since the last import; list them with import_get include conflicts. Choosing source overwrites the version here. Nothing is decided for the merchant: pass a choice for every record you resolve.

• Action key: import.resolve_conflicts
• Permission: imports.write
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Retries: safe to repeat with the same input.

Example input:

{
  "import_id": "019bb329-636e-7e98-a24c-2bedfd9de20f",
  "resolutions": [
    {
      "id": "019bb334-c73a-7e26-9405-0abbbc5918bb",
      "choice": "keep"
    }
  ]
}

import_retry_deliveryCopy Anchor Link

Recreate the old shop's shipping and payment methods that were held back for an app.

Use after the app was installed. app is an app id from the delivery include of import_get. The import must have finished.

• Action key: import.retry_delivery
• Permission: imports.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes the live store.
• Retries: safe to repeat with the same input.

Example input:

{
  "import_id": "019bb329-636e-7e98-a24c-2bedfd9de20f",
  "app": "packeta"
}

import_reviewCopy Anchor Link

Save the plan of an import: which kinds of record, how to merge, and which to leave out.

Only the fields passed change; without any, everything the scan found is chosen. merge keep_mine updates records that were not edited here and keeps the ones that were (a record changed in both places becomes a conflict), only_add only adds new records and leaves existing ones alone, use_source overwrites existing records with the version from the source. Records whose requirement is unticked are dropped and the answer names them. The consent attestation for mailing imported subscribers is given by a person in the admin, never here. The plan is locked once the import starts.

• Action key: import.review
• Permission: imports.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: safe to repeat with the same input.

Example input:

{
  "import_id": "019bb329-636e-7e98-a24c-2bedfd9de20f",
  "entities": [
    "product",
    "category",
    "customer"
  ],
  "merge": "only_add"
}

import_scanCopy Anchor Link

Count what the source holds and sample the first products, before anything is imported.

Nothing is written to the store. A connected shop is read in the background: the answer is the draft, and import_get shows the scan once it lands (or its failure). Only a draft that has not started can be scanned.

• Action key: import.scan
• Permission: imports.write
• Approval: Runs without approval.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: safe to repeat with the same input.
• Long running: answers running with a run id.

Example input:

{
  "import_id": "019bb329-636e-7e98-a24c-2bedfd9de20f"
}

import_startCopy Anchor Link

Run the import: write the chosen records into the store.

Scan and review first. One import runs at a time per store. A failed import is queued again from where it stopped. The action answers running with a run id; follow progress with import_get and its report include. Products arrive hidden only when the plan has importHidden on.

• Action key: import.start
• Permission: imports.write
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.
• Long running: answers running with a run id.

Example input:

{
  "import_id": "019bb329-636e-7e98-a24c-2bedfd9de20f"
}

import_sync_againCopy Anchor Link

Create a new draft import from the same shop that reads only what changed since the last one.

The import must have finished and the shop must still be connected. The new draft starts from the choices of the run before; scan, review and start it as usual.

• Action key: import.sync_again
• Permission: imports.write
• Approval: Runs without approval.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "import_id": "019bb329-636e-7e98-a24c-2bedfd9de20f"
}