DEV Community

Cover image for Cara Menggunakan BigCommerce API: Panduan Developer untuk Integrasi E-commerce
Walse
Walse

Posted on • Originally published at apidog.com

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

#api #backend #tutorial #webdev

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.

Coba Apidog hari ini

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 membingungkan. Anda akan sering berpindah antara dokumen autentikasi, referensi API, dan panduan webhook hanya untuk menyelesaikan tugas sederhana.

Panduan ini fokus pada praktik langsung: autentikasi, pola umum, serta cara menguji integrasi sebelum ke toko produksi—produk, pesanan, pelanggan, dan webhook.

💡 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.

Uji API BigCommerce Anda dengan Apidog - gratis

Setelah membaca, Anda akan bisa:

  • 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 tipe integrasi.

Metode 1: Token API (Integrasi Kustom)

Gunakan token API untuk skrip atau layanan yang hanya bekerja dengan satu toko.

Langkah membuat akun API:

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

Anda akan mendapatkan:

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

Contoh permintaan API pertama:

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

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

Metode 2: OAuth (Aplikasi Marketplace)

Untuk aplikasi marketplace, gunakan OAuth.

Alur OAuth:

  1. Pengguna klik “Instal” di marketplace.
  2. BigCommerce mengarahkan ke URL callback Anda dengan kode autentikasi.
  3. Server Anda menukarkan kode dengan token akses.
  4. Simpan token untuk panggilan API berikutnya.

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 untuk panggilan API
// context berisi store_hash
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

Produk dan Manajemen Katalog

Produk adalah inti toko BigCommerce. Gunakan V3 Catalog API untuk produk, varian, kategori, merek.

Daftar produk 

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

Contoh 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
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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]
}
Enter fullscreen mode Exit fullscreen mode

Perbarui varian produk

Produk dengan opsi seperti ukuran/warna menggunakan varian.

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

Kelola inventaris

Perbarui stok produk:

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

Atau stok varian:

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

Pesanan dan Pemenuhan

Orders V2 API untuk pembuatan, pembaruan, dan pemenuhan pesanan.

Daftar pesanan 

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

Contoh 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"
    }
  }
]
Enter fullscreen mode Exit fullscreen mode

Dapatkan detail pesanan 

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

Dapatkan produk pesanan 

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

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
}
Enter fullscreen mode Exit fullscreen mode

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
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Pelanggan dan Segmentasi

Customers V3 API untuk 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
Enter fullscreen mode Exit fullscreen mode

Contoh 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"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

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
}
Enter fullscreen mode Exit fullscreen mode

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
}
Enter fullscreen mode Exit fullscreen mode

Webhook untuk Pembaruan Waktu Nyata

Webhook memberi tahu aplikasi Anda secara real-time saat peristiwa terjadi di toko.

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
}
Enter fullscreen mode Exit fullscreen mode

Cakupan tersedia:

  • store/order/created - Pesanan baru
  • store/order/updated - Status pesanan berubah
  • 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 setiap webhook.

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')
})
Enter fullscreen mode Exit fullscreen mode

Menguji API BigCommerce dengan Apidog

API BigCommerce membutuhkan header konsisten dan autentikasi. Pengujian manual dengan curl membosankan. Apidog menyederhanakan ini.

BigCommerce Apidog

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
Enter fullscreen mode Exit fullscreen mode

2. Skrip pra-permintaan

Tambahkan header autentikasi otomatis:

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. Validasi respons

Uji bahwa produk memiliki field wajib:

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

Uji API BigCommerce dengan Apidog - gratis

Kesalahan Umum dan Perbaikan

401 Tidak Sah

Penyebab: Token akses tidak valid/hilang.

Perbaikan:

  1. Pastikan header X-Auth-Token sudah diatur.
  2. Verifikasi token masih aktif.
  3. Pastikan akun API memiliki cakupan yang diperlukan.

403 Terlarang

Penyebab: Token valid tapi cakupan kurang.

Perbaikan:

  1. Cek izin akun API.
  2. Tambahkan cakupan yang kurang.
  3. Hasilkan token baru dengan izin lengkap.

404 Tidak Ditemukan

Penyebab: Endpoint salah/sumber daya tidak ada.

Perbaikan:

  1. Periksa hash toko.
  2. Cek versi API di URL (v2/v3).
  3. Pastikan ID sumber daya benar.

429 Terlalu Banyak Permintaan

Penyebab: Melebihi rate limit.

Perbaikan: Cek header X-Rate-Limit-Remaining dan lakukan backoff otomatis. Contoh:

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 Entitas Tidak Dapat Diproses

Penyebab: Validasi gagal.

Perbaikan: Cek respons error detail dari BigCommerce.

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

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 dibanding pendekatan API Shopify yang terfragmentasi, namun API GraphQL Shopify unggul untuk query kompleks.

Kasus Penggunaan Dunia Nyata

Sinkronisasi inventaris multi-saluran

Merek yang menjual di BigCommerce, Amazon, dan toko fisik menggunakan Products API untuk sinkronisasi stok, mencegah overselling. Endpoint diuji otomatis dengan Apidog sebelum deployment.

Automasi pesanan

Perusahaan langganan menggunakan webhook untuk memicu pemenuhan saat pesanan masuk. Orders API memperbarui nomor resi, gudang menerima daftar pengambilan otomatis via handler webhook.

Segmentasi pelanggan

E-commerce menggunakan Customers API untuk mengelompokkan pembeli berdasarkan histori. Pelanggan VIP masuk grup khusus dengan harga eksklusif. Proses dijalankan mingguan via job terjadwal.

Kesimpulan

Yang sudah Anda pelajari:

  • Autentikasi via token API (integrasi sederhana) atau OAuth (aplikasi marketplace)
  • V3 Catalog API untuk produk dan varian
  • V2 Orders API untuk pemrosesan pesanan
  • V3 Customers API untuk data pelanggan
  • Webhook untuk pembaruan real-time
  • Uji dan dokumentasikan dengan Apidog untuk integrasi yang andal

Langkah selanjutnya:

  1. Buat akun API di toko BigCommerce Anda
  2. Lakukan panggilan API pertama untuk daftar produk
  3. Siapkan webhook untuk pembuatan pesanan
  4. Simpan panggilan API Anda di Apidog
  5. Bangun integrasi Anda

Uji API BigCommerce dengan Apidog - gratis

FAQ

Apa perbedaan antara API V2 dan V3?

V3 adalah versi baru dan konsisten. Gunakan untuk produk, kategori, merek, pelanggan. V2 untuk pesanan. Mayoritas integrasi memakai keduanya.

Bagaimana cara mendapatkan hash toko saya?

Cek di URL admin: https://store-abc123.mybigcommerce.com/manage. Bagian abc123 adalah store hash. Juga ada di pengaturan akun API.

Bisakah saya menggunakan API di toko uji coba?

Ya. Toko uji coba BigCommerce punya akses API penuh, cocok untuk dev/testing.

Berapa batas rate limit API?

Tergantung endpoint: Produk 10.000/jam, Pesanan 30.000/jam. Lihat header X-Rate-Limit-Remaining di respons.

Bagaimana menangani pagination?

Gunakan query page dan limit. Default limit 50. Cek meta.pagination di respons. Ulangi sampai semua data diambil.

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

Bisakah upload gambar produk via API?

Ya, gunakan endpoint gambar produk:

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

Bagaimana menangani mata uang dan multi-toko?

Tiap toko BigCommerce punya mata uang dasar. Multi-mata uang diatur di storefront, bukan API. Untuk multi-toko, buat akun API dan environment terpisah di Apidog.

Apa yang terjadi jika endpoint webhook mati?

BigCommerce mencoba ulang webhook gagal dengan exponential backoff. Setelah 5 kegagalan/24 jam, webhook dinonaktifkan. Pantau endpoint Anda dan setup alert jika gagal.

Top comments (0)