Create an import

POST/imports

Costs 2 rate-limit points · Rate limits

Start a bulk import of historic orders from CSV text (csv), as the bulk import page does. Columns are the page's template (sku, filename, external_url, data_type, link_to_product, custom_product) in that order, or column_mapping {sku: 0, filename: 1, ...} gives the 0-based index of each. data_type is sku or variant_id (blank means sku); link_to_product and custom_product are yes, no or blank. Rows run in the background; follow progress with GET /imports/:id.

Only one import runs per shop at a time (409 while one is in progress). Rows that reference unknown files, SKUs or urls are reported as 422 with code validation_warnings and nothing is imported; send proceed_with_warnings: true to import the valid rows and skip the rest.

Also searched asimport orders from csvbulk importupload a csv of ordersstart an import

Request body

csvstringRequired
Example: sku,filename,external_url,data_type,link_to_product,custo…
filenameany
column_mappingany
proceed_with_warningsboolean
Example: false

Errors

401

Missing or invalid API key.

409

The request conflicts with the current state (an order Shopify is not ready to fulfil, a digital product that already exists). Nothing was changed; read the message, don't retry blindly.

422

The request failed validation, or sent a key the action does not take (code: "unknown_parameters" with unknown and accepted). Nothing was saved.

429

Rate limited. Cost-weighted per API key, shared with API v1: a read costs 1 point, a write 2, 40 points per fixed 60-second window. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time the window ends); a 429 adds Retry-After (seconds), retry_after, retryable: true and a next_step in the body. A 429 did nothing: wait retry_after seconds, then send the same request again. The budget is per key, so every tool or script using the key shares it; prefer one list call with per_page over many single reads.

Every error has the same shape: see Errors.

POST/imports

curl -X POST "https://app.filemonk.io/api/v2/external/imports" \
  -H "X-Auth-Token: $FILEMONK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "csv": "sku,filename,external_url,data_type,link_to_product,custom_product\nWATERCOLOUR-1,guide.pdf,,sku,yes,no\n",
    "proceed_with_warnings": false
  }'

const res = await fetch("https://app.filemonk.io/api/v2/external/imports", {
  method: "POST",
  headers: {
    "X-Auth-Token": process.env.FILEMONK_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "csv": "sku,filename,external_url,data_type,link_to_product,custom_product\nWATERCOLOUR-1,guide.pdf,,sku,yes,no\n",
    "proceed_with_warnings": false
  }),
});
const data = await res.json();

import os
import requests

res = requests.post(
    "https://app.filemonk.io/api/v2/external/imports",
    headers={"X-Auth-Token": os.environ["FILEMONK_API_KEY"]},
    json={
        "csv": "sku,filename,external_url,data_type,link_to_product,custom_product\nWATERCOLOUR-1,guide.pdf,,sku,yes,no\n",
        "proceed_with_warnings": False
    },
)
data = res.json()

require "net/http"
require "json"

uri = URI("https://app.filemonk.io/api/v2/external/imports")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["FILEMONK_API_KEY"], "Content-Type" => "application/json")
req.body = {
  csv: "sku,filename,external_url,data_type,link_to_product,custom_product\nWATERCOLOUR-1,guide.pdf,,sku,yes,no\n",
  proceed_with_warnings: false
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

Response

No body

{
  "id": "de0d7253-b5ed-42cc-921b-e1d90bf2cd76",
  "name": "orders-import.csv",
  "status": "processing",
  "rows": {
    "total": 1,
    "completed": 0,
    "failed": 0
  },
  "completed_at": null,
  "created_at": "2026-10-30T23:03:04Z",
  "queued": true
}

{
  "errors": [
    "Invalid API key"
  ]
}

{
  "errors": [
    "This product already has a digital product"
  ]
}

{
  "errors": [
    "access.download_limit_count must be an integer of at least 0"
  ],
  "field_errors": {
    "access.download_limit_count": [
      "must be an integer of at least 0"
    ]
  }
}

{
  "errors": [
    "You have exceeded the rate limit of 40 points per 60 seconds. Read requests cost 1 point(s) and write requests cost 2 point(s). Please retry after 12 second(s)."
  ],
  "code": "rate_limited",
  "retry_after": 12,
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit of 40 points per 60 seconds. Read requests cost 1 point(s) and write requests cost 2 point(s). Please retry after 12 second(s)."
}