API & Integration Hub

Authentication

Access to the Cup Source API requires an API key or OAuth 2.0 token. All requests must be made over HTTPS. Keys are scoped to specific environments (sandbox/production) and can be rotated from your developer dashboard.

Security Note: Never expose your secret keys in client-side code or public repositories. Use environment variables and server-side proxy patterns.

# Authenticate & fetch products
curl -X GET "https://api.cupsource.com/v1/products?limit=25" \
  -H "Authorization: Bearer cs_live_sk_8f3a2b9c1d..." \
  -H "Content-Type: application/json"

# Python (requests library)
import requests

headers = {
    "Authorization": "Bearer cs_live_sk_8f3a2b9c1d...",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.cupsource.com/v1/products?limit=25",
    headers=headers
)
print(response.json())

// Node.js (axios)
const axios = require('axios');

const config = {
  headers: {
    'Authorization': 'Bearer cs_live_sk_8f3a2b9c1d...',
    'Content-Type': 'application/json'
  }
};

axios.get('https://api.cupsource.com/v1/products?limit=25', config)
  .then(res => console.log(res.data));

Core Endpoints

Our REST API follows standard conventions. All resources are returned as JSON. Pagination is supported via limit and offset query parameters.

GET

/v1/products

Retrieve catalog items including dimensions, materials, MOQ, and pricing tiers.

POST

/v1/orders

Submit a new wholesale or custom-branded order with item SKUs and quantities.

GET

/v1/inventory

Check real-time stock levels by warehouse region or product variant.

PUT

/v1/orders/{id}/status

Update order fulfillment status or request production holds.

Response Structure

Field	Type	Description
`data`	Object	The requested resource payload
`pagination`	Object	Contains `total`, `limit`, `offset`
`meta.request_id`	String	Unique ID for support & debugging
`errors`	Array	Present only on failure; includes `code` & `message`

Webhooks

Subscribe to real-time events instead of polling. We sign every webhook payload with your secret key so you can verify authenticity.

Supported Events

order.created — New order placed
order.shipped — Package dispatched with tracking
inventory.low — Stock falls below threshold
production.approved — Custom artwork cleared for print

{
  "event_id": "evt_9x72k1m4",
  "type": "order.shipped",
  "timestamp": "2025-06-14T09:22:18Z",
  "data": {
    "order_id": "ord_cup_8821a",
    "carrier": "FedEx Ground",
    "tracking": "7940011899562847192013",
    "estimated_delivery": "2025-06-17"
  }
}

Rate Limits & Status

API calls are limited to 600 requests per minute on standard plans and 2,400/min on enterprise tiers. Exceeding limits returns 429 Too Many Requests with a Retry-After header.

Monitor system health and scheduled maintenance at status.cupsource.com. We maintain 99.95% uptime SLA for production endpoints.

SDKs & Integration Tools

Accelerate development with officially maintained libraries or our integration marketplace.

🐍 cupsource-python

Type-hinted, async-ready SDK. Install via pip install cupsource.

⚛️ @cupsource/node

Modern TypeScript client with automatic retries & pagination helpers.

📊 Postman Collection

Import our curated workspace to test endpoints before writing code.

Build on the Cup Source API