Merchant API Documentation

Welcome to the Tulus.ee Merchant API (v7.0). This API allows external stores (such as WooCommerce, Shopify, or custom platforms) to sync discount campaigns, track coupon usage, and retrieve performance analytics from the Tulus platform.

Base URL: https://api.tulus.ee/api.php
Content-Type: application/json

Authentication

All requests must include your unique API Key in the HTTP Header. You can generate this key in the Tulus Merchant Dashboard.

Header	Value	Description
`X-Tulus-Auth`	`tl_a1b2c3...`	Your unique Merchant API Key.

Example Header

X-Tulus-Auth: tl_a1b2c3d4e5f6g7h8...

GET Get Categories

Retrieve the list of active campaign categories. Use these IDs when creating a campaign.

GET /api.php?action=categories

Response

{
  "status": "success",
  "data": [
    { "id": 1, "title": "Mood & Ilu" },
    { "id": 2, "title": "Elektroonika" },
    { "id": 9, "title": "Kodu & Aed" }
  ]
}

GET Get Statistics

Fetch lifetime performance stats (Views, Clicks, Copies, Usage) for all active campaigns.

GET /api.php?action=stats

Response

{
  "status": "success",
  "data": {
    "SUMMER20": { "views": 150, "clicks": 45, "copies": 12, "used": 3 },
    "WINTER10": { "views": 80, "clicks": 20, "copies": 5, "used": 0 }
  }
}

GET Get Analytics (Graph)

Retrieve daily data points for graphing performance over a time range.

GET /api.php?action=analytics&start=2023-10-01&end=2023-10-07

Parameters

Param	Required	Description
`action`	Yes	Must be set to `analytics`.
`start`	No	Start date (YYYY-MM-DD). Default: 30 days ago.
`end`	No	End date (YYYY-MM-DD). Default: Today.

Response

{
  "status": "success",
  "data": {
    "2023-10-01": { "view": 10, "click": 2, "copy": 1, "usage": 0, "revenue": 0 },
    "2023-10-02": { "view": 15, "click": 5, "copy": 2, "usage": 1, "revenue": 49.99 }
  }
}

POST Create or Update Campaign

Sync a campaign. If the coupon_code exists, it updates the offer; otherwise, creates a new one.

POST /api.php

Body Parameters (JSON)

Field	Required	Description
`campaign_name`	Yes	Internal campaign name.
`coupon_code`	Yes	Unique discount code (e.g. SALE20).
`discount_display`	No	Text to show (e.g. "20%" or "10€").
`store_url`	No	Direct link to offer/shop.
`expiry_date`	No	YYYY-MM-DD.
`category_id`	No	ID from categories endpoint (Default: 9).

Example Request

{
  "campaign_name": "Must Reede",
  "coupon_code": "BLACKFRIDAY",
  "discount_display": "25%",
  "store_url": "https://myshop.ee",
  "expiry_date": "2024-12-31",
  "category_id": 2
}

POST Track Usage

Notify Tulus when a purchase is made using a coupon. This logs revenue.

POST /api.php

Example Request

{
  "action": "track_usage",
  "coupon_code": "BLACKFRIDAY",
  "order_amount": 125.50
}

Response

{ "status": "success", "message": "Usage tracked" }

DELETE Delete Campaign

Permanently remove a campaign and its history from Tulus.ee.

DELETE /api.php?code=BLACKFRIDAY

Response

{ "status": "success", "message": "Offer permanently deleted" }

Error Codes

Code	Meaning
`200`	OK - Request successful.
`201`	Created - New resource created.
`400`	Bad Request - Missing fields/Invalid JSON.
`401`	Unauthorized - Missing API Key.
`403`	Forbidden - Invalid API Key.
`404`	Not Found - Coupon not found.
`500`	Internal Error - Database issue.

PHP Integration Example

A simple PHP function using cURL to connect to the API.

<?php
function call_tulus_api($endpoint, $method = 'GET', $data = []) {
    $api_key = 'tl_YOUR_API_KEY';
    $url = 'https://api.tulus.ee/api.php' . $endpoint;

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'X-Tulus-Auth: ' . $api_key
    ]);

    if ($method === 'POST') {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    } elseif ($method === 'DELETE') {
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
    }

    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

// Usage: Create a campaign
$res = call_tulus_api('', 'POST', [
    'campaign_name' => 'Summer Sale',
    'coupon_code' => 'SUMMER20',
    'discount_display' => '20%'
]);
?>