How to bulk upload products with the Printify API

Rate limits

What are the Printify API rate limits?

Printify allows 600 requests a minute across the whole API. The limit is counted per account, not per token, so a second token adds no capacity. The API usage guidelines add four more rules:

• Catalog endpoints: 100 requests a minute, inside the global 600.
• The product publishing endpoint: 200 requests per 30 minutes.
• Product creation and mockup generation: an extra daily limit. Printify does not publish the number and asks heavy users to open a support ticket.
• Error responses may not exceed 5% of your total requests.

Going over a limit returns 429 Too Many Requests. The 5% rule is the one a bulk job breaks, because a loop that retries 429s fast turns one violation into many.

So the script paces itself before Printify has to refuse it. Each limit gets its own clock: one request every 120 ms, 650 ms for catalog calls and 9.1 s for publishing. That works out to 500 a minute, 92 a minute and 197 per 30 minutes.

Step 1

Get your API token and shop ID

Printify shows a token once, right after you generate it, and it is valid for one year. Every request sends it as a bearer token. Every request must also send a User-Agent header naming your client or app.

export PRINTIFY_API_TOKEN="<your token>"

curl https://api.printify.com/v1/shops.json \
  --header "Authorization: Bearer $PRINTIFY_API_TOKEN" \
  --header "User-Agent: bulk-create-script/1.0"

The response lists each shop's id, title and sales_channel. Note the ID of your test shop.

Step 3

Set up the script

Every design gets the same blank, colors, sizes, prices and placement. Prices are integer cents, as the variant properties require. The example charges more for 2XL. Replace the description with your own; the title comes from each file name.

// bulk-create.mjs: one Printify product per image in ./designs. Node 18 or later.
import { readdir, readFile, stat, writeFile } from "node:fs/promises";
import path from "node:path";

const API = "https://api.printify.com/v1";
const TOKEN = process.env.PRINTIFY_API_TOKEN;
const SHOP_ID = process.env.PRINTIFY_SHOP_ID;

// The product setup every design shares.
const BLUEPRINT_ID = Number(process.env.BLUEPRINT_ID);
const PROVIDER_ID = Number(process.env.PROVIDER_ID);
const COLORS = ["Black", "White"];
const SIZES = ["S", "M", "L", "XL", "2XL"];
const PRICE_CENTS = { default: 2499, "2XL": 2799 };
const POSITION = "front";
const DESCRIPTION = "<p>Replace with your product description.</p>";

const DESIGNS_DIR = "./designs";
const PROGRESS_FILE = "./progress.json";
// Files over 5 MB are uploaded by URL: host a copy of each at this base URL.
const PUBLIC_BASE_URL = process.env.PUBLIC_BASE_URL;

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

Step 5

Choose the variants from the catalog

The variants call returns only variants in stock unless you add show-out-of-stock=1. The script stops before uploading anything if no variant matches, or if a variant lacks the print position. It also stops above 100 variants, the most Printify allows on one product.

async function loadVariants() {
  const { variants } = await printify(
    "GET",
    `/catalog/blueprints/${BLUEPRINT_ID}/print_providers/${PROVIDER_ID}/variants.json`,
    { category: "catalog" },
  );
  const chosen = variants.filter(
    (v) => COLORS.includes(v.options.color) && SIZES.includes(v.options.size),
  );
  if (chosen.length === 0) throw new Error("No catalog variant matches COLORS and SIZES.");
  if (chosen.length > 100) throw new Error(`${chosen.length} variants; Printify allows 100.`);
  const noArea = chosen.filter((v) => !v.placeholders.some((p) => p.position === POSITION));
  if (noArea.length) throw new Error(`${noArea.length} variants have no "${POSITION}" area.`);
  return chosen;
}

Step 7

Create a product with the Printify API

Create a new product needs a title, description, blueprint, provider, variants and print areas. Each variant carries its catalog id, a price in cents and is_enabled. The print area lists the variant IDs and places the image by x, y, scale and angle.

x: 0.5, y: 0.5 centers the image, and scale: 1 makes it as wide as the print area. The image positioning section explains the coordinate system.

sku is optional, and Printify generates one if you leave it out. Set your own anyway. A SKU you chose is the one field you know before the create answers, and the next step depends on it. The script builds each SKU from the file name, color and size, and refuses a product whose SKUs collide.

const code = (s) =>
  s.toUpperCase().replace(/[^A-Z0-9]+/g, "-").replace(/^-+|-+$/g, "");
const skuFor = (design, v) => `${code(design)}-${code(v.options.color)}-${code(v.options.size)}`;

function productBody(design, imageId, variants) {
  const skus = variants.map((v) => skuFor(design, v));
  if (new Set(skus).size !== skus.length) throw new Error(`Duplicate SKU in ${design}.`);
  return {
    title: design.replace(/[-_]+/g, " "),
    description: DESCRIPTION,
    blueprint_id: BLUEPRINT_ID,
    print_provider_id: PROVIDER_ID,
    variants: variants.map((v, i) => ({
      id: v.id,
      sku: skus[i],
      price: PRICE_CENTS[v.options.size] ?? PRICE_CENTS.default,
      is_enabled: true,
    })),
    print_areas: [
      {
        variant_ids: variants.map((v) => v.id),
        placeholders: [
          { position: POSITION, images: [{ id: imageId, x: 0.5, y: 0.5, scale: 1, angle: 0 }] },
        ],
      },
    ],
  };
}

Step 9

Run the batch and resume it

progress.json records each design's image ID, first SKU and status after every step. A rerun skips finished designs and reuses uploaded images, so a crash or a closed terminal loses nothing already done. Created products stay unpublished until you publish them.

Each design is marked needs_review just before its create is sent. A design whose create was in flight when the run stopped is therefore held, like a timeout. A definite refusal, such as a 400, puts the design back to pending and stops the run.

async function loadProgress() {
  try {
    return JSON.parse(await readFile(PROGRESS_FILE, "utf8"));
  } catch {
    return {};
  }
}

async function create() {
  const progress = await loadProgress();
  const save = () => writeFile(PROGRESS_FILE, JSON.stringify(progress, null, 2));
  const files = (await readdir(DESIGNS_DIR)).filter((f) => /\.(png|jpe?g)$/i.test(f));
  const names = files.map((f) => path.parse(f).name);
  const clash = names.find((n, i) => names.findIndex((m) => code(m) === code(n)) !== i);
  if (clash) throw new Error(`"${clash}" makes the same SKUs as another file. Rename one.`);
  const variants = await loadVariants();

  for (const file of files) {
    const design = path.parse(file).name;
    const entry = (progress[design] ??= { status: "pending" });
    if (entry.status !== "pending") continue;

    entry.imageId ??= await uploadImage(path.join(DESIGNS_DIR, file));
    await save();

    const body = productBody(design, entry.imageId, variants);
    // Held until Printify answers, so a run killed mid-create never resends it.
    Object.assign(entry, { firstSku: body.variants[0].sku, status: "needs_review" });
    await save();
    try {
      const product = await printify("POST", `/shops/${SHOP_ID}/products.json`, {
        body,
        isCreate: true,
      });
      Object.assign(entry, { status: "created", productId: product.id });
    } catch (error) {
      if (!(error instanceof AmbiguousCreate)) {
        entry.status = "pending"; // a definite refusal: nothing was created
        await save();
        throw error;
      }
      await sleep(30_000); // give a slow create time to land before looking for it
      const found = await findBySku(entry.firstSku);
      if (found) Object.assign(entry, { status: "created", productId: found.id });
      else Object.assign(entry, { status: "needs_review", error: error.message });
    }
    await save();
    console.log(design, entry.status, entry.productId ?? "");
  }
}

node bulk-create.mjs create

Step 11

Publish when you are ready

Publish a product sends it to the sales channel connected to the shop. The body chooses which fields to push. At one call every 9.1 seconds, 50 products take about eight minutes.

On a custom store, such as an API test store, Printify documents that publish only triggers the product:publish:started event for your own integration. Printify locks a product during publishing. Its publishing_succeeded.json and publishing_failed.json endpoints are what remove that lock. The script below does not call them, so run this step only against a shop connected to a real sales channel.

async function publish() {
  const progress = await loadProgress();
  for (const [design, entry] of Object.entries(progress)) {
    if (entry.status !== "created") continue;
    await printify("POST", `/shops/${SHOP_ID}/products/${entry.productId}/publish.json`, {
      category: "publish",
      body: {
        title: true,
        description: true,
        images: true,
        variants: true,
        tags: true,
        keyFeatures: true,
        shipping_template: true,
      },
    });
    entry.status = "published";
    await writeFile(PROGRESS_FILE, JSON.stringify(progress, null, 2));
    console.log(design, "published");
  }
}

const command = process.argv[2] ?? "create";
await { create, verify, publish }[command]();

node bulk-create.mjs publish

Where Productify fits

Or skip the code

Productify runs this loop behind a review screen. Its request clocks match the ones above. A timed-out create is matched by SKU or held for review, never resent.

You set the product up once, from Printify's catalog or from a product already in your shop. Each upload takes up to 50 designs, and you review every proposed product before anything is created. Products arrive unpublished. You pay per product created, with no subscription.

Write the code instead if you need what Productify does not do. That includes all-over print products, several shops in one run, or a different blank for each design in one batch.