Public API

Authentication

Send your key as a bearer token on every request:

Authorization: Bearer pk_your_key_here

GET /api/v1/products

Paginated list of active products. Access is limited to the suppliers allowed for your API key (keys with no restriction see all suppliers). Query params (all optional): page, limit (max 100), category (matches GWS or supplier category), search, supplier (a supplier's slug within your allowed set). Each product includes category (GWS category when set, otherwise supplier category), supplier_category, and gws_category. decoration_options is a structured breakdown of branding/decoration methods (each with a unit price and setup price), where decoration stays as a plain-text summary of the same data.

curl "https://promocat.mypromosearch.au/api/v1/products?category=Bags" \
  -H "Authorization: Bearer pk_your_key_here"

{
  "total": 1,
  "page": 1,
  "totalPages": 1,
  "data": [
    {
      "id": "6273e0a9-...",
      "name": "Branded Tote Bag",
      "slug": "branded-tote-bag",
      "sku": "TOTE-001",
      "brand": "Acme",
      "price": 12.5,
      "category": "Bags",
      "supplier_category": "Tote Bags",
      "gws_category": "Bags",
      "colours": "Navy, Black",
      "dimensions": "38 x 42 cm",
      "material": "Cotton canvas",
      "decoration": "Screen Print, Embroidery",
      "decoration_options": [
        {"type": "DO", "label": "Screen Print", "description": "One colour screen print", "unit_price": 0.85, "setup_price": 45.0},
        {"type": "DE", "label": "Embroidery", "description": "Up to 8000 stitches", "unit_price": 1.2, "setup_price": 60.0}
      ],
      "quantity_breaks": [
        {"qty": 50, "price": 0.98},
        {"qty": 100, "price": 0.88},
        {"qty": 250, "price": 0.77}
      ],
      "stock": 500,
      "image_url": null,
      "supplier": "Acme Promo Co",
      "is_active": true
    }
  ]
}

GET /api/v1/products/<slug>

Single product by slug. Increments its view count.

curl "https://promocat.mypromosearch.au/api/v1/products/branded-tote-bag" \
  -H "Authorization: Bearer pk_your_key_here"

POST /api/v1/events

Report that a product you pulled from the API led to a click or an order on your end. event_type is "order" or "click".

curl -X POST "https://promocat.mypromosearch.au/api/v1/events" \
  -H "Authorization: Bearer pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "6273e0a9-...", "event_type": "order"}'

Try it

Test GET /api/v1/products with your own key, right here.