The CubeCart REST API: What It Does and How to Use It Safely

CubeCart gained a REST API in 6.6.0, released as beta, and refactored it across four phases in 6.7.4. It is the change that most expands what you can build around a CubeCart store, and it is the one most likely to be relevant if you have ever wanted your shop to talk to something else without a human exporting a spreadsheet.

What it is for

If you run any of these, the API is the piece that was missing:

• Stock levels held in a separate warehouse or EPOS system that need to reach the website
• Orders that need to land in an accounts package without rekeying
• A supplier feed that should create or update products automatically
• A dashboard, app or internal tool that needs live store data
• A migration or bulk edit that is too awkward for the CSV import

Before 6.6.0 the honest answers were CSV files on a schedule, a custom plugin, or reading the database directly. All three work and all three are brittle. An API is a supported contract instead.

The resources

Nine resources ship, each implemented as its own class under classes/api/resources/:

• products and categories for your catalogue
• orders and customers for transactions and accounts
• coupons for promotions
• reviews for product reviews
• tax for tax configuration
• settings for store configuration
• files for uploads

That set covers most integration work. What is not there is anything shipping-module specific, and there is no webhook or event push, so anything reactive still has to poll.

How requests work

The entry point is api.php at your store root, and paths follow a conventional shape:

/api/v1/{resource}
/api/v1/{resource}/{id}
/api/v1/{resource}/{id}/{subResource}
/api/v1/{resource}/{id}/{subResource}/{subId}

The v1 segment is required. Omit it and you get a VERSION_REQUIRED error rather than a guess, which is the right call and means a future v2 will not silently break your integration.

Supported methods are GET, POST, PUT, PATCH and DELETE, plus OPTIONS for CORS preflight. GET on a collection lists, GET with an id fetches one, POST creates, PUT and PATCH update, DELETE removes. Nothing surprising, which is the point.

Authentication

Bearer token, but note the format, because it is a key and secret pair rather than a single opaque token:

Authorization: Bearer {api_key}:{api_secret}

Keys are created and revoked in the back office under Settings, on the API Keys screen. Each key carries its own per-resource permissions, stored as JSON, with read and write levels.

There is a design detail here worth knowing, because it is a good one. Every API key is tied to an administrator account, and that admin’s own permissions act as a ceiling on the key. A key cannot be granted more access than the administrator it belongs to. So if you create a limited admin account for your integration and issue the key against it, you get defence in depth: the key’s own scope and the underlying account’s permissions both have to allow the operation.

Use that. Do not issue integration keys against your own full-access superadmin account because it was quicker.

Rate limiting

Implemented in classes/api/ratelimiter.class.php as a sliding window counter backed by CubeCart’s cache layer. The default is 60 requests per minute per key, configurable per key.

Responses carry standard headers so a well behaved client can pace itself:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 43

Exceed it and you get HTTP 429 with a RATE_LIMITED error code and the number of seconds until the window resets. If you are writing a bulk sync, read the remaining count and back off rather than retrying blindly into a 429 loop.

One practical consequence: 60 requests a minute is fine for incremental sync and poor for bulk. Importing 10,000 products one call at a time is nearly three hours. Batch where the resource allows it, run bulk work off-peak, or raise the limit for that specific key.

Request logging

Every API call is logged, and it is registered as a shutdown function so it runs even on a code path that ends in exit(). That means failed and rejected calls get logged too, which is exactly when you want the record. Combined with the request log added in 6.7.0, you can see both what your store called out to and what called in.

Security: do not run this on 6.6.x

This needs saying plainly. The files resource had an authenticated arbitrary file upload to remote code execution vulnerability, GHSA-652f-8c88-25cx, fixed in 6.7.0. An authenticated caller could upload a file that the server would then execute.

The fix added filename validation, filepath traversal containment, and a defence in depth .htaccess in images/source/. But the practical guidance is simple: if you are going to enable the API, be on a current release. Do not turn on an API on 6.6.x because an article said the API arrived in 6.6.0.

Beta status and the 6.7.4 refactor

CubeCart shipped this labelled beta and that label was accurate. The 6.7.4 refactor reworked api.php across four phases for cleaner routing and request handling, without changing the resource scope. So the surface you integrate against is the same nine resources, but the code underneath is considerably more settled than it was at launch.

If you are building against it now, sensible precautions still apply: pin your integration to a tested CubeCart version, do not deploy a store upgrade and an integration change on the same day, and test on a staging copy first. The v1 prefix protects you from a breaking redesign, not from behaviour changes within v1.

Getting started

Create a dedicated admin account with only the permissions your integration needs. Issue an API key against it, scoped to the specific resources. Test against a staging copy of your store, not production. Watch the rate limit headers. Log what you send.

If you host your CubeCart store with us and want a hand setting up a staging copy to build against, or want the API key permissions reviewed before you point a live integration at your shop, get in touch.