← Back to EcomCentral
BIG CARTEL API v1 · JSON:API

Big Cartel Setup Guide

Connect your Big Cartel store to EcomCentral using the v1 JSON:API with OAuth2 Bearer token authentication.

Prerequisites

ℹ️ Big Cartel's API uses OAuth2 Bearer tokens and JSON:API (Content-Type: application/vnd.api+json). EcomCentral handles the content negotiation automatically.

Getting Your API Credentials

  1. Register a developer application at developers.bigcartel.com
  2. Set the redirect URI and request the store scope
  3. Complete the OAuth2 flow to obtain an access token
  4. Retrieve your numeric account ID by calling GET /v1/accounts/me or from the OAuth token response
  5. In EcomCentral, add a new Big Cartel connection and enter both fields
  6. Click ⚡ Test — should return your store name and creation date
⚠️ API access requires a Platinum plan or higher. Free and Gold plans cannot use the API.

Credentials Reference

KeyRequiredDescriptionExample
account_id Required Numeric Big Cartel account / store ID 1234567
access_token Required OAuth2 access token from the authorization flow abc123xyz…
✅ Alternative key names: accountId or id for the account; accessToken or token for the OAuth token.

API Endpoints Used

OperationMethodEndpoint
Test connectionGET/v1/accounts/{id}
List ordersGET/v1/accounts/{id}/orders?page[number]=P&page[size]=N
Order detail + itemsGET/v1/accounts/{id}/orders/{oid}?include=items,items.product
Add tracking (shipment)POST/v1/accounts/{id}/orders/{oid}/shipments
List productsGET/v1/accounts/{id}/products?page[number]=P&page[size]=N&include=options
Product detail + optionsGET/v1/accounts/{id}/products/{pid}?include=options
ℹ️ All endpoints return JSON:API format: rows are under the top-level data array; related resources (items, options) are in the included array; pagination count is at meta.total.

Supported Features

FeatureSupportedNotes
View orders (paginated)✅Payment status, shipping status, total, date
View order detail✅Billing + delivery address, line items with quantity and price
Add tracking / create shipment✅Carrier, tracking number, URL, customer notification flag
View products (paginated)✅Name, default price, status (active/sold_out)
View product detail + options✅Options (variants) with name, price diff, sold-out status, thumbnail
Update stock quantity❌Big Cartel has no inventory write endpoint — no numeric quantity exists in the API
Test connection✅Returns store name and creation date
⚠️ No stock quantities. Big Cartel only tracks a boolean sold_out flag per option, not a numeric quantity. Stock management must be done via the Big Cartel dashboard.

Troubleshooting

✕ 401 Unauthorized

The access token is expired or invalid. Big Cartel tokens may expire — re-run the OAuth2 flow to get a fresh token and update the connection credentials via Rotate Keys.

✕ 403 Forbidden on all endpoints

Your Big Cartel plan does not include API access. Upgrade to the Platinum plan or higher.

✕ Order detail returns empty items

Items are loaded via JSON:API include. If the order was created before the API was enabled, or if the OAuth scope does not cover order items, the included array may be empty.