API Quick Start
Get up and running with the GCP API in under 5 minutes. This guide covers authentication, your first API call, and essential concepts.
Base URL
https://api.globalcannabisproduct.com/v2
Sandbox Available
Use https://sandbox-api.globalcannabisproduct.com/v2 for testing. Sandbox data resets every 24 hours.
1. Get Your API Keys
Generate API keys from your Dashboard → Settings → API Keys. You'll receive:
gcp_pk_live_...— Public key (safe for client-side)gcp_sk_live_...— Secret key (server-side only, never expose)
2. Make Your First Request
curl -X GET "https://api.globalcannabisproduct.com/v2/marketplace/products" \ -H "Authorization: Bearer gcp_sk_live_your_key_here" \ -H "Content-Type: application/json"
3. Install an SDK
# Node.js npm install @globalcannabis/sdk # Python pip install globalcannabis-sdk # PHP composer require globalcannabis/sdk
4. Initialize the Client
import { GCPClient } from '@globalcannabis/sdk'; const gcp = new GCPClient({ apiKey: 'gcp_sk_live_your_key_here', environment: 'production' // or 'sandbox' }); // Fetch products const products = await gcp.marketplace.getProducts({ category: 'cbd', page: 1, limit: 20 }); console.log(products);
Authentication
All API requests require authentication via a Bearer token in the Authorization header.
Header Format
Authorization: Bearer gcp_sk_live_abc123def456ghi789
OAuth 2.0 (For User-Scoped Access)
For applications that act on behalf of a user, implement OAuth 2.0 Authorization Code flow.
// Step 1: Redirect user to authorization URL const authUrl = `https://auth.globalcannabisproduct.com/oauth/authorize` + `?client_id=YOUR_CLIENT_ID` + `&redirect_uri=https://yourapp.com/callback` + `&response_type=code` + `&scope=marketplace:read orders:write`; // Step 2: Exchange code for token const token = await fetch('https://auth.globalcannabisproduct.com/oauth/token', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ grant_type: 'authorization_code', code: 'AUTH_CODE_FROM_CALLBACK', client_id: 'YOUR_CLIENT_ID', client_secret: 'YOUR_CLIENT_SECRET', redirect_uri: 'https://yourapp.com/callback' }) });
Keep Your Secret Key Safe
Never expose your gcp_sk_ key in client-side code, public repositories, or browser requests. Use environment variables on your server.
Rate Limits
API requests are rate-limited per API key to ensure platform stability.
| Plan | Requests / Minute | Requests / Day | Burst |
|---|---|---|---|
| Starter | 60 | 10,000 | 10 req/sec |
| Growth | 300 | 100,000 | 50 req/sec |
| Enterprise | 1,000 | Unlimited | 200 req/sec |
Rate limit headers are included in every response:
X-RateLimit-Limit: 300 X-RateLimit-Remaining: 297 X-RateLimit-Reset: 1711234567
Error Handling
The API uses standard HTTP status codes. All error responses include a JSON body with details.
{
"status": "error",
"error": {
"code": "INVALID_API_KEY",
"message": "The API key provided is invalid or expired.",
"doc_url": "https://docs.globalcannabisproduct.com/errors/INVALID_API_KEY"
}
}| Code | Status | Description |
|---|---|---|
INVALID_API_KEY | 401 | API key is missing, invalid, or expired |
PERMISSION_DENIED | 403 | Key doesn't have permission for this endpoint |
NOT_FOUND | 404 | Resource doesn't exist |
VALIDATION_ERROR | 422 | Request body has invalid parameters |
RATE_LIMITED | 429 | Too many requests — retry after reset |
SERVER_ERROR | 500 | Internal error — contact support |
All Endpoints
Complete list of available API endpoints grouped by resource.
Marketplace
| Method | Endpoint | Description |
|---|---|---|
| GET | /v2/marketplace/products | List all marketplace products |
| GET | /v2/marketplace/products/:id | Get single product details |
| GET | /v2/marketplace/categories | List product categories |
| GET | /v2/marketplace/producers | List verified producers |
Inventory
| Method | Endpoint | Description |
|---|---|---|
| GET | /v2/inventory | List your inventory items |
| POST | /v2/inventory | Add new inventory item |
| PUT | /v2/inventory/:id | Update inventory item |
| DELETE | /v2/inventory/:id | Remove inventory item |
Orders
| Method | Endpoint | Description |
|---|---|---|
| GET | /v2/orders | List all orders |
| POST | /v2/orders | Create new order |
| GET | /v2/orders/:id | Get order details |
| PUT | /v2/orders/:id/status | Update order status |
Tracking
| Method | Endpoint | Description |
|---|---|---|
| GET | /v2/track/:tracking_id | Get shipment tracking data |
| GET | /v2/track/:id/climate | Get climate sensor readings |
| GET | /v2/track/:id/timeline | Get tracking timeline events |
Compliance
| Method | Endpoint | Description |
|---|---|---|
| GET | /v2/compliance/status | Get account compliance status |
| GET | /v2/compliance/documents | List compliance documents |
| POST | /v2/compliance/documents/generate | Auto-generate compliance doc |
Marketplace API
Search, filter, and retrieve products from the global marketplace.
List Products
GET /v2/marketplace/products?category=cbd&origin=canada&page=1&limit=20
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| category | string | Optional | Filter by category: cbd, extract, flower, edible, preroll |
| origin | string | Optional | Filter by origin country |
| search | string | Optional | Full-text search across product names and descriptions |
| min_price | number | Optional | Minimum price filter (per kg) |
| max_price | number | Optional | Maximum price filter (per kg) |
| page | integer | Optional | Page number (default: 1) |
| limit | integer | Optional | Results per page (max: 100, default: 20) |
| sort | string | Optional | Sort by: price_asc, price_desc, name, newest |
Response
{
"status": "success",
"data": {
"products": [
{
"id": "prod_abc123",
"name": "CBD Isolate 99.5% Pure",
"category": "CBD Products",
"price": 850,
"unit": "kg",
"origin": "Canada",
"producer": {
"id": "prod_xyz789",
"name": "Your Brand",
"verified": true
},
"certifications": ["GMP", "Organic", "COA"],
"image_url": "https://cdn.gcp.com/products/cbd-isolate.jpg"
}
],
"pagination": {
"total": 1200,
"page": 1,
"limit": 20,
"pages": 60
}
}
}Inventory API
Manage your product inventory across all warehouse locations.
Get Inventory
const inventory = await gcp.inventory.list({ location: 'toronto', category: 'extract', low_stock: true // Only items below reorder threshold }); console.log(inventory.items); // [{ id: "inv_001", product: "THC Distillate 92%", quantity: 500, ... }]
Orders API
Create and manage trade orders programmatically.
Create an Order
const order = await gcp.orders.create({ product_id: 'prod_abc123', quantity: 100, unit: 'kg', shipping_address: { name: 'Acme Cannabis', address: '123 Trade St', city: 'Amsterdam', country: 'NL', postal_code: '1012 AB' }, shipping_method: 'air_freight', payment_method: 'escrow' }); console.log(order.id); // "ord_xyz456"
Tracking API
Real-time shipment tracking with GPS, climate, and compliance data.
Track Shipment
const tracking = await gcp.track.getShipment('GCP-4821'); console.log(tracking.status); // "in_transit" console.log(tracking.location); // { lat: 52.3, lng: 4.9 } console.log(tracking.eta); // "2025-03-18T14:00:00Z" console.log(tracking.climate); // { temp: 4.2, humidity: 52 }
Compliance API
Manage regulatory compliance documents and status.
Generate Compliance Document
const doc = await gcp.compliance.generateDocument({ type: 'certificate_of_origin', order_id: 'ord_xyz456', format: 'pdf' }); console.log(doc.download_url); // "https://cdn.gcp.com/docs/..."
Webhooks
Receive real-time notifications when events occur on your account.
Available Events
| Event | Description |
|---|---|
order.created | A new order has been placed |
order.paid | Escrow has been funded |
order.shipped | Order has been shipped |
order.delivered | Delivery confirmed |
tracking.updated | Shipment location or status changed |
compliance.alert | Compliance document expiring or required |
inventory.low | Inventory item below reorder threshold |
Webhook Payload
{
"event": "order.shipped",
"timestamp": "2025-03-15T14:30:00Z",
"data": {
"order_id": "ord_xyz456",
"tracking_id": "GCP-4821",
"carrier": "DHL Express",
"eta": "2025-03-18T14:00:00Z"
},
"signature": "sha256=abc123..."
}Verify Webhook Signatures
Always verify the signature field using your webhook secret to prevent spoofed requests. See our Security Guide for implementation details.
SDKs & Libraries
Official client libraries to accelerate your integration.
| Language | Package | Install |
|---|---|---|
| JavaScript / Node.js | @globalcannabis/sdk | npm install @globalcannabis/sdk |
| Python | globalcannabis-sdk | pip install globalcannabis-sdk |
| PHP | globalcannabis/sdk | composer require globalcannabis/sdk |
| Ruby | globalcannabis-ruby | gem install globalcannabis-ruby |
Need Help?
Contact our developer support at api-support@globalcannabisproduct.com or join our Developer Discord community for real-time assistance.
