Overview

Welcome to the Cup Source Partner Documentation. This guide covers everything you need to integrate with our wholesale ordering platform, automate bulk procurement, manage custom packaging workflows, and sync fulfillment data with your existing systems.

ℹ️ Audience

This documentation is intended for B2B partners, POS/ERP integrators, and supply chain developers. For retail browsing and direct consumer orders, visit cupsource.com.

Base URL & Environment

All API requests should be routed to our primary production endpoint:

https://api.cupsource.com/v2

Sandbox/testing requests use the same path but require the X-Environment: sandbox header.

Authentication

Cup Source uses Bearer token authentication. Generate your API keys from the Partner Dashboard under Settings → API Access.

Authorization: Bearer cs_live_sk_8f7d6c5b4a3e2d1f

⚠️ Security Notice

Never commit secret keys to version control or expose them in frontend code. Rotate keys immediately if compromised.

Products & Catalog

Retrieve available drinkware, bowls, sleeves, and accessories. Filter by material, certification, size, or eco-rating.

GET

/products

Query Parameters

Parameter	Type	Required	Description
`category`	string	No	Filter by SKU group (e.g., `paper_cups`, `plastic_bowls`)
`eco_certified`	boolean	No	Include only FSC/compostable certified items
`min_moz`	integer	No	Minimum order quantity threshold
`limit`	integer	No	Results per page (default: 20, max: 100)
`cursor`	string	No	Pagination token from previous response

Example Request

curl -X GET 'https://api.cupsource.com/v2/products?category=coffee_cups&eco_certified=true&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response Schema

{
  'data': [
    {
      'id': 'prod_8x92k4m',
      'name': 'Double-Wall 12oz Coffee Cup',
      'sku': 'CS-CF-12DW',
      'material': 'Kraft Paper + PLA Lining',
      'certifications': ['FSC-MIX', 'BPI_Compostable'],
      'pricing': { 'unit_price': 0.14, 'currency': 'USD', 'min_order_qty': 1000 },
      'stock_status': 'available',
      'lead_time_days': 3
    }
  ],
  'pagination': { 'total': 142, 'has_more': true, 'next_cursor': 'eyJpZCI6MTQyfQ==' }
}

Creating Orders

POST

/orders

Submit wholesale purchase orders. All line items must meet MOQs. Custom branding assets should be uploaded via the /assets endpoint and referenced by asset_id.

Order Payload

{
  'line_items': [
    { 'product_id': 'prod_8x92k4m', 'quantity': 5000 }
  ],
  'custom_branding': {
    'asset_id': 'art_9f3m2x',
    'print_method': 'flexography',
    'proof_approval_deadline': '2025-04-15T00:00:00Z'
  },
  'shipping': {
    'method': 'freight_pallet',
    'address': { 'line1': '123 Warehouse Blvd', 'city': 'Portland', 'state': 'OR', 'postal_code': '97201', 'country': 'US' }
  },
  'billing': { 'po_number': 'PO-2025-0892', 'net_terms': '30' }
}

Webhooks

Subscribe to asynchronous events for production milestones, proof reviews, and logistics tracking. Configure endpoints via the dashboard or POST /webhooks.

Event Types

order.created - Order validated and queued
proof.approved - Artwork cleared for print
production.completed - Goods finished and QC passed
shipment.labeled - Tracking number assigned
shipment.delivered - POD confirmed

🔐 Signature Verification

All payloads are signed with HMAC-SHA256. Validate the X-CupSource-Signature header against your webhook secret before processing.

Brand & Packaging Specifications

To ensure print fidelity across curved substrates, adhere to these guidelines:

Resolution: Minimum 300 DPI at 100% scale
Color Profile: FOGRA39 (CMYK) | Pantone spot colors supported for runs >50k
Safe Margin: Maintain 3mm clearance from vertical seams and die-cut edges
Accepted Formats: .AI, .EPS, .PDF (vector), .TIFF/.PNG (raster)

Documentation v2.4.1 • Last updated: March 2025 Report an Issue →