← Back to EcomCentral
CUBECART REST API v1

CubeCart Setup Guide

Connect your CubeCart 6.5+ store to EcomCentral using Bearer token authentication with your API key pair generated in the admin panel.

Prerequisites

ℹ️ The CubeCart REST API is built into the core of CubeCart 6.5+. Older CubeCart 6.x versions (prior to 6.5) did not include an official REST API. If you are running an older version, upgrade to 6.5+ before proceeding.
ℹ️ CubeCart uses Bearer token authentication: your API key and API secret are combined as Authorization: Bearer {api_key}:{api_secret}. API requests use the path format api.php?_api_path=v1/... — no URL rewriting required.

Generating Your API Key Pair

  1. Log in to your CubeCart administration panel
  2. Navigate to Developer in the left-hand menu
  3. Click API Keys
  4. Click Generate new key pair — a public key and secret are created immediately
  5. Copy both the API Key (public) and the API Secret — the secret is shown only once
  6. Set the required permissions for the key: enable read on orders, products, and settings; enable write on orders and products
  7. In EcomCentral, add a new CubeCart connection with your store URL, API key, and API secret
  8. Click ⚡ Test — a successful test confirms the credentials are valid
⚠️ The API secret is shown only once when you generate the key pair. Store it securely before closing the page. If lost, delete the key and generate a new pair, then update the connection in EcomCentral.

Credentials Reference

KeyRequiredDescriptionExample
base_url Required The root URL of your CubeCart store (without /api.php — EcomCentral appends the API path automatically) https://store.example.com
api_key Required Public API key generated in Developer → API Keys in the admin panel ccapi_abc123…
api_secret Required Paired secret key — shown once at generation time; must be stored securely s3cr3t…
✅ Alternative key names accepted: baseUrl or url for the store URL; apiKey or key for the API key; apiSecret or secret for the API secret.

API Endpoints Used

OperationMethodEndpoint
Test connectionGETapi.php?_api_path=v1/settings&per_page=1
List ordersGETapi.php?_api_path=v1/orders&page=P&per_page=N
Order detailGETapi.php?_api_path=v1/orders/{id}
Add / update trackingPUTapi.php?_api_path=v1/orders/{id} with { "ship_tracking": "…", "ship_method": "…" }
List productsGETapi.php?_api_path=v1/products&page=P&per_page=N
Product detailGETapi.php?_api_path=v1/products/{id}
Update stockPUTapi.php?_api_path=v1/products/{id} with { "stock_level": N }
ℹ️ CubeCart routes API requests via api.php?_api_path=v1/.... This form is used internally by CubeCart's ApiRouter and does not require the store's .htaccess pretty-URL rewrite to be active — it works on any standard PHP hosting.

Order Status Labels

Status LabelMeaning
Pending Order placed but not yet processed or paid
Processing Payment received; order is being prepared for shipment
Complete Order has been fully fulfilled and delivered
Shipped Order has been dispatched and is in transit
Awaiting Stock One or more items are out of stock; order is on hold
On Hold Order is paused pending manual review or action
Cancelled Order has been cancelled
Declined Payment or order was declined
Refunded Payment has been refunded to the customer
ℹ️ CubeCart returns order statuses as text labels (e.g. "Processing") rather than single-letter codes. EcomCentral uses these labels directly to colour-code badges. Custom status labels configured in your store will display as-is with a neutral grey badge.

Supported Features

FeatureSupportedNotes
View orders (paginated)✅Order ID, date (UNIX timestamp), status label, total
View order detail✅Customer info, shipping & billing addresses, line items, current tracking
Add / update tracking✅Tracking number + carrier stored on the order via PUT — no separate shipment object needed
View products (paginated)✅Product ID, SKU (product_code), name, price, stock level, status
View product detail✅Full product record: description, weight, categories, current stock
Update stock quantity✅By product_id via PUT /products/{id} with { "stock_level": N }
Test connection✅Hits /settings; falls back to /products if the key lacks settings scope
ℹ️ Tracking note: Unlike CS-Cart, CubeCart has no separate shipment object. Tracking is stored directly on the order as ship_tracking and ship_method fields. A PUT to /orders/{id} with those fields updates tracking instantly — no products map or shipping_id derivation required.

Troubleshooting

✕ 401 Unauthorized

The API key or secret is wrong, or the key has been deleted and regenerated since the connection was saved. Go to Developer → API Keys in your CubeCart admin panel, confirm the key still exists, and update the connection in EcomCentral with the correct credentials.

✕ 403 Forbidden

The API key exists but lacks the required permission for the requested endpoint (e.g. write access on orders or products). Edit the key in Developer → API Keys and enable the missing read/write permission, then retry.

✕ Connection error / SSL error

Verify the base_url is correct and your CubeCart store has a valid SSL certificate. EcomCentral connects over HTTPS with peer verification enabled. Self-signed certificates are not accepted.

✕ CubeCart version too old (no API)

The CubeCart REST API is only available in version 6.5 and later. If your store is running an older version of CubeCart 6, the api.php entry point will not exist or will return a 404. Upgrade your CubeCart installation to 6.5+ to use this integration.