Cup Source API Documentation

Welcome to the Cup Source API. This RESTful API allows you to programmatically manage wholesale cup and bowlware inventory, place bulk orders, track shipments, and integrate custom branding workflows directly into your POS or ERP system.

Base URL

https://api.cupsource.com/v1

Authentication

All API requests require authentication via Bearer token. Include your API key in the Authorization header.

Header Format

Authorization: Bearer cs_live_9f8e7d6c5b4a3210

Obtain your key from the Developer Dashboard. Keep it secure and never expose it in client-side code.

List Products

GET /products

Retrieve a paginated list of available wholesale cups, bowls, and accessories.

Query Parameters

Parameter	Type	Description
`category`	string	Filter by type (e.g., `coffee_cups`, `cold_cups`, `bowls`)
`size_oz`	integer	Filter by volume in ounces
`eco_friendly`	boolean	Only return compostable/recyclable items
`limit`	integer	Items per page (default: 20, max: 100)

cURL

JavaScript

Python

curl -X GET "https://api.cupsource.com/v1/products?category=coffee_cups&limit=10" \
  -H "Authorization: Bearer cs_live_9f8e7d6c5b4a3210"

const res = await fetch('https://api.cupsource.com/v1/products?category=coffee_cups', {
  headers: { 'Authorization': 'Bearer cs_live_9f8e7d6c5b4a3210' }
});
console.log(await res.json());

import requests
res = requests.get('https://api.cupsource.com/v1/products', params={'category': 'coffee_cups'},
  headers={'Authorization': 'Bearer cs_live_9f8e7d6c5b4a3210'})
print(res.json())

Response

{
  "data": [
    {
      "id": "prod_8x7z6y5w",
      "name": "Double-Wall Paper Coffee Cup",
      "category": "coffee_cups",
      "size_oz": 12,
      "material": "Kraft Paper + PE Lining",
      "eco_friendly": true,
      "moq": 500,
      "price_per_unit": 0.14,
      "currency": "USD"
    }
  ],
  "pagination": { "page": 1, "per_page": 10, "total": 142 }
}

Create Wholesale Order

POST /orders

Submit a bulk order for cups, bowls, or accessories. Orders under 500 units are subject to standard pricing.

Request Body

Field	Type	Required	Description
`items`	array	Yes	Array of { product_id, quantity } objects
`ship_to`	object	Yes	Shipping address { name, street, city, state, zip, country }
`custom_print`	boolean	No	Apply approved artwork to products
`notes`	string	No	Internal fulfillment notes

Response (201)

{
  "id": "ord_4k3j2h1g",
  "status": "processing",
  "total_amount": 145.50,
  "currency": "USD",
  "created_at": "2025-03-15T10:22:00Z",
  "estimated_ship": "2025-03-17T00:00:00Z",
  "tracking_url": null
}

Status Codes

The API uses standard HTTP status codes to indicate success or failure.

200 OK

Request succeeded

201 Created

Resource successfully created

400 Bad Request

Missing or invalid parameters

401 Unauthorized

Invalid or missing API key

429 Too Many Requests

Rate limit exceeded

500 Internal Error

Server-side processing error

Rate Limits

To ensure fair usage, the Cup Source API enforces the following limits:

Standard Tier: 60 requests per minute
Business Tier: 300 requests per minute
Enterprise Tier: Custom limits with dedicated support

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Error Handling

Errors are returned as JSON with a structured payload:

{
  "error": {
    "code": "invalid_quantity",
    "message": "Quantity must be a multiple of 50 for bulk orders.",
    "details": { "field": "items[0].quantity", "min_multiple": 50 },
    "request_id": "req_7h6g5f4d"
  }
}

Always check the status code and error object in failed requests. Include the request_id when contacting support.