{"id":17997,"date":"2026-08-13T16:32:26","date_gmt":"2026-08-13T10:47:26","guid":{"rendered":"https:\/\/www.bay20.com\/de\/?p=17997"},"modified":"2026-08-19T14:13:35","modified_gmt":"2026-08-19T08:28:35","slug":"wie-verwaltet-man-301-weiterleitungen-mithilfe-der-bigcommerce-weiterleitungs-api","status":"publish","type":"post","link":"https:\/\/www.bay20.com\/de\/wie-verwaltet-man-301-weiterleitungen-mithilfe-der-bigcommerce-weiterleitungs-api\/","title":{"rendered":"How do you manage 301 redirects using the BigCommerce Redirect API?<\/font><\/font>"},"content":{"rendered":"\n

Jede Shop-Migration, URL-Umstrukturierung oder Umbenennung von Kategorien f\u00fchrt letztendlich dazu, dass irgendwo eine Menge toter Links entsteht. Alte Produktseiten, die fr\u00fcher bei Google rankten, verschobene Blogbeitr\u00e4ge, Kategoriepfade, die w\u00e4hrend der Migration vereinfacht wurden. Eine Handvoll davon manuell im Control Panel zu bearbeiten, ist kein Problem. Tausende davon nach einer vollst\u00e4ndigen Umstrukturierung der Website einzeln zu bearbeiten, ist jedoch eine Aufgabe, die niemand gerne \u00fcbernehmen m\u00f6chte. Genau hier spielt die Bigcommerce Redirects<\/strong><\/a> API ihre St\u00e4rken aus.<\/p>\n\n\n\n

Die gute Nachricht dabei \u2013 und das sollte man gleich zu Beginn erw\u00e4hnen, da es im Gegensatz zum Verhalten der Catalog-API steht \u2013 ist, dass BigCommerce<\/strong><\/a> tats\u00e4chlich einen echten Batch-Endpunkt f\u00fcr Weiterleitungen bereitstellt. Man ist nicht darauf angewiesen, diese wie bei Produkten einzeln per Anfrage zu erstellen. Es gibt jedoch noch ein paar Fallstricke, die man kennen sollte, bevor man ein Skript auf einen Live-Shop anwendet.<\/p>\n\n\n\n

Verzichten Sie auf die alte Redirects-API, wenn Sie ganz von vorne anfangen.<\/h2>\n\n\n\n

Wenn Sie nach Beispielen f\u00fcr BigCommerce-Weiterleitungen suchen, werden Sie auf viel \u00e4lteren Code sto\u00dfen, der POST \/v2\/redirects mit nur einem Pfad und einem \u201eforward\u201c-Feld verwendet. Dieser Endpunkt funktioniert technisch gesehen zwar noch, ist aber veraltet. Er erstellt pro Aufruf eine Weiterleitung und unterst\u00fctzt die Multi-Storefront-Konfiguration von BigCommerce \u00fcberhaupt nicht. BigCommerce dr\u00e4ngt schon seit einiger Zeit darauf, auf die Version v3 der Management-API umzusteigen, und genau diese Version lohnt es sich zu nutzen: PUT \/v3\/storefront\/redirects, auch als \u201eUpsert Redirects\u201c bezeichnet.<\/p>\n\n\n\n

Ja, es handelt sich um einen PUT-Aufruf, nicht um einen POST-Aufruf, auch wenn man damit oft v\u00f6llig neue Weiterleitungen erstellt. Das verwirrt viele beim ersten Lesen der Dokumentation. Der Grund daf\u00fcr ist das \u201eUpsert\u201c-Verhalten selbst, das sich als wirklich n\u00fctzlich erweist, sobald man verstanden hat, wie es funktioniert.<\/p>\n\n\n\n

Das \u201eUpsert\u201c-Verhalten ist der springende Punkt<\/h2>\n\n\n\n

So sieht die Anfrage aus:<\/p>\n\n\n\n

[\n  {\n    \"from_path\": \"\/old-product-page\/\",\n    \"site_id\": 1,\n    \"to\": {\n      \"type\": \"product\",\n      \"entity_id\": 482\n    }\n  }\n]<\/code><\/pre>\n\n\n\n
\u201efrom_path\u201c und \u201esite_id\u201c sind Pflichtangaben. \u201eto\u201c ist technisch gesehen optional, sollte aber fast immer angegeben werden. Andernfalls kann die Weiterleitung den Traffic nirgendwohin leiten. Das Feld \u201etype\u201c bei \u201eto\u201c kann auf ein Produkt, eine Kategorie, eine Seite, einen Blogbeitrag, eine Marke oder einfach eine reine externe oder interne URL verweisen, wenn Sie keine bestimmte Katalogentit\u00e4t ansprechen.<\/p>\n\n\n\n
Da es sich hierbei um einen \u201eUpsert\u201c und nicht um eine einfache Erstellung handelt, f\u00fchrt die zweimalige Ausf\u00fchrung derselben Payload nicht zu einem Duplikatfehler, wie es beispielsweise beim Anlegen eines Produkts mit einer bereits vorhandenen SKU der Fall w\u00e4re. Wenn f\u00fcr diese Kombination aus \u201efrom_path\u201c und \u201esite_id\u201c bereits eine Weiterleitung existiert, aktualisiert BigCommerce diese einfach. Falls keine vorhanden ist, wird eine neue erstellt. Dieses eine Detail macht die gesamte Angelegenheit wesentlich benutzerfreundlicher f\u00fcr die Erstellung eines Skripts. Sie k\u00f6nnen einen Import nach einem teilweisen Fehlschlag erneut ausf\u00fchren, ohne zuvor herausfinden zu m\u00fcssen, welche Weiterleitungen bereits \u00fcbernommen wurden.<\/p>\n\n\n\n
Warum Ihre Weiterleitung zwar vorhanden ist, aber dennoch nicht funktioniert<\/h2>\n\n\n\n
Dieses Thema verdient einen eigenen Abschnitt, da es zu einer \u00fcberm\u00e4\u00dfigen Anzahl von Support-Anfragen mit der Frage \u201eWarum funktioniert meine Weiterleitung nicht?\u201c f\u00fchrt. Wenn Ihr Shop mehrere Storefronts betreibt \u2013 also mehrere Kan\u00e4le, die auf denselben Backend-Katalog verweisen \u2013, hat jede davon ihre eigene site_id<\/code>, und eine f\u00fcr Site 1 erstellte Weiterleitung hat keine Auswirkung auf einen Kunden, der auf der Domain von Site 2 landet.<\/p>\n\n\n\n
Wenn Sie nur eine einzige Storefront haben, ist dies kein Problem: Ihre Site-ID entspricht einfach dem Standardwert, und jede Weiterleitung verwendet diese. Wenn Sie jedoch Weiterleitungen f\u00fcr eine Konfiguration mit mehreren Storefronts oder eine Headless-L\u00f6sung mit mehreren angeschlossenen Kan\u00e4len verwalten, m\u00fcssen Sie zun\u00e4chst die Liste der Sites abrufen (GET \/v3\/sites) und sicherstellen, dass Sie jede Weiterleitung mit der richtigen Site-ID versehen. Das \u00dcberspringen dieses Schritts ist wahrscheinlich der h\u00e4ufigste Grund daf\u00fcr, dass eine \u201ekorrekt erstellte\u201c Weiterleitung f\u00fcr echte Besucher tats\u00e4chlich keine Weiterleitung bewirkt.<\/p>\n\n\n\n
Wie gro\u00df darf ein Batch sein?<\/h2>\n\n\n\n
Im Gegensatz zur Katalog-API, bei der eine Obergrenze von 10 Eintr\u00e4gen pro Aufruf f\u00fcr Produkt-Batch-Aktualisierungen ausdr\u00fccklich dokumentiert ist, ver\u00f6ffentlicht BigCommerce keine konkrete Zahl daf\u00fcr, wie viele Redirect-Objekte Sie in einem einzigen \u201eUpsert Redirects\u201c-Aufruf senden k\u00f6nnen. In der Praxis bedeutet dies, dass Sie dies in einem Sandbox-Shop testen sollten, anstatt von einer bestimmten Zahl auszugehen. Das Senden von einigen hundert Objekten auf einmal hat im Allgemeinen gut funktioniert, aber es gibt keine ver\u00f6ffentlichte Garantie. Daher ist es die sicherere Vorgehensweise, Ihr Skript so zu gestalten, dass es das Array in Bl\u00f6cke aufteilt und eine abgelehnte Charge elegant verarbeitet \u2013 unabh\u00e4ngig davon, wo die tats\u00e4chliche Obergrenze liegt.<\/p>\n\n\n\n
Dar\u00fcber hinaus gelten weiterhin die \u00fcblichen Regeln zur Ratenbegrenzung. Es gilt dieselbe Quote von 150 Anfragen pro 30 Sekunden (Standard\/Plus) bzw. 450 pro 30 Sekunden (Pro) wie bei jedem anderen Management-API-Aufruf, und diese wird mit allen anderen Zugriffe geteilt, die gleichzeitig auf den Shop erfolgen. Die Aufteilung in angemessene Batch-Gr\u00f6\u00dfen erf\u00fcllt hier einen doppelten Zweck: Sie sorgt daf\u00fcr, dass Sie unterhalb der m\u00f6glicherweise bestehenden, undokumentierten Payload-Obergrenze bleiben, und h\u00e4lt die Anzahl Ihrer Anfragen im Rahmen der Ratenbegrenzung.<\/p>\n\n\n\n
So strukturieren Sie den Import<\/h2>\n\n\n\n
Hier ist nichts Aufwendiges erforderlich, lediglich ein Skript, das sich an die Struktur der API h\u00e4lt. Lesen Sie Ihr Quell-Mapping ein, normalisieren Sie jeden \u201efrom_path\u201c so, dass er mit einem \u201e\/\u201c beginnt und der abschlie\u00dfende Schr\u00e4gstrich den Vorgaben von BigCommerce entspricht, bauen Sie jede Zeile in die Struktur des Redirect-Objekts ein und f\u00fchren Sie anschlie\u00dfend eine Stapelverarbeitung und den Push durch:<\/p>\n\n\n\n
import axios from \"axios\";\n\nconst client = axios.create({\n  baseURL: `https:\/\/api.bigcommerce.com\/stores\/${process.env.STORE_HASH}\/v3`,\n  headers: {\n    \"X-Auth-Token\": process.env.BC_ACCESS_TOKEN,\n    \"Content-Type\": \"application\/json\",\n  },\n});\n\nconst SITE_ID = 1;\nconst BATCH_SIZE = 200;\n\nasync function runImport(rows) {\n  const failures = [];\n\n  for (let i = 0; i < rows.length; i += BATCH_SIZE) {\n    const batch = rows.slice(i, i + BATCH_SIZE).map(row => ({\n      from_path: row.old_path.startsWith(\"\/\") ? row.old_path : `\/${row.old_path}`,\n      site_id: SITE_ID,\n      to: { type: \"url\", url: row.new_path },\n    }));\n\n    try {\n      await client.put(\"\/storefront\/redirects\", batch);\n    } catch (err) {\n      failures.push(...batch);\n      console.error(err.response?.data || err.message);\n    }\n\n    await new Promise(r => setTimeout(r, 500));\n  }\n\n  return failures;\n}<\/code><\/pre>\n\n\n\n
\u201eUpsert Redirects\u201c ist ein Upsert und kein reines \u201eCreate\u201c, daher musst du nicht pr\u00fcfen, ob bereits eine Weiterleitung existiert. Bei einer erneuten Ausf\u00fchrung wird die vorhandene einfach \u00fcberschrieben. Das macht die Fehlerbehandlung so einfach. Wenn bei einem Batch ein Fehler auftritt, speicherst du ihn einfach ab und versuchst es sp\u00e4ter erneut.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Achten Sie auf f\u00fchrende und abschlie\u00dfende Schr\u00e4gstriche<\/h2>\n\n\n\n
\u201efrom_path\u201c muss mit einem \u201e\/\u201c beginnen, und BigCommerce ist sehr streng, was abschlie\u00dfende Schr\u00e4gstriche angeht, die nicht immer der URL-Struktur Ihrer alten Plattform entsprechen. Wenn Sie von Shopify oder WordPress migrieren, enthalten Ihre Quell-URLs m\u00f6glicherweise abschlie\u00dfende Schr\u00e4gstriche an Stellen, an denen BigCommerce diese nicht erwartet, oder umgekehrt. Es lohnt sich, jeden Pfad in Ihrem Skript zu normalisieren, anstatt sich auf den Inhalt Ihrer Exportdatei zu verlassen, da ein nicht \u00fcbereinstimmender abschlie\u00dfender Schr\u00e4gstrich dazu f\u00fchrt, dass die Weiterleitung f\u00fcr diese URL einfach stillschweigend nicht ausgel\u00f6st wird.<\/p>\n\n\n\n
Alte Weiterleitungen bereinigen<\/h2>\n\n\n\n
Die gleiche v3-Ressource unterst\u00fctzt auch das L\u00f6schen von Weiterleitungen im Massenverfahren: DELETE \/v3\/storefront\/redirects?id:in=101,102,103. Dies ist nach einer Migration sehr praktisch. Sobald Sie sich vergewissert haben, dass die neuen Weiterleitungen funktionieren, k\u00f6nnen Sie eine Reihe veralteter Weiterleitungen aus einem fr\u00fcheren Import l\u00f6schen, die nicht mehr korrekt sind. Es empfiehlt sich, zuvor einen GET-Aufruf an \/v3\/storefront\/redirects zu senden, um sicherzustellen, dass Sie tats\u00e4chlich die beabsichtigten IDs l\u00f6schen, da der Vorgang nach dem L\u00f6schen nicht r\u00fcckg\u00e4ngig gemacht werden kann.<\/p>\n\n\n\n
Wo setzt man das eigentlich ein?<\/h2>\n\n\n\n
Der naheliegendste Anwendungsfall ist eine Plattformmigration, bei der jede alte URL ihrem neuen \u00c4quivalent zugeordnet wird, damit der \u00fcber Jahre hinweg aufgebaute SEO-Wert nicht verloren geht. Aber auch au\u00dferhalb von Migrationen gibt es zahlreiche Anwendungsf\u00e4lle. Beispiele hierf\u00fcr sind: Umstrukturierungen von Kategorien, \u00c4nderungen an Produkt-URL-Slugs aus SEO-Gr\u00fcnden, die j\u00e4hrliche Umbenennung saisonaler Kollektionen oder die Bereinigung nach einer falschen URL-Entscheidung, die vor drei Jahren getroffen wurde und immer noch in Backlinks vorkommt, auf die man keinen Einfluss hat. Immer dann, wenn die Anzahl der zu \u00e4ndernden URLs das Ma\u00df \u00fcbersteigt, das man noch manuell im Control Panel bew\u00e4ltigen m\u00f6chte, ist dies das richtige Tool daf\u00fcr.<\/p>\n\n\n\n
Bitte kontaktieren Sie uns unter wargis@bay20.com\/manish@bay20.com<\/strong> oder rufen Sie uns unter +91-9582784309 oder +91-8800519180<\/strong> an, wenn Sie Unterst\u00fctzung im Zusammenhang mit BigCommerce<\/a><\/strong> ben\u00f6tigen. Sie k\u00f6nnen auch unsere Website besuchen, um sich \u00fcber unser Leistungsangebot zu informieren.<\/p>\n\n\n\n
<\/p>\n","protected":false},"excerpt":{"rendered":"
Jede Shop-Migration, URL-Umstrukturierung oder Umbenennung von Kategorien f\u00fchrt letztendlich dazu, dass irgendwo eine Menge toter Links entsteht. Alte Produktseiten, die fr\u00fcher bei Google rankten, verschobene Blogbeitr\u00e4ge, Kategoriepfade, die w\u00e4hrend der Migration vereinfacht wurden. Eine Handvoll davon manuell im Control Panel zu bearbeiten, ist kein Problem. Tausende davon nach einer vollst\u00e4ndigen Umstrukturierung der Website einzeln zu […]<\/p>\n","protected":false},"author":1,"featured_media":17998,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[13],"tags":[175],"class_list":["post-17997","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-bigcommerce","tag-bigcommerce"],"aioseo_notices":[],"_links":{"self":[{"href":"https:\/\/www.bay20.com\/de\/wp-json\/wp\/v2\/posts\/17997","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.bay20.com\/de\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.bay20.com\/de\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.bay20.com\/de\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.bay20.com\/de\/wp-json\/wp\/v2\/comments?post=17997"}],"version-history":[{"count":2,"href":"https:\/\/www.bay20.com\/de\/wp-json\/wp\/v2\/posts\/17997\/revisions"}],"predecessor-version":[{"id":18001,"href":"https:\/\/www.bay20.com\/de\/wp-json\/wp\/v2\/posts\/17997\/revisions\/18001"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.bay20.com\/de\/wp-json\/wp\/v2\/media\/17998"}],"wp:attachment":[{"href":"https:\/\/www.bay20.com\/de\/wp-json\/wp\/v2\/media?parent=17997"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.bay20.com\/de\/wp-json\/wp\/v2\/categories?post=17997"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.bay20.com\/de\/wp-json\/wp\/v2\/tags?post=17997"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}