Cara Menggunakan BigCommerce API: Panduan Developer untuk Integrasi E-commerce

Intisari

API BigCommerce memungkinkan Anda mengelola produk, pesanan, pelanggan, dan operasi toko secara terprogram. Anda melakukan autentikasi dengan token API (untuk sisi server) atau OAuth (untuk aplikasi), memanggil endpoint REST di api.bigcommerce.com, dan menangani webhook untuk pembaruan waktu nyata. Untuk pengujian, gunakan Apidog untuk menyimpan panggilan API Anda, memvalidasi respons, dan berbagi koleksi dengan tim Anda.

Pendahuluan

BigCommerce menggerakkan lebih dari 60.000 toko online. Setiap toko membutuhkan integrasi kustom - sinkronisasi inventaris, pemrosesan pesanan, manajemen pelanggan, penanganan pembayaran. Di sinilah peran API.

Platform ini menawarkan tiga jenis API: Storefront API (headless commerce), Management API (operasi backend), dan Payments API (transaksi). Sebagian besar pengembang bekerja dengan Management API. Ini menangani produk, pesanan, pelanggan, dan segala sesuatu yang terjadi di balik layar.

Kurva pembelajarannya tidak terlalu curam, tetapi dokumentasinya bisa terasa membingungkan. Anda akan sering berpindah antara dokumen autentikasi, referensi API, dan panduan webhook hanya untuk menyelesaikan tugas sederhana.

Panduan ini berfokus pada apa yang akan benar-benar Anda gunakan. Produk, pesanan, pelanggan, dan webhook. Anda akan mempelajari autentikasi, pola umum, dan cara menguji integrasi Anda sebelum menyentuh toko langsung.

💡

Jika Anda membangun integrasi BigCommerce, Apidog membantu Anda merancang, menguji, dan mendokumentasikan panggilan API tersebut. Simpan permintaan sebagai koleksi, gunakan variabel lingkungan untuk toko yang berbeda, dan validasi bahwa respons sesuai dengan skema yang diharapkan. Ini menangkap kesalahan sebelum memengaruhi pelanggan nyata.

tombol

Uji API BigCommerce Anda dengan Apidog - gratis

Pada akhir panduan ini, Anda akan dapat:

Mengatur autentikasi BigCommerce dengan benar
Mengelola produk, varian, dan inventaris
Memproses pesanan dan menangani data pelanggan
Mengatur webhook untuk pembaruan waktu nyata
Menguji dan mendokumentasikan integrasi Anda dengan Apidog

Autentikasi: mendapatkan akses ke toko Anda

BigCommerce menawarkan dua metode autentikasi tergantung pada apa yang Anda bangun.

Metode 1: Token API (untuk integrasi kustom)

Jika Anda membangun skrip atau layanan yang bekerja dengan satu toko, gunakan token API.

Buat akun API:

Buka panel admin toko Anda
Pengaturan → Akun API → Buat Akun API
Pilih “V3/V2 API Token”
Pilih cakupan yang Anda butuhkan (Produk, Pesanan, Pelanggan, dll.)
Simpan kredensial

Anda akan mendapatkan:

URL Toko: mystore.mybigcommerce.com
Token Akses: abc123def456...
ID Klien: abc123...
Kunci Rahasia Klien: xyz789...

Lakukan panggilan pertama Anda:

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"

store-hash adalah bagian setelah /stores/ di jalur API Anda. Ini juga terlihat di URL admin toko Anda.

Metode 2: OAuth (untuk aplikasi marketplace)

Jika Anda membangun aplikasi untuk marketplace BigCommerce, gunakan OAuth.

Alur OAuth:

Pengguna mengklik “Instal” pada aplikasi Anda di marketplace
BigCommerce mengarahkan ke URL callback Anda dengan kode autentikasi
Server Anda menukarkan kode tersebut dengan token akses
Simpan token untuk panggilan API di masa mendatang

Tukarkan kode untuk token:

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 adalah yang Anda gunakan untuk panggilan API
// context berisi store_hash

Gunakan 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"

Produk dan manajemen katalog

Produk adalah inti dari setiap toko BigCommerce. V3 Catalog API menangani produk, varian, kategori, dan merek.

Daftar produk

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

Respons:

{
  "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
    }
  }
}

Buat produk

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]
}

Perbarui varian produk

Produk dengan opsi (ukuran, warna) memiliki varian. Setiap varian dapat memiliki SKU, harga, dan inventarisnya sendiri.

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"
    }
  ]
}

Kelola inventaris

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

{
  "inventory_level": 75
}

Atau perbarui inventaris varian:

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

{
  "inventory_level": 25
}

Pesanan dan pemenuhan

Pesanan adalah tempat bisnis terjadi. Orders V2 API menangani pembuatan pesanan, pembaruan, dan pemenuhan.

Daftar pesanan

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

Respons:

[
  {
    "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"
    }
  }
]

Dapatkan detail pesanan

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

Dapatkan produk pesanan

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

Perbarui status pesanan

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

{
  "status_id": 12
}

ID status umum:

0: Tidak Lengkap
11: Menunggu Pemenuhan
12: Selesai
5: Dibatalkan
4: Dikembalikan Dananya

Buat pengiriman (pemenuhan)

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
    }
  ]
}

Pelanggan dan segmentasi

Customers V3 API menangani data pelanggan, alamat, dan grup pelanggan.

Daftar pelanggan

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

Respons:

{
  "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"
    }
  ]
}

Buat pelanggan

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
}

Perbarui pelanggan

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
}

Webhook untuk pembaruan waktu nyata

Webhook memberi tahu aplikasi Anda saat terjadi peristiwa di toko. Alih-alih melakukan polling, BigCommerce mendorong data ke endpoint Anda.

Buat webhook

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
}

Cakupan yang tersedia:

store/order/created - Pesanan baru dibuat
store/order/updated - Status pesanan diubah
store/order/archived - Pesanan diarsipkan
store/product/created - Produk ditambahkan
store/product/updated - Produk dimodifikasi
store/product/deleted - Produk dihapus
store/customer/created - Pelanggan baru
store/inventory/updated - Stok diubah

Verifikasi tanda tangan webhook

BigCommerce menandatangani webhook sehingga Anda dapat memverifikasi keabsahannya:

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')
  }
  
  // Proses webhook
  console.log('Order created:', req.body.data.id)
  res.status(200).send('OK')
})

Menguji API BigCommerce dengan Apidog

API BigCommerce memerlukan header yang konsisten dan autentikasi yang tepat. Pengujian manual dengan curl menjadi membosankan. Apidog menyederhanakan hal ini.

1. Penyiapan lingkungan

Buat lingkungan untuk setiap toko:

# 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

2. Skrip pra-permintaan

Tambahkan header autentikasi secara otomatis:

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

3. Validasi respons

Uji bahwa produk memiliki bidang yang wajib diisi:

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)
})

Uji API BigCommerce dengan Apidog - gratis

Kesalahan umum dan perbaikan

401 Tidak Sah

Penyebab: Token akses tidak valid atau hilang.

Perbaikan:

Periksa apakah header X-Auth-Token Anda telah diatur
Verifikasi bahwa token belum dicabut
Pastikan akun API memiliki cakupan yang benar

403 Terlarang

Penyebab: Token valid tetapi tidak memiliki cakupan yang diperlukan.

Perbaikan:

Periksa izin akun API Anda
Tambahkan cakupan yang hilang (Produk, Pesanan, dll.)
Hasilkan token baru dengan izin yang diperluas

404 Tidak Ditemukan

Penyebab: Endpoint salah atau sumber daya tidak ada.

Perbaikan:

Verifikasi hash toko sudah benar
Periksa versi API di URL (v2 vs v3)
Pastikan ID sumber daya ada

429 Terlalu Banyak Permintaan

Penyebab: Batas tingkat permintaan terlampaui.

Perbaikan: BigCommerce mengizinkan batas yang berbeda per endpoint. Produk: 10.000 permintaan/jam. Pesanan: 30.000 permintaan/jam. Periksa header X-Rate-Limit-Remaining dan terapkan 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
    }
  }
}

422 Entitas Tidak Dapat Diproses

Penyebab: Kesalahan validasi dalam isi permintaan.

Perbaikan: Periksa respons untuk detailnya. BigCommerce mengembalikan kesalahan validasi spesifik:

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

Alternatif dan perbandingan

Fitur	BigCommerce	Shopify	WooCommerce
Penerapan versi API	V2 dan V3	REST dan GraphQL	REST
Batas tingkat permintaan	10K-30K/jam	2/menit (leaky bucket)	Tergantung pada hosting
Webhook	Ya	Ya	Ya (plugin)
GraphQL	Tidak	Ya	Tidak
Kualitas SDK	Baik	Sangat Baik	Hanya PHP
Multi-toko	Ya	Tidak	Tidak

API V3 BigCommerce lebih konsisten daripada pendekatan Shopify yang terfragmentasi, tetapi API GraphQL Shopify menawarkan lebih banyak fleksibilitas untuk kueri yang kompleks.

Kasus penggunaan dunia nyata

Sinkronisasi inventaris multi-saluran. Sebuah merek menjual di BigCommerce, Amazon, dan toko fisik. Mereka menggunakan Products API untuk menyinkronkan tingkat inventaris di seluruh saluran, mencegah penjualan berlebihan. Apidog menguji endpoint sinkronisasi sebelum setiap deployment.

Automasi pesanan. Sebuah perusahaan kotak langganan menggunakan webhook untuk memicu pemenuhan saat pesanan dibuat. Orders API memperbarui nomor pelacakan. Gudang mereka menerima daftar pengambilan secara otomatis melalui handler webhook.

Segmentasi pelanggan. Sebuah situs e-commerce menggunakan Customers API untuk mengsegmentasi pembeli berdasarkan riwayat pembelian. Pelanggan VIP ditambahkan ke grup khusus dengan harga eksklusif. Integrasi ini berjalan mingguan via pekerjaan terjadwal.

Kesimpulan

Inilah yang telah Anda pelajari:

Autentikasi menggunakan token API (integrasi sederhana) atau OAuth (aplikasi marketplace)
V3 Catalog API menangani produk dan varian
V2 Orders API menangani pemrosesan dan pemenuhan pesanan
V3 Customers API menangani data pelanggan
Webhook mendorong pembaruan waktu nyata ke endpoint Anda
Uji dan dokumentasikan dengan Apidog untuk integrasi yang andal

Langkah selanjutnya:

Buat akun API di toko BigCommerce Anda
Lakukan panggilan API pertama Anda untuk daftar produk
Siapkan webhook untuk pembuatan pesanan
Simpan panggilan API Anda di Apidog
Bangun integrasi Anda

Uji API BigCommerce dengan Apidog - gratis

FAQ

Apa perbedaan antara API V2 dan V3?V3 adalah API yang lebih baru dan lebih konsisten. Gunakan untuk produk, kategori, merek, dan pelanggan. V2 menangani pesanan, yang belum dimigrasikan. Anda akan menggunakan keduanya dalam sebagian besar integrasi.

Bagaimana cara mendapatkan hash toko saya?Itu ada di URL admin BigCommerce Anda: https://store-abc123.mybigcommerce.com/manage. Bagian abc123 adalah hash toko Anda. Ini juga terlihat di pengaturan akun API.

Bisakah saya menggunakan API di toko uji coba?Ya. Toko uji coba BigCommerce memiliki akses API penuh. Ini sempurna untuk pengembangan dan pengujian sebelum diluncurkan.

Berapa batas tingkat permintaan untuk panggilan API?Tergantung pada endpoint. Produk: 10.000 permintaan/jam. Pesanan: 30.000 permintaan/jam. Periksa X-Rate-Limit-Remaining di header respons untuk melihat batas Anda saat ini.

Bagaimana cara menangani pagination?Gunakan parameter kueri page dan limit. Batas default adalah 50. Periksa meta.pagination di respons untuk jumlah halaman. Lakukan perulangan hingga Anda telah mengambil semua catatan.

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++
}

Bisakah saya mengunggah gambar produk melalui API?Ya. Gunakan endpoint gambar produk:

{
  "image_url": "https://example.com/image.jpg",
  "is_thumbnail": true
}

Bagaimana cara menangani mata uang dan multi-toko?Toko BigCommerce memiliki mata uang dasar. Multi-mata uang ditangani di tingkat etalase, bukan API. Untuk beberapa toko, buat akun API terpisah dan gunakan lingkungan yang berbeda di Apidog.

Apa yang terjadi jika endpoint webhook saya mati?BigCommerce mencoba ulang webhook yang gagal dengan exponential backoff. Setelah 5 kegagalan selama 24 jam, webhook dinonaktifkan. Pantau endpoint Anda dan berikan peringatan jika terjadi kegagalan.