Cup Source API Integration

📘 Introduction

The Cup Source API allows developers to programmatically manage wholesale drinkware and packaging inventory, place bulk orders, retrieve tracking information, and sync product metadata. All responses are returned in JSON format.

💡

Need help? Join our Developer Discord or email api-support@cupsource.com.

🔐 Authentication

Access to the API requires a valid API key. Generate yours from the Developer Dashboard. Include it in the Authorization header as a Bearer token.

curl -X GET https://api.cupsource.com/v1/products
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"

const fetchProducts = async () => {
  const res = await fetch('https://api.cupsource.com/v1/products', {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });
  return res.json();
};

import requests

headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.get("https://api.cupsource.com/v1/products", headers=headers)
print(response.json())

🌐 Base URL & Response Format

All API requests should be made to:

https://api.cupsource.com/v1

Successful responses wrap data in a standard envelope:

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 142
  }
}

📡 Core Endpoints

Manage inventory, place orders, and track shipments programmatically.

GET /products

Retrieve a paginated list of available cups, bowls, and accessories. Supports filtering by category, material, and capacity.

Parameter	Type	Description
`category`	string	Filter: `cups`, `bowls`, `lids`
`material`	string	Filter: `paper`, `plastic`, `bioplastic`
`page`	integer	Pagination index (default: 1)

POST /orders

Create a new wholesale order. Requires an authenticated account with verified billing.

{
  "items": [
    { "sku": "CS-8OZ-ECO", "qty": 5000 },
    { "sku": "CS-DOME-LID", "qty": 5000 }
  ],
  "shipping_address": { "line1": "123 Commerce Way", "city": "Portland", "state": "OR", "zip": "97201" },
  "currency": "USD"
}

GET /orders/{id}/tracking

Returns real-time carrier tracking status, estimated delivery, and signature requirements.

⚡ Rate Limits & Errors

API requests are limited to 120 requests per minute per API key. Exceeding this triggers a 429 Too Many Requests response with a Retry-After header.

Status Code	Meaning	Resolution
`400`	Bad Request	Check payload structure & required fields
`401`	Unauthorized	Verify API key validity & expiration
`403`	Forbidden	Account lacks required permissions
`404`	Not Found	Endpoint or resource ID is invalid
`429`	Rate Limited	Implement exponential backoff
`500`	Server Error	Contact support if persistent

⚠️

Do not expose your API key in client-side code or public repositories. Use environment variables or secret managers.

📦 SDKs & Libraries

Official client libraries are available for rapid integration:

🟨 Node.js — npm install @cupsource/sdk
🐍 Python — pip install cupsource-api
☕ Java — Maven Central: com.cupsource:sdk-java:1.2.0
🐘 PHP — Composer: require 'cupsource/cupsource-php'

All SDKs support async calls, automatic retry logic, and TypeScript type definitions.

🛟 Support & Status

Monitor API uptime, maintenance windows, and incident reports at our Status Page. For integration questions, bug reports, or partnership inquiries:

📧 api-support@cupsource.com
💬 Developer Discord Community
📖 Interactive Postman Collection

Generate API Key →