Katalog-API2026-11Vorschau

Importe

Füg einen Angebotslink ein und erhalte seine Varianten und was dich der Verkauf jeder einzelnen kostet: die Ware, unsere Annahmegebühr von 12,00 CN¥ für das Paket des Verkäufers zu uns, die Pauschalsteuer von 14 %, dann der Versandweg, die Bearbeitungsgebühr von 50,00 CN¥ pro Paket und die Steuer darauf, die Marktplatzgebühr und den Preis, der deine Marge hält.

Importieren ist kostenlos, ohne Produktlimit. Du zahlst nur für das, was du bestellst.
Jeder Wert gilt für ein Stück, in einer eigenen Bestellung gekauft und in einem eigenen Paket versendet: ein gedropshippter Verkauf. Mehrere Stück in einer Bestellung oder einem Paket kosten weniger als hier angegeben.
Marktplatzgebühren sind standardmäßig der öffentliche Regelsatz des jeweiligen Marktplatzes. Schick deinen eigenen, wenn deine Kategorie oder dein Tarif abweicht.

Endpunkte

POST/v1/importsAus einem Link importieren
POST/v1/imports/{id}/analysisNeu bepreisen
GET/v1/imports/{id}Einen Import abrufen
GET/v1/importsImporte auflisten
POST/v1/imports/{id}/saveAls Produkt speichern

Das Import-Objekt

Ein Angebot, wie wir es lesen, mit den Kosten eines Verkaufs bis zur Haustür deines Käufers: die Ware, unsere Annahmegebühr von 12,00 CN¥ für das Paket des Verkäufers zu uns, die Pauschalsteuer von 14 %, dann der Versandweg, die Bearbeitungsgebühr von 50,00 CN¥ pro Paket und die Steuer darauf. In US$ ist es das, was einer US$-Karte belastet wird, Währungsumrechnung inklusive.

idstring: Beginnt mit imp_.
statusstring: running (eine Fundstücke-Tabelle wird noch gelesen), ready oder failed.
urlstring: Der Link, den du gesendet hast.
marketplacestring: taobao, tmall, weidian oder 1688.
title, seller, images[]string: So, wie der Verkäufer sie geschrieben hat, meistens auf Chinesisch.
read_atstring: Wann wir das Angebot zuletzt vom Marktplatz gelesen haben.
analysis.ship_to, lane, weight_g: Die Eingaben, für die es bepreist wurde.
analysis.coveredboolean: False, wenn kein veröffentlichter Tarif auf diesem Versandweg in dieses Land liefert; dann hat keine Variante Gesamtkosten.
analysis.marketplace_feeobject: percent und fixed: was der Marktplatz von einem Verkauf behält. default ist true, wenn du nichts gesendet hast und wir seinen öffentlichen Regelsatz genutzt haben, eine Schätzung, nie deine echte Abrechnung.
analysis.margin_reachableboolean: False, wenn Gebühr und Marge zusammen den ganzen Preis ausmachen: Kein Preis kann sie erreichen.
analysis.brand_hintobject|null: Marken- oder Replika-Wörter im Titel, auf Englisch oder Chinesisch. Ein Hinweis, nie ein Urteil: Ein Logo auf einem Foto sieht er nicht, und ein sauberes Ergebnis beweist nichts.
analysis.variants[].procurementobject: goods, intake_fee, tax und total der Bestellung, die ein Stück kauft.
analysis.variants[].seller_shippingobject|null: Der Versand des Verkäufers zu unserem Lager. Kein Angebot enthält ihn, er ist also null: unbekannt, nicht kostenlos.
analysis.variants[].parcelobject|null: lane, shipping, handling_fee, tax und total des Pakets, das es versendet.
analysis.variants[].landedobject: Artikel und Paket zusammen: in CN¥, in US$ und mit der Umrechnungsgebühr im US$-Betrag.
analysis.variants[].minimum_priceobject|null: Der niedrigste Preis, der deine Marge nach der Marktplatzgebühr hält.
analysis.variants[].suggestedobject|null: Der niedrigste x,99-Preis am oder über dem Minimum, mit der Gebühr, dem Gewinn und der Marge, die er übrig lässt.
productstring|null: Das Produkt, zu dem es nach dem Speichern wurde.

import

{
  "id": "imp_2c9d",
  "status": "ready",
  "url": "https://weidian.com/item.html?itemID=7750970856",
  "marketplace": "weidian",
  "title": "Heavyweight washed hoodie",
  "seller": "Ruoyi Studio",
  "images": [
    "https://media.ninjabuy.com/listings/weidian-7750970856/1.webp"
  ],
  "read_at": "2026-11-04T09:12:40Z",
  "analysis": {
    "ship_to": "US",
    "lane": "saver",
    "weight_g": 180,
    "covered": true,
    "marketplace": "ebay",
    "marketplace_fee": {
      "percent": "13.6",
      "fixed": { "amount": "0.40", "currency": "USD" },
      "default": true
    },
    "margin_percent": "30",
    "margin_reachable": true,
    "brand_hint": null,
    "variants": [
      {
        "sku": "5187209554",
        "label": "Black / M",
        "in_stock": true,
        "procurement": {
          "goods": { "amount": "38.00", "currency": "CNY" },
          "intake_fee": { "amount": "12.00", "currency": "CNY" },
          "tax": { "amount": "7.00", "currency": "CNY" },
          "total": { "amount": "57.00", "currency": "CNY" }
        },
        "seller_shipping": null,
        "parcel": {
          "lane": "saver",
          "shipping": { "amount": "68.00", "currency": "CNY" },
          "handling_fee": { "amount": "50.00", "currency": "CNY" },
          "tax": { "amount": "16.52", "currency": "CNY" },
          "total": { "amount": "134.52", "currency": "CNY" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      },
      {
        "sku": "5187209555",
        "label": "Black / L",
        "in_stock": false,
        "procurement": {
          "goods": { "amount": "38.00", "currency": "CNY" },
          "intake_fee": { "amount": "12.00", "currency": "CNY" },
          "tax": { "amount": "7.00", "currency": "CNY" },
          "total": { "amount": "57.00", "currency": "CNY" }
        },
        "seller_shipping": null,
        "parcel": {
          "lane": "saver",
          "shipping": { "amount": "68.00", "currency": "CNY" },
          "handling_fee": { "amount": "50.00", "currency": "CNY" },
          "tax": { "amount": "16.52", "currency": "CNY" },
          "total": { "amount": "134.52", "currency": "CNY" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      }
    ]
  },
  "product": null,
  "created_at": "2026-11-04T09:12:41Z"
}

Aus einem Link importieren

POST/v1/imports

Liest ein Taobao-, Tmall-, Weidian- oder 1688-Angebot (ein Kurzlink oder der Link eines anderen Einkaufsagenten darauf geht auch) und antwortet im selben Aufruf mit der Analyse. Ein Angebot, das wir in den letzten fünf Minuten gelesen haben, wird nicht erneut abgerufen.

Ein Link zu einer Fundstücke-Tabelle (https://www.ninjabuy.com/spreadsheets/d/…) importiert jedes Produkt darin: 202 mit status: running, dann den Import abfragen.

Scopeproducts:write

Body

urlstringerforderlich: Ein Produktlink oder eine Fundstücke-Tabelle.
ship_tostring: Zweistelliges Land, für das das Paket bepreist wird. Ohne Angabe US.
lanestring: saver oder fast. Ohne Angabe saver.
weight_gintegererforderlich: Das verpackte Gewicht eines Stücks, in Gramm. Angebote haben kein Gewicht, das Paket wird also nach deinem bepreist.
marketplacestring: Wo du es verkaufst: ebay, shopify, amazon oder tiktok. Ohne Angabe shopify.
marketplace_feeobject: Optional. percent und fixed (US$), statt des Regelsatzes des Marktplatzes, für deine Kategorie oder deinen Tarif.
margin_percentstring: Die Marge, auf die bepreist wird, bezogen auf den Verkaufspreis. Ohne Angabe 30.

Fehler

Status	Typ	Wann
400	bad-body	weight_g fehlt, oder ein Feld liegt außerhalb des Bereichs.
422	unprocessable	Kein Link, den wir lesen können, oder das Angebot ist weg.
429	rate-limited	Das Marktplatz-Kontingent ist verbraucht; siehe Rate-Limits.

curl -X POST "https://www.ninjabuy.com/api/v1/imports" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "ship_to": "US",
    "weight_g": 180,
    "marketplace": "ebay",
    "margin_percent": "30"
  }'

Response 201

HTTP/2 201 Created

{
  "id": "imp_2c9d",
  "status": "ready",
  "url": "https://weidian.com/item.html?itemID=7750970856",
  "marketplace": "weidian",
  "title": "Heavyweight washed hoodie",
  "seller": "Ruoyi Studio",
  "images": [
    "https://media.ninjabuy.com/listings/weidian-7750970856/1.webp"
  ],
  "read_at": "2026-11-04T09:12:40Z",
  "analysis": {
    "ship_to": "US",
    "lane": "saver",
    "weight_g": 180,
    "covered": true,
    "marketplace": "ebay",
    "marketplace_fee": {
      "percent": "13.6",
      "fixed": { "amount": "0.40", "currency": "USD" },
      "default": true
    },
    "margin_percent": "30",
    "margin_reachable": true,
    "brand_hint": null,
    "variants": [
      {
        "sku": "5187209554",
        "label": "Black / M",
        "in_stock": true,
        "procurement": {
          "goods": { "amount": "38.00", "currency": "CNY" },
          "intake_fee": { "amount": "12.00", "currency": "CNY" },
          "tax": { "amount": "7.00", "currency": "CNY" },
          "total": { "amount": "57.00", "currency": "CNY" }
        },
        "seller_shipping": null,
        "parcel": {
          "lane": "saver",
          "shipping": { "amount": "68.00", "currency": "CNY" },
          "handling_fee": { "amount": "50.00", "currency": "CNY" },
          "tax": { "amount": "16.52", "currency": "CNY" },
          "total": { "amount": "134.52", "currency": "CNY" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      },
      {
        "sku": "5187209555",
        "label": "Black / L",
        "in_stock": false,
        "procurement": {
          "goods": { "amount": "38.00", "currency": "CNY" },
          "intake_fee": { "amount": "12.00", "currency": "CNY" },
          "tax": { "amount": "7.00", "currency": "CNY" },
          "total": { "amount": "57.00", "currency": "CNY" }
        },
        "seller_shipping": null,
        "parcel": {
          "lane": "saver",
          "shipping": { "amount": "68.00", "currency": "CNY" },
          "handling_fee": { "amount": "50.00", "currency": "CNY" },
          "tax": { "amount": "16.52", "currency": "CNY" },
          "total": { "amount": "134.52", "currency": "CNY" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      }
    ]
  },
  "product": null,
  "created_at": "2026-11-04T09:12:41Z"
}

Neu bepreisen

POST/v1/imports/{id}/analysis

Dasselbe Angebot für ein anderes Land, einen anderen Versandweg, ein anderes Gewicht, einen anderen Marktplatz oder eine andere Marge. Bepreist aus dem, was wir schon gelesen haben, verbraucht also keinen Marktplatz-Aufruf. Antwortet mit der neuen Analyse und speichert sie am Import.

Scopeproducts:write

Pfadparameter

idstringerforderlich: Die ID des Imports.

Body

ship_tostring: Zweistelliges Land, für das das Paket bepreist wird. Ohne Angabe US.
lanestring: saver oder fast. Ohne Angabe saver.
weight_gintegererforderlich: Das verpackte Gewicht eines Stücks, in Gramm. Angebote haben kein Gewicht, das Paket wird also nach deinem bepreist.
marketplacestring: Wo du es verkaufst: ebay, shopify, amazon oder tiktok. Ohne Angabe shopify.
marketplace_feeobject: Optional. percent und fixed (US$), statt des Regelsatzes des Marktplatzes, für deine Kategorie oder deinen Tarif.
margin_percentstring: Die Marge, auf die bepreist wird, bezogen auf den Verkaufspreis. Ohne Angabe 30.

Fehler

Status	Typ	Wann
404	not-found	Kein solcher Import in diesem Konto.

curl -X POST "https://www.ninjabuy.com/api/v1/imports/imp_2c9d/analysis" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ship_to": "GB",
    "lane": "fast",
    "weight_g": 180,
    "marketplace": "tiktok",
    "margin_percent": "35"
  }'

Response 200

HTTP/2 200 OK

{
  "ship_to": "GB",
  "lane": "fast",
  "weight_g": 180,
  "covered": true,
  "marketplace": "tiktok",
  "marketplace_fee": {
    "percent": "6",
    "fixed": { "amount": "0.00", "currency": "USD" },
    "default": true
  },
  "margin_percent": "35",
  "margin_reachable": true,
  "brand_hint": null,
  "variants": [
    {
      "sku": "5187209554",
      "label": "Black / M",
      "in_stock": true,
      "procurement": {
        "goods": { "amount": "38.00", "currency": "CNY" },
        "intake_fee": { "amount": "12.00", "currency": "CNY" },
        "tax": { "amount": "7.00", "currency": "CNY" },
        "total": { "amount": "57.00", "currency": "CNY" }
      },
      "seller_shipping": null,
      "parcel": {
        "lane": "saver",
        "shipping": { "amount": "68.00", "currency": "CNY" },
        "handling_fee": { "amount": "50.00", "currency": "CNY" },
        "tax": { "amount": "16.52", "currency": "CNY" },
        "total": { "amount": "134.52", "currency": "CNY" }
      },
      "landed": {
        "cny": { "amount": "191.52", "currency": "CNY" },
        "usd": { "amount": "27.71", "currency": "USD" },
        "fx_fee": { "amount": "5.75", "currency": "CNY" }
      },
      "minimum_price": { "amount": "49.84", "currency": "USD" },
      "suggested": {
        "price": { "amount": "49.99", "currency": "USD" },
        "marketplace_fee": { "amount": "7.20", "currency": "USD" },
        "profit": { "amount": "15.08", "currency": "USD" },
        "margin_percent": "30.16"
      }
    },
    {
      "sku": "5187209555",
      "label": "Black / L",
      "in_stock": false,
      "procurement": {
        "goods": { "amount": "38.00", "currency": "CNY" },
        "intake_fee": { "amount": "12.00", "currency": "CNY" },
        "tax": { "amount": "7.00", "currency": "CNY" },
        "total": { "amount": "57.00", "currency": "CNY" }
      },
      "seller_shipping": null,
      "parcel": {
        "lane": "saver",
        "shipping": { "amount": "68.00", "currency": "CNY" },
        "handling_fee": { "amount": "50.00", "currency": "CNY" },
        "tax": { "amount": "16.52", "currency": "CNY" },
        "total": { "amount": "134.52", "currency": "CNY" }
      },
      "landed": {
        "cny": { "amount": "191.52", "currency": "CNY" },
        "usd": { "amount": "27.71", "currency": "USD" },
        "fx_fee": { "amount": "5.75", "currency": "CNY" }
      },
      "minimum_price": { "amount": "49.84", "currency": "USD" },
      "suggested": {
        "price": { "amount": "49.99", "currency": "USD" },
        "marketplace_fee": { "amount": "7.20", "currency": "USD" },
        "profit": { "amount": "15.08", "currency": "USD" },
        "margin_percent": "30.16"
      }
    }
  ]
}

Einen Import abrufen

GET/v1/imports/{id}

Lies einen Import erneut oder frag eine Fundstücke-Tabelle ab, während sie läuft.

Scopeproducts:read

Pfadparameter

idstringerforderlich: Die ID des Imports.

Fehler

Status	Typ	Wann
404	not-found	Kein solcher Import in diesem Konto.

curl "https://www.ninjabuy.com/api/v1/imports/imp_6t1b" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "id": "imp_6t1b",
  "status": "running",
  "url": "https://www.ninjabuy.com/spreadsheets/d/1aBcD3fGh",
  "progress": { "done": 41, "total": 120 },
  "poll_after_seconds": 10
}

Importe auflisten

GET/v1/imports

Neueste zuerst. Importe, die du nie gespeichert hast, bleiben hier, damit du darauf zurückkommen kannst.

Scopeproducts:read

Query-Parameter

statusstring: Optional. running, ready oder failed.
savedboolean: Optional. true für die, die zu Produkten wurden.
limit, cursor: Pagination

curl "https://www.ninjabuy.com/api/v1/imports?saved=false&limit=2" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "imp_2c9d",
      "status": "ready",
      "title": "Heavyweight washed hoodie",
      "product": null
    },
    {
      "id": "imp_2c7a",
      "status": "ready",
      "title": "Canvas tote, 3 colours",
      "product": null
    }
  ],
  "has_more": true,
  "cursor": "c_2c7a"
}

Als Produkt speichern

POST/v1/imports/{id}/save

Behält die gewählten Varianten als Produkt, zu den Preisen, die du setzt, oder den vorgeschlagenen. Füge push_to: shopify hinzu, um es im selben Aufruf in deinem Shop zu listen (An Shopify übertragen).

Scopeproducts:write

Pfadparameter

idstringerforderlich: Die ID des Imports.

Body

variants[]array: Optional. sku und price jeder Variante, die behalten wird. Ohne Angabe jede vorrätige Variante zum Preisvorschlag.
titlestring: Optional. Dein eigener Titel; der des Verkäufers ist meist auf Chinesisch.
push_tostring: Optional. shopify.

Fehler

Status	Typ	Wann
409	invalid-state	Schon gespeichert; product nennt es.
422	unprocessable	Jede Variante, die du behalten hast, ist ausverkauft.

curl -X POST "https://www.ninjabuy.com/api/v1/imports/imp_2c9d/save" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Heavyweight Washed Hoodie",
    "variants": [
      {
        "sku": "5187209554",
        "price": { "amount": "49.99", "currency": "USD" }
      }
    ],
    "push_to": "shopify"
  }'

Response 201

HTTP/2 201 Created

{
  "import": "imp_2c9d",
  "product": "prd_8f2k",
  "status": "draft",
  "channels": [{ "channel": "shopify", "status": "draft" }]
}