How to Use the BigCommerce API for Weekly and Monthly Reports (With AI)

Ask a BigCommerce merchant group how they get the reports they actually want and someone will answer: "I connected AI to the API. I can ask it anything." Ask them how, and the reply is usually "ask AI, that's what I did." That's true, but it's not a guide.

This is the guide. It covers how to connect to the BigCommerce API safely, how to get Claude or ChatGPT to write the reporting script for you, how to run it every week and month, and which numbers will quietly go wrong if you don't check them. Every heading is a question merchants actually ask, so you can jump to the one you have.

You don't need to be a developer. You do need about an afternoon, a computer you can run a script on, and a willingness to check the first report against BigCommerce's own numbers.

Table of Contents

• Can I connect AI to my BigCommerce store to get reports?
  • Does BigCommerce have an MCP server for reports?
• How do I get a BigCommerce API key?
  • Which permissions should I give the API account?
• Which BigCommerce API endpoints do I need for sales reports?
  • Which order statuses count as a sale?
  • What are the BigCommerce API rate limits?
• How do I get ChatGPT or Claude to write the report script?
  • What does a working weekly report script look like?
• How do I run BigCommerce reports automatically every week or month?
• Which products do my repeat customers buy most?
• What should I ask AI once the data is pulled?
• Why don't my API numbers match BigCommerce Analytics?
• Is it safe to give AI my BigCommerce API token?
• What's the easier way if I don't want to maintain a script?
• Which route should I choose?

Can I connect AI to my BigCommerce store to get reports?

Yes, but "connecting AI" means different things depending on who you ask. In practice merchants use one of four routes:

Route	How it works	Good for	Watch out for
API + AI-written script	AI writes a small program that pulls orders through the API and builds the report	Repeatable weekly and monthly reports, any custom metric	You own the script, the token and every fix
CSV export + AI chat	Export orders from BigCommerce and upload the file to ChatGPT or Claude	One-off questions	Large files get truncated, numbers can be invented, nothing repeats automatically
MCP connection	An AI assistant calls store tools directly	Quick lookups and store admin tasks	BigCommerce's own store MCP is a closed beta with no reporting tools (see below)
Reporting app	An app syncs your orders and answers questions or builds charts	Ongoing reporting without code	Monthly cost; check it covers the metric you need

The first route is what most merchants mean when they say "I connected AI to the API." The AI doesn't sit inside your store. It writes code that talks to the store, and that code produces the report. Most of this guide covers that route, because it's the one nobody explains properly.

Does BigCommerce have an MCP server for reports?

Not for reporting, as of November 2026. MCP (Model Context Protocol) is the standard that lets AI assistants such as Claude and ChatGPT call tools in other apps. BigCommerce has two MCP servers, and neither is built for sales reports:

• Storefront MCP is for shoppers. It covers catalog search, product details, carts and checkout links, so you can build a shopping assistant. It doesn't expose your sales data.
• Store Management MCP is for merchants, but BigCommerce's Store Management MCP docs describe it as an invite-only closed beta. Its order tools list order summaries and handle refunds. There are no analytics or reporting tools, and order lookups leave out shopper names, emails and addresses, which you need for repeat-customer analysis.

You'll also find community-built BigCommerce MCP servers on GitHub and MCP directories. They work by holding your API token, so treat them like any third-party app: read the code or trust the author before giving one access.

For weekly and monthly reports, the API is still the dependable route.

How do I get a BigCommerce API key?

BigCommerce calls it a store-level API account. You need to be the store owner or have permission to manage API accounts.

1. In your BigCommerce control panel, go to Settings → Store-level API accounts (some stores show it under Settings → API).
2. Click Create API account and choose V2/V3 API token as the token type.
3. Give it a clear name, such as Weekly reports – read only.
4. Set the permissions (next section), then click Save.
5. BigCommerce shows your credentials and downloads a .txt file with them. This is the only time you'll see them. If you lose the file, you'll have to delete the account and create a new one.

From that file you need two values:

• Access token: the long string that authenticates your requests. It's sent in the X-Auth-Token header.
• API path: a URL like https://api.bigcommerce.com/stores/abc123xyz/v3/. The part after /stores/ is your store hash.

BigCommerce's API accounts documentation notes that store-level tokens don't expire, and that you can't change an account's permissions after you create it. To change permissions, or to revoke access, delete the account and create a new one.

Which permissions should I give the API account?

Give it the least it needs. For sales and customer reports, that's three permissions, all read-only:

Permission	Set to	Why
Orders	read-only	Order totals, statuses, dates, line items, refunds
Products	read-only	Product names, categories, variants, SKUs
Customers	read-only	Customer records and groups
Everything else	None	Not needed for reporting

Read-only matters more than usual here. You're about to run code you didn't write line by line. If the token can only read, the worst a buggy script can do is produce a wrong report. With modify access, it could edit orders or products.

Practical rule: A reporting token should never be able to change anything in your store.

Which BigCommerce API endpoints do I need for sales reports?

Fewer than you'd think. Most weekly and monthly reports come from these:

What you want	Endpoint	Useful fields
Orders in a date range	GET /v2/orders?min_date_created=…&max_date_created=…	id, date_created, status_id, subtotal_ex_tax, total_inc_tax, discount_amount, refunded_amount, shipping_cost_ex_tax, customer_id, billing_address.email
Line items in an order	GET /v2/orders/{order_id}/products	product_id, variant_id, sku, name, quantity, total_ex_tax, quantity_refunded
Order status names	GET /v2/order_statuses	id, name
Product details and categories	GET /v3/catalog/products	id, name, sku, categories
Customer records	GET /v3/customers	id, email, customer_group_id, date_created

All of them sit under https://api.bigcommerce.com/stores/{store_hash}. A few details from the List Orders reference that save hours of confusion:

• Dates can be filtered in ISO-8601 (2026-11-01T00:00:00-05:00) or RFC-2822 format. Dates in the response are always in UTC, so a late-evening order can land on the next day in your report unless you convert it to your store's time zone.
• Pagination uses page and limit. The default is 50 orders per page, so a script has to keep requesting pages until there are none left.
• Guest checkouts have customer_id set to 0. To count repeat buyers, you'll need the billing email for guests.
• Money fields are strings, like "49.9900". Convert them to numbers before adding them up.
• Line items need one request per order. The orders list doesn't include products, which is why reports with product or SKU detail take longer to run.

Which order statuses count as a sale?

This is the most common reason an API report disagrees with BigCommerce. Every order has a status_id, and your script needs to decide which ones count. BigCommerce's order status list is:

ID	Status	Count it as a sale?
0	Incomplete	No: the shopper never finished checkout
1	Pending	Usually no: payment isn't confirmed yet
2	Shipped	Yes
3	Partially Shipped	Yes
4	Refunded	Count it, then subtract the refund (or exclude it entirely, but be consistent)
5	Cancelled	No
6	Declined	No
7	Awaiting Payment	Usually no
8	Awaiting Pickup	Yes
9	Awaiting Shipment	Yes
10	Completed	Yes
11	Awaiting Fulfillment	Yes
12	Manual Verification Required	Your call: decide once and document it
13	Disputed	Your call: decide once and document it
14	Partially Refunded	Yes, minus the refunded amount

A sensible starting set is 2, 3, 4, 8, 9, 10, 11 and 14, with refunds subtracted. Whatever you choose, write it at the top of the script and tell the AI exactly which statuses to include. "Sales" without a status rule is how two people get two different totals.

What are the BigCommerce API rate limits?

According to BigCommerce's rate limit documentation:

Plan	Limit
Core and Growth	20,000 requests per hour (150 per 30 seconds)
Scale	60,000 requests per hour (450 per 30 seconds)
Higher plans	Vary by plan and resource

Every app installed on your store shares the same quota, so your script competes with your other apps. When you hit the limit, the API returns HTTP 429 Too Many Requests. Each response includes an X-Rate-Limit-Requests-Left header and an X-Rate-Limit-Time-Reset-Ms header, and a well-behaved script checks them and waits when the quota runs low.

Hypothetical example: A store with 1,200 orders a month needs about 24 requests to list the orders and about 1,200 more for their line items. At 150 requests per 30 seconds, that takes roughly 4 minutes without hitting the limit. That's fine for a monthly report, but it's why you shouldn't run it every few minutes.

How do I get ChatGPT or Claude to write the report script?

Be specific. "Write me a BigCommerce report" produces a demo. A prompt that names the endpoints, the status rule, the time zone and the output produces something you can trust. Copy this and fill in the brackets:

Write a Python script that builds a weekly sales report from the BigCommerce REST API.

Setup:
- Read BIGCOMMERCE_STORE_HASH and BIGCOMMERCE_ACCESS_TOKEN from environment variables. Never hard-code them.
- Send the token in the X-Auth-Token header, with Accept: application/json.
- Use only GET requests. The token is read-only.

Data:
- List orders with GET /stores/{store_hash}/v2/orders, filtered with min_date_created and
  max_date_created for the previous Monday 00:00 to Sunday 23:59 in [America/New_York].
- Page through results with page and limit=250 until a page comes back empty or with HTTP 204.
- Only include orders with status_id in [2, 3, 4, 8, 9, 10, 11, 14].
- For each order, get line items from GET /v2/orders/{order_id}/products.
- Money fields are strings. Convert them to Decimal.
- Respect rate limits: if X-Rate-Limit-Requests-Left is below 10, sleep for
  X-Rate-Limit-Time-Reset-Ms. On HTTP 429, wait and retry.

Report:
- Orders, gross sales (sum of subtotal_ex_tax), discounts (discount_amount),
  refunds (refunded_amount), net sales (gross - discounts - refunds), average order value.
- Top 10 products by net line revenue (total_ex_tax), with units sold.
- Same figures for the week before, with the % change.
- Save the line-level data to orders_YYYY-MM-DD.csv and print a short summary.

Explain how to install and run it on [Mac / Windows].

A few things make this prompt work:

• It names the exact endpoints and fields, so the AI doesn't invent ones that don't exist.
• It states the status rule and time zone, which are the two places numbers go wrong.
• It asks for a CSV of the raw rows, so you can check the totals yourself.
• It keeps the token out of the code, so you can share the script or commit it without leaking access.

If something fails, paste the full error message back into the same chat. That's most of what "vibe coding" is: run it, paste the error, run it again.

What does a working weekly report script look like?

Here's a trimmed-down version of what that prompt should give you. It's a reference, so you can tell whether the AI's version is on the right track:

import os, time, csv
from datetime import datetime, timedelta
from decimal import Decimal
from collections import defaultdict
from zoneinfo import ZoneInfo
import requests

STORE = os.environ["BIGCOMMERCE_STORE_HASH"]
TOKEN = os.environ["BIGCOMMERCE_ACCESS_TOKEN"]
BASE = f"https://api.bigcommerce.com/stores/{STORE}"
HEADERS = {"X-Auth-Token": TOKEN, "Accept": "application/json"}
TZ = ZoneInfo("America/New_York")
SALE_STATUSES = {2, 3, 4, 8, 9, 10, 11, 14}

def get(path, params=None):
    while True:
        r = requests.get(BASE + path, headers=HEADERS, params=params, timeout=30)
        if r.status_code == 429:
            time.sleep(int(r.headers.get("X-Rate-Limit-Time-Reset-Ms", 5000)) / 1000)
            continue
        r.raise_for_status()
        if int(r.headers.get("X-Rate-Limit-Requests-Left", 100)) < 10:
            time.sleep(int(r.headers.get("X-Rate-Limit-Time-Reset-Ms", 5000)) / 1000)
        return [] if r.status_code == 204 else r.json()

def orders_between(start, end):
    page = 1
    while True:
        batch = get("/v2/orders", {
            "min_date_created": start.isoformat(),
            "max_date_created": end.isoformat(),
            "limit": 250, "page": page,
        })
        if not batch:
            return
        yield from (o for o in batch if o["status_id"] in SALE_STATUSES)
        page += 1

def week_report(start, end):
    totals = defaultdict(Decimal)
    products = defaultdict(lambda: {"units": 0, "revenue": Decimal(0)})
    rows = []
    for o in orders_between(start, end):
        totals["orders"] += 1
        totals["gross"] += Decimal(o["subtotal_ex_tax"])
        totals["discounts"] += Decimal(o["discount_amount"])
        totals["refunds"] += Decimal(o["refunded_amount"])
        for item in get(f"/v2/orders/{o['id']}/products", {"limit": 250}):
            key = item["sku"] or item["name"]
            products[key]["units"] += item["quantity"]
            products[key]["revenue"] += Decimal(item["total_ex_tax"])
            rows.append([o["id"], o["date_created"], key, item["quantity"], item["total_ex_tax"]])
    totals["net"] = totals["gross"] - totals["discounts"] - totals["refunds"]
    return totals, products, rows

today = datetime.now(TZ).replace(hour=0, minute=0, second=0, microsecond=0)
start = today - timedelta(days=today.weekday() + 7)   # last Monday
end = start + timedelta(days=7) - timedelta(seconds=1)

totals, products, rows = week_report(start, end)
with open(f"orders_{start:%Y-%m-%d}.csv", "w", newline="") as f:
    csv.writer(f).writerows([["order_id", "date_created", "sku", "units", "line_total_ex_tax"], *rows])

print(f"Week of {start:%b %d}: {totals['orders']} orders, net sales {totals['net']:.2f}")
for sku, p in sorted(products.items(), key=lambda kv: kv[1]["revenue"], reverse=True)[:10]:
    print(f"  {sku}: {p['units']} units, {p['revenue']:.2f}")

To run it, install Python 3.9 or later, run pip install requests, set the two environment variables, then run python weekly_report.py. The AI can walk you through each step for your computer.

The first time you run it, compare the order count and gross sales with Analytics → Orders in BigCommerce for the same week. If they're close, keep going. If they're far apart, the cause is almost always the status rule or the time zone (see why the numbers don't match).

How do I run BigCommerce reports automatically every week or month?

Once the script works, you have three common ways to schedule it:

Option	Best for	Setup effort
Your own computer (cron on Mac/Linux, Task Scheduler on Windows)	Trying it out	Low, but only runs when the computer is on
GitHub Actions	Most merchants	Medium: free for light use, runs in the cloud, keeps the token in encrypted secrets
A small cloud server	Merchants who already run one	Medium to high: you maintain the server

For GitHub Actions, ask the AI:

Create a GitHub Actions workflow that runs weekly_report.py every Monday at 7:00 in
[America/New_York], using BIGCOMMERCE_STORE_HASH and BIGCOMMERCE_ACCESS_TOKEN from
repository secrets, and emails the summary and CSV to [me@store.com] using [Gmail SMTP
with an app password / SendGrid]. Use a private repository.

For a monthly report, have the AI add a second schedule on the first day of each month that runs the same logic for the previous calendar month and compares it with the same month last year. Comparing a month with the one before it mostly shows seasonality. Comparing it with the same month last year shows whether the business actually grew.

Tip: Have the email include the order count and the status rule ("statuses 2, 3, 4, 8–11, 14; America/New_York"). When a number looks odd three months from now, you'll know how it was calculated.

Which products do my repeat customers buy most?

This is the report merchants most often mention as painful, because BigCommerce's built-in reports don't answer it directly. With the API it's a short addition to the same script.

The logic:

1. Pull all orders for the past 12 months (or longer), using the same status rule.
2. Identify each customer by customer_id, or by the lowercase billing_address.email for guests, where customer_id is 0.
3. A repeat customer is anyone with two or more orders in that window.
4. Pull the line items for the repeat customers' orders and add up units and revenue by product.
5. Compare with the same ranking for one-time customers.

The prompt:

Extend the script: pull qualifying orders from the last 12 months. Identify customers by
customer_id, or by lowercased billing_address.email when customer_id is 0. Mark customers
with 2+ orders as repeat. Output two rankings, the top 20 products by revenue for repeat
customers and the top 20 for one-time customers, with units, revenue, number of distinct
buyers, and each product's share of the group's revenue. Also report, for repeat customers,
which product appears most often in their FIRST order.

That last line matters most. The product that appears in repeat customers' first orders is often your best acquisition product: the one that turns new buyers into regulars. It's frequently a different product from your overall bestseller.

Hypothetical example: A tea store's top seller overall is a gift box. Among repeat customers, the top first-order product is a 50g sampler that only ranks ninth overall. That points to promoting the sampler to new visitors, rather than the gift box.

For more on grouping customers by behaviour, see our guide to BigCommerce customer segmentation.

What should I ask AI once the data is pulled?

Once your script saves clean CSVs, you can upload them to ChatGPT or Claude and ask questions. This works far better than uploading a raw BigCommerce export, because the data is already filtered and labelled. Questions worth asking:

Weekly check-in

• How did net sales, orders and average order value compare with last week and with the same week last year?
• Which five products gained or lost the most revenue this week?
• Did any product sell zero units this week after selling steadily for the past month?

Monthly review

• What share of this month's revenue came from returning customers versus first-time customers?
• Which categories grew and which shrank compared with the same month last year?
• Which products have the highest refund rate (refunded quantity ÷ units sold) over the past 90 days?
• How much revenue came from orders that used a discount, and what was their average order value?

Customers

• Which customers ordered at least three times last year but haven't ordered in the last 90 days?
• What's the median number of days between a customer's first and second order?
• Which states or countries have the highest share of repeat customers?

The "audit my business" question

• "Here's 12 months of order data. Give me the five things a store owner should worry about and the five things that are going well. Show the numbers behind each one."

Two rules keep these answers honest:

1. Ask for the calculation, not just the answer. "Show the formula and the rows you used" makes it much harder for the AI to make up a number.
2. Spot-check one figure against the CSV or BigCommerce before acting on it. Language models are good at analysis and sometimes bad at arithmetic, especially with large files.

Why don't my API numbers match BigCommerce Analytics?

The first API report rarely matches BigCommerce's own dashboard to the cent. The usual causes, in order of how often they happen:

Symptom	Likely cause	Fix
Order count too high	Incomplete, cancelled or declined orders included	Filter by status_id
Orders on the wrong day	API dates are UTC	Convert to your store's time zone before grouping by day
Sales too high	Tax or shipping included	Use subtotal_ex_tax for merchandise sales; report tax and shipping separately
Sales too high after refunds	Refunds not subtracted	Subtract refunded_amount once, at order level
Product totals don't add up to order totals	Order-level discounts, shipping, or rounding	Compare merchandise totals, not grand totals
Missing orders	Pagination stopped early	Keep requesting pages until one comes back empty
Repeat customers undercounted	Guests all share customer_id 0	Use billing email for guests
Totals change after the fact	Late refunds or status changes on old orders	Re-run past periods, or note the date the report was pulled

Also note that line items have a refund_amount field that BigCommerce marks as deprecated: refunds made through the current refunds feature don't update it. Use the order-level refunded_amount for refund totals, and quantity_refunded on line items for refunded units.

Our guide to BigCommerce sales by SKU goes deeper on the step from gross to net sales.

Is it safe to give AI my BigCommerce API token?

Pasting the token into a chat is the riskiest step in this whole process, and you can skip it entirely.

• Never paste the real token into ChatGPT or Claude. The AI doesn't need it to write the script. Use placeholder environment variable names, as in the prompt above.
• Keep the token in environment variables or encrypted secrets, never in the script file, a shared Google Doc or a public GitHub repository.
• Use read-only permissions, so a leaked token can read your data but can't change your store.
• Give each tool its own API account. If one leaks, you delete that account without breaking the others.
• Remember the token doesn't expire. If someone who had access leaves, or you're not sure where a token has been, delete the account and create a new one.
• Customer data is personal data. Your CSVs contain names and emails. Store them somewhere private, and check your privacy policy before uploading customer-level files to an AI service.

What's the easier way if I don't want to maintain a script?

The API route works, and plenty of merchants are happy with it. The trade-off is that you become the maintainer: when an endpoint changes, a token gets revoked, GitHub changes something, or the report quietly double-counts a refund, it's your job to notice and fix it. It also only answers the questions you thought to code.

If you'd rather skip that, a reporting app does the same job without the script. Chartsy is one option built for BigCommerce:

• Install it from the BigCommerce marketplace and it syncs your last 12 months of orders right away, with older history loading in the background. It reads your data through the API and never touches your storefront or checkout.
• Ask ChartsyAI a question such as "Which products do my repeat customers buy most?" or "Compare net sales by category with the same month last year" and get the chart that answers it. Follow-up questions build on the last answer.
• Customer segments (Loyalists, Promising, At-Risk and Lost) are calculated from purchase history and updated every month, so the repeat-customer and win-back questions above are already answered.
• Gross sales, discounts, refunds, shipping and tax are reported separately, so the gross-to-net problems in the table above are handled for you.
• Scheduled email reports cover the weekly and monthly reports, and charts export to PDF or PNG.

What Chartsy doesn't do: it doesn't track ad spend or marketing attribution. If you need ROAS, you'll still need your ad platforms or a dedicated attribution tool.

Which route should I choose?

If you…	Choose
Enjoy tinkering, want full control, and have an afternoon	API + AI-written script
Have one question this month and won't need it again	CSV export + AI chat
Want AI to manage products and orders, and have a beta invite	BigCommerce Store Management MCP
Want the same reports every week without maintaining anything	A reporting app such as Chartsy

Whichever route you take, the rules that make the numbers trustworthy are the same: decide which order statuses count, report in your store's time zone, keep tax and shipping separate, subtract refunds once, and check the first report against BigCommerce before you rely on it.

For more ideas on which questions to answer first, see BigCommerce custom reports and the BigCommerce KPIs worth tracking.

Frequently Asked Questions

Do I need to be a developer to use the BigCommerce API for reports?

No. You need to create a read-only API account, run a script on your computer or in GitHub Actions, and check the first report against BigCommerce. ChatGPT or Claude can write the script if you give them the endpoints, the order statuses to count and your time zone.

Where do I find my BigCommerce API key?

Go to Settings → Store-level API accounts in your control panel and click Create API account. BigCommerce shows the access token and API path once and downloads them as a .txt file. Your store hash is the part of the API path after /stores/.

Can ChatGPT or Claude connect directly to my BigCommerce store?

Not for reporting, as of November 2026. BigCommerce's Store Management MCP is an invite-only closed beta with no analytics or reporting tools, and its Storefront MCP is built for shoppers. For reports, have the AI write a script that calls the API.

Which BigCommerce API endpoint gives me sales data?

GET /v2/orders lists orders with totals, discounts, refunds and status, filtered by date with min_date_created and max_date_created. GET /v2/orders/{order_id}/products gives the line items for product and SKU reports.

How often can I run a BigCommerce API report?

Core and Growth plans allow 20,000 requests per hour (150 per 30 seconds), shared with every app on your store. A weekly or monthly report fits easily. Running a full report every few minutes doesn't.

Can I get BigCommerce reports emailed to me every week without code?

Yes, with a reporting app. Chartsy, for example, syncs your BigCommerce orders and sends scheduled email reports, so you don't have to maintain a script.

---

Want weekly and monthly BigCommerce reports without writing or maintaining a script? Try Chartsy free for 14 days. No credit card required. Install it from the BigCommerce marketplace and ask your first question about your store in minutes.