DEV Community

Cover image for BigCommerce API Nutzung: Entwicklerhandbuch für E-Commerce Integration
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

BigCommerce API Nutzung: Entwicklerhandbuch für E-Commerce Integration

Das Wichtigste auf einen Blick

Mit den BigCommerce APIs können Sie Produkte, Bestellungen, Kunden und Shop-Vorgänge programmatisch steuern. Für die Authentifizierung verwenden Sie API-Tokens (serverseitig) oder OAuth (Apps). Sie greifen auf REST-Endpunkte unter api.bigcommerce.com zu und verwalten Webhooks für Echtzeit-Updates. Nutzen Sie zum Testen Apidog, um API-Aufrufe zu speichern, Antworten zu validieren und Sammlungen mit dem Team zu teilen.

Teste Apidog jetzt

Einleitung

BigCommerce betreibt über 60.000 Online-Shops. Jede Instanz benötigt individuelle Integrationen wie Bestandsabgleich, Auftragsabwicklung, Kundenverwaltung oder Zahlungsabwicklung – hier kommen die APIs zum Einsatz.

Es gibt drei API-Typen: Storefront API (Headless Commerce), Management API (Backend-Operationen) und Payments API (Transaktionen). Die meisten Entwickler arbeiten mit der Management API, um Produkte, Bestellungen, Kunden und shopinterne Abläufe zu automatisieren.

Die Lernkurve ist moderat, aber die Dokumentation kann unübersichtlich sein. Sie müssen teils zwischen Authentifizierungsdokumenten, API-Referenzen und Webhook-Guides springen, um Aufgaben umzusetzen.

Dieser Leitfaden konzentriert sich auf praxisrelevante Anwendungsfälle: Produkte, Bestellungen, Kunden und Webhooks. Sie lernen Authentifizierung, typische Muster und wie Sie Ihre Integrationen testen, bevor sie live gehen.

💡 Tipp: Für die Entwicklung von BigCommerce-Integrationen hilft Apidog, um API-Calls zu entwerfen, testen und zu dokumentieren. Speichern Sie Anfragen als Sammlungen, nutzen Sie Umgebungsvariablen für verschiedene Shops und validieren Sie Rückgaben gegen erwartete Schemata. So erkennen Sie Fehler, bevor sie Kunden betreffen.

Testen Sie Ihre BigCommerce APIs mit Apidog – kostenlos.

Am Ende dieses Leitfadens sind Sie in der Lage:

  • BigCommerce-Authentifizierung korrekt einzurichten
  • Produkte, Varianten und Inventar zu verwalten
  • Bestellungen zu bearbeiten und Kundendaten zu steuern
  • Webhooks für Echtzeit-Updates einzurichten
  • Ihre Integrationen mit Apidog zu testen und zu dokumentieren

Authentifizierung: Zugriff auf Ihren Shop erhalten

BigCommerce bietet zwei Authentifizierungsmethoden – je nach Integrationsart:

Methode 1: API-Tokens (benutzerdefinierte Integrationen)

Bauen Sie ein Skript oder einen Dienst, der mit einem Shop arbeitet, nutzen Sie API-Tokens.

API-Konto erstellen:

  1. Admin-Panel Ihres Shops öffnen
  2. Einstellungen → API-Konten → API-Konto erstellen
  3. „V3/V2 API Token“ wählen
  4. Benötigte Scopes auswählen (Produkte, Bestellungen, Kunden etc.)
  5. Anmeldeinformationen speichern

Sie erhalten:

  • Shop-URL: mystore.mybigcommerce.com
  • Zugriffstoken: abc123def456...
  • Client-ID: abc123...
  • Client-Geheimnis: xyz789...

Erster API-Aufruf:

curl -X GET "https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products" \
  -H "X-Auth-Token: {access-token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
Enter fullscreen mode Exit fullscreen mode

Der store-hash steht nach /stores/ im API-Pfad und ist in Ihrer Admin-URL sichtbar.

Methode 2: OAuth (Marketplace-Apps)

Für App-Entwicklung im BigCommerce Marketplace nutzen Sie OAuth.

OAuth-Fluss:

  1. Benutzer klickt auf „Installieren“ im Marketplace
  2. BigCommerce leitet zu Ihrer Callback-URL mit Auth-Code weiter
  3. Server tauscht Code gegen Zugriffstoken
  4. Token für künftige API-Aufrufe speichern

Beispiel: Code gegen Token eintauschen

const response = await fetch('https://login.bigcommerce.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    client_id: process.env.BC_CLIENT_ID,
    client_secret: process.env.BC_CLIENT_SECRET,
    redirect_uri: 'https://yourapp.com/auth/callback',
    grant_type: 'authorization_code',
    code: authCode,
    scope: 'store_v2_default store_v3_products'
  })
})
const { access_token, context } = await response.json()
// access_token für API-Aufrufe verwenden
// context enthält store_hash
Enter fullscreen mode Exit fullscreen mode

API-Call mit Token:

curl -X GET "https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products" \
  -H "X-Auth-Token: {access-token}" \
  -H "Content-Type: application/json"
Enter fullscreen mode Exit fullscreen mode

Produkte und Katalogverwaltung

Produkte bilden das Kernstück jedes BigCommerce-Shops. Mit der V3 Catalog API verwalten Sie Produkte, Varianten, Kategorien und Marken.

Produkte auflisten 

GET https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products
X-Auth-Token: {token}
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

Antwort:

{
  "data": [
    {
      "id": 174,
      "name": "Plain T-Shirt",
      "type": "physical",
      "sku": "PLAIN-T",
      "price": 29.99,
      "sale_price": 24.99,
      "inventory_level": 150,
      "inventory_tracking": "product",
      "is_visible": true,
      "categories": [23, 45],
      "brand_id": 12
    }
  ],
  "meta": {
    "pagination": {
      "total": 500,
      "count": 50,
      "page": 1,
      "per_page": 50
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Ein Produkt erstellen 

POST https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products
X-Auth-Token: {token}
Content-Type: application/json

{
  "name": "Premium Hoodie",
  "type": "physical",
  "sku": "HOODIE-PREM",
  "price": 79.99,
  "description": "Premium cotton blend hoodie",
  "weight": 1.5,
  "width": 20,
  "height": 28,
  "depth": 2,
  "inventory_level": 100,
  "inventory_tracking": "product",
  "is_visible": true,
  "categories": [23]
}
Enter fullscreen mode Exit fullscreen mode

Produktvarianten aktualisieren

Produkte mit Optionen (z.B. Größe, Farbe) haben Varianten. Jede Variante kann eigene Attribute besitzen.

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/variants/{variant-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "sku": "HOODIE-PREM-BLK-M",
  "price": 79.99,
  "inventory_level": 50,
  "option_values": [
    {
      "option_display_name": "Color",
      "label": "Black"
    },
    {
      "option_display_name": "Size",
      "label": "Medium"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Inventar verwalten

Produktinventar aktualisieren:

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "inventory_level": 75
}
Enter fullscreen mode Exit fullscreen mode

Oder für eine Variante:

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/variants/{variant-id}
Content-Type: application/json

{
  "inventory_level": 25
}
Enter fullscreen mode Exit fullscreen mode

Bestellungen und Abwicklung

Bestellungen werden mit der Orders V2 API verwaltet – Erstellung, Aktualisierung, Fulfillment.

Bestellungen auflisten 

GET https://api.bigcommerce.com/stores/{store-hash}/v2/orders
X-Auth-Token: {token}
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

Antwort:

[
  {
    "id": 115,
    "status": "Awaiting Fulfillment",
    "status_id": 11,
    "customer_id": 45,
    "date_created": "2026-03-24T10:30:00+00:00",
    "subtotal_ex_tax": 149.99,
    "total_inc_tax": 162.49,
    "items_total": 2,
    "items_shipped": 0,
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "street_1": "123 Main St",
      "city": "Austin",
      "state": "Texas",
      "zip": "78701",
      "country": "United States"
    }
  }
]
Enter fullscreen mode Exit fullscreen mode

Bestelldetails abrufen 

GET https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}
X-Auth-Token: {token}
Enter fullscreen mode Exit fullscreen mode

Bestellprodukte abrufen 

GET https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}/products
X-Auth-Token: {token}
Enter fullscreen mode Exit fullscreen mode

Bestellstatus aktualisieren 

PUT https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "status_id": 12
}
Enter fullscreen mode Exit fullscreen mode

Gängige Status-IDs:

  • 0: Unvollständig
  • 11: Wartet auf Erfüllung
  • 12: Abgeschlossen
  • 5: Storniert
  • 4: Erstattet

Eine Sendung erstellen (Abwicklung) 

POST https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}/shipments
X-Auth-Token: {token}
Content-Type: application/json

{
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "shipping_method": "UPS Ground",
  "items": [
    {
      "order_product_id": 234,
      "quantity": 1
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Kunden und Segmentierung

Die Customers V3 API steuert Kundendaten, Adressen und Gruppen.

Kunden auflisten 

GET https://api.bigcommerce.com/stores/{store-hash}/v3/customers
X-Auth-Token: {token}
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

Antwort:

{
  "data": [
    {
      "id": 45,
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "company": "Acme Corp",
      "phone": "512-555-1234",
      "customer_group_id": 1,
      "notes": "VIP customer",
      "tax_exempt_category": "",
      "date_created": "2025-11-15T09:30:00+00:00",
      "date_modified": "2026-03-20T14:22:00+00:00"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Einen Kunden erstellen 

POST https://api.bigcommerce.com/stores/{store-hash}/v3/customers
X-Auth-Token: {token}
Content-Type: application/json

{
  "email": "jane.smith@example.com",
  "first_name": "Jane",
  "last_name": "Smith",
  "phone": "512-555-5678",
  "customer_group_id": 2
}
Enter fullscreen mode Exit fullscreen mode

Kunden aktualisieren 

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/customers/{customer-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "notes": "Repeat customer - priority support",
  "customer_group_id": 3
}
Enter fullscreen mode Exit fullscreen mode

Webhooks für Echtzeit-Updates

Webhooks informieren Ihre App, wenn Ereignisse im Shop stattfinden. Kein Polling nötig – BigCommerce sendet Daten an Ihre Endpunkte.

Einen Webhook erstellen 

POST https://api.bigcommerce.com/stores/{store-hash}/v3/hooks
X-Auth-Token: {token}
Content-Type: application/json

{
  "scope": "store/order/created",
  "destination": "https://yourapp.com/webhooks/orders",
  "is_active": true
}
Enter fullscreen mode Exit fullscreen mode

Verfügbare Scopes:

  • store/order/created – Neue Bestellung
  • store/order/updated – Bestellstatus geändert
  • store/order/archived – Bestellung archiviert
  • store/product/created – Produkt hinzugefügt
  • store/product/updated – Produkt geändert
  • store/product/deleted – Produkt entfernt
  • store/customer/created – Neuer Kunde
  • store/inventory/updated – Lagerbestand geändert

Webhook-Signaturen überprüfen

BigCommerce signiert Webhook-Requests zur Verifizierung:

import crypto from 'crypto'

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  )
}

app.post('/webhooks/orders', (req, res) => {
  const signature = req.headers['x-bc-webhook-signature']
  const payload = JSON.stringify(req.body)

  if (!verifyWebhook(payload, signature, process.env.BC_CLIENT_SECRET)) {
    return res.status(401).send('Invalid signature')
  }

  // Webhook weiterverarbeiten
  console.log('Order created:', req.body.data.id)
  res.status(200).send('OK')
})
Enter fullscreen mode Exit fullscreen mode

Testen von BigCommerce APIs mit Apidog

BigCommerce APIs verlangen konsistente Header und Authentifizierung. Manuelles Testen mit curl ist fehleranfällig – Apidog vereinfacht den Prozess.

Apidog Beispiel

1. Umgebung einrichten

Definieren Sie Umgebungsvariablen für verschiedene Shops:

# Production Store
STORE_HASH: abc123
ACCESS_TOKEN: xyz789
BASE_URL: https://api.bigcommerce.com/stores/abc123

# Staging Store
STORE_HASH: staging456
ACCESS_TOKEN: staging_token
BASE_URL: https://api.bigcommerce.com/stores/staging456
Enter fullscreen mode Exit fullscreen mode

2. Pre-Request-Skripte

Automatisieren Sie das Hinzufügen von Auth-Headern:

pm.request.headers.add({
  key: 'X-Auth-Token',
  value: pm.environment.get('ACCESS_TOKEN')
})
pm.request.headers.add({
  key: 'Accept',
  value: 'application/json'
})
Enter fullscreen mode Exit fullscreen mode

3. Antworten validieren

Stellen Sie sicher, dass die API das erwartete Schema liefert:

pm.test('Products have required fields', () => {
  const response = pm.response.json()
  response.data.forEach(product => {
    pm.expect(product).to.have.property('id')
    pm.expect(product).to.have.property('name')
    pm.expect(product).to.have.property('price')
    pm.expect(product.price).to.be.above(0)
  })
})

pm.test('Pagination works', () => {
  const response = pm.response.json()
  pm.expect(response.meta.pagination).to.have.property('total')
  pm.expect(response.meta.pagination.page).to.eql(1)
})
Enter fullscreen mode Exit fullscreen mode

Testen Sie BigCommerce APIs mit Apidog – kostenlos.

Häufige Fehler und Behebungen

401 Nicht autorisiert

Ursache: Ungültiges oder fehlendes Zugriffstoken.

Behebung:

  1. Prüfen Sie, ob der X-Auth-Token-Header gesetzt ist
  2. Prüfen Sie, ob das Token gültig ist
  3. Achten Sie auf korrekte Scopes im API-Konto

403 Verboten

Ursache: Token hat nicht die erforderlichen Scopes.

Behebung:

  1. API-Konto-Berechtigungen prüfen
  2. Fehlende Scopes ergänzen
  3. Neues Token mit erweiterten Rechten generieren

404 Nicht gefunden

Ursache: Falscher Endpunkt oder Ressource existiert nicht.

Behebung:

  1. Store-Hash prüfen
  2. API-Version in der URL prüfen (v2/v3)
  3. Gültige Ressourcen-ID verwenden

429 Zu viele Anfragen

Ursache: Ratenlimit überschritten.

Behebung: BigCommerce limitiert Anfragen je Endpunkt (Produkte: 10.000/h, Bestellungen: 30.000/h). Prüfen Sie den X-Rate-Limit-Remaining-Header und implementieren Sie Backoff:

async function callWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fn()
    if (response.status === 429) {
      const retryAfter = response.headers.get('X-Rate-Limit-Reset')
      await new Promise(r => setTimeout(r, retryAfter * 1000))
    } else {
      return response
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

422 Unverarbeitbare Entität

Ursache: Validierungsfehler im Request.

Behebung: Details der API-Antwort prüfen:

{
  "errors": {
    "price": "Price must be greater than zero",
    "sku": "SKU already exists"
  }
}
Enter fullscreen mode Exit fullscreen mode

Alternativen und Vergleiche

Merkmal BigCommerce Shopify WooCommerce
API-Versionierung V2 und V3 REST und GraphQL REST
Ratenlimits 10K-30K/Stunde 2/min (Leaky Bucket) Abhängig vom Hosting
Webhooks Ja Ja Ja (Plugin)
GraphQL Nein Ja Nein
SDK-Qualität Gut Exzellent Nur PHP
Multi-Store Ja Nein Nein

Die V3 API von BigCommerce ist konsistenter als der fragmentierte Ansatz von Shopify, allerdings bietet die GraphQL API von Shopify mehr Flexibilität für komplexe Abfragen.

Praktische Anwendungsfälle

Omnichannel-Inventarsynchronisierung: Synchronisieren Sie Lagerbestände über BigCommerce, Amazon und stationäre Geschäfte per Products API. Apidog testet die Endpunkte vor jeder Deployment.

Bestellautomatisierung: Automatisieren Sie Fulfillment mit Webhooks, sobald Bestellungen eingehen. Aktualisieren Sie Sendungsverfolgungsnummern via Orders API. Lagerlisten werden automatisch über Webhook-Handler verteilt.

Kundensegmentierung: Segmentieren Sie Käufer nach Kaufhistorie per Customers API. Weisen Sie VIP-Kunden Gruppen mit Sonderpreisen zu. Die Integration läuft z.B. wöchentlich als geplanter Job.

Fazit

Das haben Sie gelernt:

  • Authentifizierung über API-Tokens (Integrationen) oder OAuth (Apps)
  • V3 Catalog API für Produkte und Varianten
  • V2 Orders API für Auftragsbearbeitung
  • V3 Customers API für Kundendaten
  • Webhooks für Echtzeit-Updates
  • Integrationstests und Dokumentation mit Apidog

Ihre nächsten Schritte:

  1. API-Konto im BigCommerce-Shop erstellen
  2. Ersten API-Call zum Produkte auflisten durchführen
  3. Webhook für Auftragserstellung einrichten
  4. API-Calls in Apidog speichern
  5. Integration bauen

Testen Sie BigCommerce APIs mit Apidog – kostenlos.

FAQ

Was ist der Unterschied zwischen V2 und V3 APIs?

V3 ist die modernere, konsistentere API – nutzen Sie sie für Produkte, Kategorien, Marken und Kunden. V2 bleibt für Bestellungen relevant. In den meisten Integrationen brauchen Sie beide.

Wie finde ich meinen Store-Hash?

Er steht in Ihrer Admin-URL: https://store-abc123.mybigcommerce.com/manage – der Teil abc123 ist Ihr Store-Hash. Auch in den API-Kontoeinstellungen sichtbar.

Kann ich die API in einem Test-Shop verwenden?

Ja. Test-Shops haben vollen API-Zugriff – ideal für Entwicklung und Tests vor dem Go-Live.

Wie hoch ist das Ratenlimit für API-Aufrufe?

Je Endpunkt unterschiedlich: Produkte 10.000/h, Bestellungen 30.000/h. Prüfen Sie X-Rate-Limit-Remaining im Response-Header.

Wie handhabe ich Paginierung?

Nutzen Sie die Query-Parameter page und limit (Standard: 50). Prüfen Sie meta.pagination in der Antwort für Gesamtseitenzahl. Schleifen Sie, bis alle Daten geladen sind.

let allProducts = []
let page = 1

while (true) {
  const response = await fetch(
    `${baseUrl}/v3/catalog/products?page=${page}&limit=100`,
    { headers: { 'X-Auth-Token': token } }
  )
  const data = await response.json()
  allProducts.push(...data.data)

  if (page >= data.meta.pagination.total_pages) break
  page++
}
Enter fullscreen mode Exit fullscreen mode

Kann ich Produktbilder per API hochladen?

Ja – nutzen Sie diesen Endpunkt:

POST https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/images
Content-Type: application/json

{
  "image_url": "https://example.com/image.jpg",
  "is_thumbnail": true
}
Enter fullscreen mode Exit fullscreen mode

Wie handhabe ich Währung und Multi-Store?

Jeder Shop hat eine Basiswährung. Multi-Währung wird auf Storefront-Ebene gemanaged, nicht via API. Für mehrere Shops nutzen Sie getrennte API-Konten und Umgebungen in Apidog.

Was passiert, wenn mein Webhook-Endpunkt nicht erreichbar ist?

BigCommerce versucht bei Fehlern mehrfach mit exponentiellem Backoff. Nach 5 Fehlern in 24h wird der Webhook deaktiviert. Überwachen Sie Ihre Endpunkte und richten Sie Fehlermeldungen ein.

Top comments (0)