Get API Key

Welcome to the OffersInc Merchant API

Complete REST API for integrating DD credit transactions, offers, and customer management into your Point-of-Sale system, e-commerce platform, or custom application. Build powerful integrations with comprehensive endpoints covering the entire transaction lifecycle.

Base URL: https://offersinc.ca/api/v1

API Monitoring & Debugging

📊 Real-Time Request Logging

Every API request is automatically logged and visible in your merchant dashboard. Access comprehensive logs to debug issues and monitor API usage.

Access Your Logs:

  • Dashboard: Settings → API Keys → View Logs
  • View requests by specific API key or see all requests
  • Filter by date, endpoint, HTTP method, status code, or errors only
What You Can See in Logs:
Request method (GET, POST, PUT, DELETE)
Full URL with query parameters
Request headers (sanitized for security)
Request body (sensitive fields redacted)
Response status code
Response body
Response time in milliseconds
IP address & timestamp

🔒 Security Note: Sensitive fields (passwords, PIN codes, API keys) are automatically redacted in logs for your protection.

Error Handling

Consistent Error Format

All API errors follow a standard JSON format for easy programmatic handling:

JSON
1{
2 "success": false,
3 "error": "error_code",
4 "message": "Human-readable error message",
5 "details": {} // Optional, for validation errors
6}

HTTP Status Codes

200 Success
201 Created
401 Authentication Error
403 Authorization Error
404 Not Found
422 Validation Error
429 Rate Limit Exceeded
500 Server Error

🔒 Security Promise

Stack traces, SQL queries, file paths, and internal system details are NEVER exposed in API responses.

Rate Limiting

120
Requests per minute
X-RateLimit-*
Response headers
429
Error when exceeded

Quick Start Guide

  1. 1 Get Your API Key: Generate from Settings → API Keys in your dashboard
  2. 2 Test Authentication: Call GET /merchant to verify your key works
  3. 3 Review Logs: Check dashboard to see your request logged
  4. 4 Build Integration: Use endpoints in this documentation
  5. 5 Monitor Usage: Track requests in real-time via dashboard

What You Can Build

🛒 E-Commerce Integration

Accept DD credits as payment method

📱 Custom POS Systems

Build your own point-of-sale software

💼 Accounting Integration

Sync transactions to QuickBooks/Xero

📊 Analytics Dashboards

Build custom reporting tools

API Key Authentication

All API requests must include your API key in the X-API-Key header.

🔑 Generating API Keys

  1. Log into your merchant dashboard
  2. Navigate to Settings → API Keys
  3. Click "Create API Key"
  4. Copy the key immediately (shown only once)
  5. Store your key securely (never commit to version control)

⚠️ Security Warning: Never expose API keys in client-side code (JavaScript, mobile apps). Use server-side proxies to protect your keys.

Code Examples

Here's how to authenticate API requests in different programming languages:

cURL (Command Line)

BASH
1curl -X GET https://offersinc.ca/api/v1/merchant \
2 -H "X-API-Key: mk_your_api_key_here" \
3 -H "Accept: application/json"

PHP (with Laravel HTTP Client)

PHP
1use Illuminate\Support\Facades\Http;
2
3$response = Http::withHeaders([
4 'X-API-Key' => 'mk_your_api_key_here',
5 'Accept' => 'application/json',
6])->get('https://offersinc.ca/api/v1/merchant');
7
8$merchant = $response->json();

Python (with Requests)

PYTHON
1import requests
2
3headers = {
4 'X-API-Key': 'mk_your_api_key_here',
5 'Accept': 'application/json'
6}
7
8response = requests.get(
9 'https://offersinc.ca/api/v1/merchant',
10 headers=headers
11)
12
13merchant = response.json()

Node.js (with Axios)

JAVASCRIPT
1const axios = require('axios');
2
3const response = await axios.get(
4 'https://offersinc.ca/api/v1/merchant',
5 {
6 headers: {
7 'X-API-Key': 'mk_your_api_key_here',
8 'Accept': 'application/json'
9 }
10 }
11);
12
13const merchant = response.data;

Ruby (with HTTParty)

RUBY
1require 'httparty'
2
3response = HTTParty.get(
4 'https://offersinc.ca/api/v1/merchant',
5 headers: {
6 'X-API-Key' => 'mk_your_api_key_here',
7 'Accept' => 'application/json'
8 }
9)
10
11merchant = response.parsed_response

Security Best Practices

Use Environment Variables: Store API keys in .env files, never hardcode them
Rotate Keys Regularly: Generate new keys periodically and delete unused ones
Use IP Whitelisting: Restrict API keys to specific IP addresses when possible
Server-Side Only: Never expose API keys in client-side JavaScript or mobile apps
Monitor Usage: Check your dashboard logs regularly for suspicious activity
HTTPS Only: Always use HTTPS to prevent man-in-the-middle attacks

Complete Transaction Flow

Step-by-step guide: Validate → Charge → Confirm

Processing a DD credit transaction requires 3 sequential API calls

💡 Transaction Flow Overview

Every DD credit transaction follows this secure 3-step process to ensure customers have sufficient balance before charging:

1
Validate
Check balance
2
Charge
Process payment
3
Confirm
Get receipt
1

Validate Customer PIN

Check balance before charging

POST /api/v1/transactions/lookup-customer

What This Does:

  • Validates the customer's PIN code
  • Returns customer ID, name, and current DD balance
  • Allows you to verify sufficient balance before charging
  • Does NOT charge or create any transaction

⚠️ Important: This is a read-only operation. No DD credits are deducted at this step.

🔒 Privacy: For customer privacy protection, this endpoint only returns customer ID, name, and DD balance. Sensitive personal information (email, phone, address) is never exposed via API.

Example Request:

JSON
1POST /api/v1/transactions/lookup-customer
2{
3 "customer_code": "9199"
4}

Example Response:

JSON
1{
2 "success": true,
3 "data": {
4 "customer_id": 123,
5 "name": "John Doe",
6 "dd_balance": "50.00" // Available DD credits
7 }
8}
2

Process Transaction

Charge DD credits and create transaction

POST /api/v1/transactions

What This Does:

  • Deducts DD credits from customer's balance
  • Creates a permanent transaction record
  • Calculates discount based on offer rules
  • Returns transaction ID for confirmation

🔒 Critical: This immediately deducts DD credits. Ensure customer has sufficient balance first (Step 1).

Example Request:

JSON
1POST /api/v1/transactions
2{
3 "customer_code": "9199",
4 "offer_id": 456,
5 "total_amount": "100.00",
6 "discount_amount": "10.00",
7 "dd_credits_to_use": "10.00"
8}

Example Response:

JSON
1{
2 "success": true,
3 "data": {
4 "transaction_id": 789, // Use this for Step 3
5 "customer_name": "John Doe",
6 "dd_used": "10.00",
7 "new_balance": "40.00"
8 }
9}
3

Get Transaction Details

Retrieve complete details for receipt

GET /api/v1/transactions/{id}

What This Does:

  • Retrieves complete transaction details
  • Includes customer info, offer details, amounts
  • Use this to print receipts or show confirmation
  • Can be called multiple times (read-only)

✅ Best Practice: Always retrieve and show transaction details to customer for confirmation.

Example Request:

HTTP
1GET /api/v1/transactions/789

Example Response:

JSON
1{
2 "success": true,
3 "data": {
4 "id": 789,
5 "customer": { "id": 123, "name": "John Doe" },
6 "offer": { "id": 456, "name": "10% Off Purchase" },
7 "amounts": {
8 "total": "100.00",
9 "discount": "10.00",
10 "dd_used": "10.00"
11 },
12 "created_at": "2025-10-13T14:00:00Z"
13 }
14}

Transaction Complete! 🎉

You've successfully processed a DD credit transaction

💡 Pro Tips

Always validate first: Call Step 1 before Step 2 to ensure customer has sufficient balance
Store transaction_id: Save the ID from Step 2 for future reference and receipt printing
Handle errors gracefully: Step 2 may fail if balance changed between Step 1 and 2
Check your logs: All 3 requests are logged in your dashboard for debugging
GET /merchant

Retrieve complete details about your merchant account including business information, contact details, and account status. Use this endpoint to verify API connectivity and display merchant information in your application.

Responses

200 Successfully retrieved merchant information

401 Unauthorized - Invalid or missing API key

JSON Response
1 {
2 "success": false,
3 "error": "unauthorized",
4 "message": "Invalid API key"
5 }

Code Examples

PHP
1 <?php
2
3 $apiKey = 'mk_your_api_key_here';
4
5 $ch = curl_init('https://offersinc.ca/api/v1/merchant');
6 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
7 curl_setopt($ch, CURLOPT_HTTPHEADER, [
8 'X-API-Key: ' . $apiKey,
9 'Accept: application/json'
10 ]);
11
12 $response = curl_exec($ch);
13 $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
14 curl_close($ch);
15
16 if ($httpCode === 200) {
17 $merchant = json_decode($response, true);
18 echo "Merchant: " . $merchant['data']['dba_name'] . "\n";
19 echo "Status: " . $merchant['data']['status'] . "\n";
20 echo "Balance API: /merchant/balance\n";
21 } else {
22 echo "Error: HTTP " . $httpCode . "\n";
23 }
JavaScript
1 const apiKey = 'mk_your_api_key_here';
2
3 fetch('https://offersinc.ca/api/v1/merchant', {
4 method: 'GET',
5 headers: {
6 'X-API-Key': apiKey,
7 'Accept': 'application/json'
8 }
9 })
10 .then(response => response.json())
11 .then(data => {
12 if (data.success) {
13 console.log('Merchant:', data.data.dba_name);
14 console.log('Status:', data.data.status);
15 console.log('Location:', `${data.data.address.city}, ${data.data.address.province}`);
16 }
17 })
18 .catch(error => console.error('Error:', error));
Python
1 import requests
2
3 api_key = 'mk_your_api_key_here'
4 url = 'https://offersinc.ca/api/v1/merchant'
5
6 headers = {
7 'X-API-Key': api_key,
8 'Accept': 'application/json'
9 }
10
11 response = requests.get(url, headers=headers)
12
13 if response.status_code == 200:
14 merchant = response.json()
15 print(f"Merchant: {merchant['data']['dba_name']}")
16 print(f"Status: {merchant['data']['status']}")
17 print(f"MID: {merchant['data']['mid']}")
18 else:
19 print(f"Error: {response.status_code}")
cURL
1 curl -X GET 'https://offersinc.ca/api/v1/merchant' \
2 -H 'X-API-Key: mk_your_api_key_here' \
3 -H 'Accept: application/json'
GET /merchant/balance

Retrieve your current DD credit balance and comprehensive transaction statistics. This endpoint shows how many DD credits you've purchased, spent, and have available, plus detailed metrics about your transaction volume and customer reach.

Responses

200 Successfully retrieved balance and statistics

Code Examples

PHP
1 <?php
2
3 $ch = curl_init('https://offersinc.ca/api/v1/merchant/balance');
4 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
5 curl_setopt($ch, CURLOPT_HTTPHEADER, [
6 'X-API-Key: mk_your_api_key_here',
7 'Accept: application/json'
8 ]);
9
10 $response = json_decode(curl_exec($ch), true);
11 curl_close($ch);
12
13 if ($response['success']) {
14 $credits = $response['data']['dd_credits'];
15 $stats = $response['data']['statistics'];
16
17 echo "=== DD Credit Balance ===\n";
18 echo "Available: $" . $credits['available'] . "\n";
19 echo "Purchased: $" . $credits['purchased'] . "\n";
20 echo "Spent: $" . $credits['spent'] . "\n\n";
21
22 echo "=== Performance Stats ===\n";
23 echo "Transactions: " . $stats['total_transactions'] . "\n";
24 echo "Sales Generated: $" . $stats['sales_generated'] . "\n";
25 echo "Unique Customers: " . $stats['unique_customers'] . "\n";
26
27 // Calculate ROI
28 $ddInvested = (float)$credits['spent'];
29 $salesGenerated = (float)$stats['sales_generated'];
30 $roi = $ddInvested > 0 ? ($salesGenerated / $ddInvested) : 0;
31 echo "ROI: " . number_format($roi, 2) . "x\n";
32 }
JavaScript
1 async function updateBalanceDashboard() {
2 const response = await fetch('https://offersinc.ca/api/v1/merchant/balance', {
3 headers: {
4 'X-API-Key': 'mk_your_api_key_here',
5 'Accept': 'application/json'
6 }
7 });
8
9 const data = await response.json();
10
11 if (data.success) {
12 const { dd_credits, statistics } = data.data;
13
14 // Update dashboard UI
15 document.getElementById('dd-available').textContent = `$${dd_credits.available}`;
16 document.getElementById('total-transactions').textContent = statistics.total_transactions;
17 document.getElementById('total-sales').textContent = `$${statistics.sales_generated}`;
18 document.getElementById('unique-customers').textContent = statistics.unique_customers;
19
20 // Show low balance warning
21 if (parseFloat(dd_credits.available) < 100) {
22 showWarning('Low DD balance! Consider purchasing more credits.');
23 }
24 }
25 }
26
27 // Update every 5 minutes
28 setInterval(updateBalanceDashboard, 300000);
Python
1 import requests
2 import smtplib
3 from email.mime.text import MIMEText
4
5 def check_dd_balance_and_alert(api_key, threshold=500):
6 """Check DD balance and send email if below threshold"""
7
8 response = requests.get(
9 'https://offersinc.ca/api/v1/merchant/balance',
10 headers={'X-API-Key': api_key}
11 )
12
13 if response.status_code == 200:
14 data = response.json()['data']
15 available = float(data['dd_credits']['available'])
16
17 print(f"Available DD Credits: ${available}")
18
19 if available < threshold:
20 send_alert_email(
21 subject='Low DD Credits Alert',
22 message=f'Your DD balance is ${available}. Consider refilling.'
23 )
24 return False
25 return True
26
27 return False
28
29 # Run daily via cron
30 check_dd_balance_and_alert('mk_your_api_key_here', threshold=500)
cURL
1 curl -X GET 'https://offersinc.ca/api/v1/merchant/balance' \
2 -H 'X-API-Key: mk_your_api_key_here' \
3 -H 'Accept: application/json'
GET /merchant/statistics

Retrieve detailed transaction statistics for a specific date range, including daily breakdowns. Perfect for generating reports, analyzing trends, and tracking performance over time.

Query Parameters

Parameter Type Required Description
start_date string Optional Start date for statistics (YYYY-MM-DD format). Defaults to 30 days ago if not specified.
end_date string Optional End date for statistics (YYYY-MM-DD format). Must be after or equal to start_date. Defaults to today if not specified.

Responses

200 Successfully retrieved statistics

JSON Response
1 {
2 "success": true,
3 "data": {
4 "period": {
5 "start": "2025-09-13",
6 "end": "2025-10-13"
7 },
8 "summary": {
9 "total_transactions": 342,
10 "dd_distributed": "2500.00",
11 "cash_collected": "12250.50",
12 "total_sales": "15750.50",
13 "unique_customers": 89,
14 "average_transaction": "46.05"
15 },
16 "daily_breakdown": [
17 {
18 "date": "2025-10-13",
19 "transactions": 15,
20 "dd_used": "125.00",
21 "sales": "687.50"
22 },
23 {
24 "date": "2025-10-12",
25 "transactions": 18,
26 "dd_used": "150.00",
27 "sales": "825.00"
28 }
29 ]
30 }
31 }

422 Validation Error - Invalid date format or end_date before start_date

JSON Response
1 {
2 "success": false,
3 "error": "Validation failed",
4 "message": "The provided data is invalid",
5 "details": {
6 "end_date": [
7 "The end date must be after or equal to start date."
8 ]
9 }
10 }

Code Examples

PHP
1 <?php
2
3 // Generate report for last 30 days
4 $startDate = date('Y-m-d', strtotime('-30 days'));
5 $endDate = date('Y-m-d');
6
7 $url = 'https://offersinc.ca/api/v1/merchant/statistics' .
8 '?start_date=' . $startDate .
9 '&end_date=' . $endDate;
10
11 $ch = curl_init($url);
12 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
13 curl_setopt($ch, CURLOPT_HTTPHEADER, [
14 'X-API-Key: mk_your_api_key_here'
15 ]);
16
17 $response = json_decode(curl_exec($ch), true);
18 curl_close($ch);
19
20 if ($response['success']) {
21 $summary = $response['data']['summary'];
22
23 // Generate CSV report
24 $csv = fopen('monthly_report.csv', 'w');
25 fputcsv($csv, ['Metric', 'Value']);
26 fputcsv($csv, ['Total Transactions', $summary['total_transactions']]);
27 fputcsv($csv, ['DD Distributed', '$' . $summary['dd_distributed']]);
28 fputcsv($csv, ['Total Sales', '$' . $summary['total_sales']]);
29 fputcsv($csv, ['Unique Customers', $summary['unique_customers']]);
30 fputcsv($csv, ['Avg Transaction', '$' . $summary['average_transaction']]);
31
32 // Add daily breakdown
33 fputcsv($csv, []);
34 fputcsv($csv, ['Date', 'Transactions', 'DD Used', 'Sales']);
35
36 foreach ($response['data']['daily_breakdown'] as $day) {
37 fputcsv($csv, [
38 $day['date'],
39 $day['transactions'],
40 '$' . $day['dd_used'],
41 '$' . $day['sales']
42 ]);
43 }
44
45 fclose($csv);
46 echo "Report generated: monthly_report.csv\n";
47 }
JavaScript
1 async function loadSalesChart(days = 30) {
2 const endDate = new Date().toISOString().split('T')[0];
3 const startDate = new Date(Date.now() - days * 24 * 60 * 60 * 1000)
4 .toISOString().split('T')[0];
5
6 const url = `https://offersinc.ca/api/v1/merchant/statistics?start_date=${startDate}&end_date=${endDate}`;
7
8 const response = await fetch(url, {
9 headers: { 'X-API-Key': 'mk_your_api_key_here' }
10 });
11
12 const data = await response.json();
13
14 if (data.success) {
15 // Prepare data for Chart.js
16 const chartData = {
17 labels: data.data.daily_breakdown.map(d => d.date).reverse(),
18 datasets: [
19 {
20 label: 'Sales ($)',
21 data: data.data.daily_breakdown.map(d => parseFloat(d.sales)).reverse(),
22 borderColor: 'rgb(75, 192, 192)',
23 backgroundColor: 'rgba(75, 192, 192, 0.2)'
24 },
25 {
26 label: 'Transactions',
27 data: data.data.daily_breakdown.map(d => d.transactions).reverse(),
28 borderColor: 'rgb(153, 102, 255)',
29 backgroundColor: 'rgba(153, 102, 255, 0.2)'
30 }
31 ]
32 };
33
34 // Render chart
35 new Chart(document.getElementById('salesChart'), {
36 type: 'line',
37 data: chartData,
38 options: {
39 responsive: true,
40 title: { display: true, text: 'Sales Performance' }
41 }
42 });
43 }
44 }
cURL
1 # Get statistics for last 7 days
2 curl -X GET 'https://offersinc.ca/api/v1/merchant/statistics?start_date=2025-10-06&end_date=2025-10-13' \
3 -H 'X-API-Key: mk_your_api_key_here'
GET /offers

Retrieve all DD credit offers for your merchant account with powerful filtering options. Filter by status, approval status, POS availability, and more. Essential for building offer selection interfaces in your POS or e-commerce system.

Query Parameters

Parameter Type Required Description
status string Optional Filter by offer status: active, Loaded, paused, expired
approval_status string Optional Filter by approval status: approved, pending, rejected
pos_enabled boolean Optional Filter offers available for POS transactions (true/false)
active_only boolean Optional Return only currently active, approved offers (true/false)

Responses

200 Successfully retrieved offers list

JSON Response
1 {
2 "success": true,
3 "data": [
4 {
5 "id": 42,
6 "name": "Coffee Rewards",
7 "title": "20% in DD Credits",
8 "description": "Earn 20% back in DD credits on all coffee purchases",
9 "type": "%",
10 "discount": "20.00",
11 "discount_display": "20%",
12 "price_per_item": null,
13 "category": "Food & Beverage",
14 "status": "active",
15 "approval_status": "approved",
16 "pos_enabled": true,
17 "featured": true,
18 "valid_period": {
19 "start": "2025-01-01",
20 "end": "2025-12-31"
21 },
22 "is_active": true,
23 "created_at": "2025-01-01T00:00:00Z",
24 "approved_at": "2025-01-02T10:00:00Z"
25 }
26 ]
27 }

Code Examples

PHP
1 <?php
2
3 // Get only POS-enabled, active offers
4 $url = 'https://offersinc.ca/api/v1/offers?pos_enabled=true&active_only=true';
5
6 $ch = curl_init($url);
7 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
8 curl_setopt($ch, CURLOPT_HTTPHEADER, [
9 'X-API-Key: mk_your_api_key_here'
10 ]);
11
12 $response = json_decode(curl_exec($ch), true);
13 curl_close($ch);
14
15 if ($response['success']) {
16 echo "Available Offers for POS:\n\n";
17
18 foreach ($response['data'] as $offer) {
19 echo "[{$offer['id']}] {$offer['title']}\n";
20 echo " Type: {$offer['discount_display']}\n";
21 echo " Category: {$offer['category']}\n";
22 echo " Status: " . ($offer['is_active'] ? '✓ Active' : '✗ Inactive') . "\n\n";
23 }
24 }
JavaScript
1 async function loadOffersDropdown() {
2 const response = await fetch(
3 'https://offersinc.ca/api/v1/offers?pos_enabled=true&active_only=true',
4 { headers: { 'X-API-Key': 'mk_your_api_key_here' } }
5 );
6
7 const data = await response.json();
8
9 if (data.success) {
10 const select = document.getElementById('offer-select');
11
12 data.data.forEach(offer => {
13 const option = document.createElement('option');
14 option.value = offer.id;
15 option.textContent = `${offer.title} (${offer.discount_display})`;
16 option.dataset.discount = offer.discount;
17 option.dataset.type = offer.type;
18 select.appendChild(option);
19 });
20 }
21 }
cURL
1 curl -X GET 'https://offersinc.ca/api/v1/offers?pos_enabled=true' \
2 -H 'X-API-Key: mk_your_api_key_here'
GET /offers/pos

Retrieve only offers that are enabled for point-of-sale transactions. This is a convenience endpoint that automatically filters for POS-enabled, active, approved offers - perfect for POS systems that need a simple list of valid offers.

Responses

200 Successfully retrieved POS offers

JSON Response
1 {
2 "success": true,
3 "data": [
4 {
5 "id": 42,
6 "name": "Coffee Rewards",
7 "title": "20% in DD Credits",
8 "description": "Earn 20% back in DD credits",
9 "type": "%",
10 "discount": "20.00",
11 "discount_display": "20%",
12 "pos_enabled": true,
13 "is_active": true
14 }
15 ]
16 }

Code Examples

PHP
1 <?php
2
3 $offers = json_decode(file_get_contents(
4 'https://offersinc.ca/api/v1/offers/pos',
5 false,
6 stream_context_create([
7 'http' => [
8 'header' => 'X-API-Key: mk_your_api_key_here'
9 ]
10 ])
11 ), true);
12
13 if ($offers['success']) {
14 // Cache for 5 minutes
15 cache(['pos_offers' => $offers['data']], 300);
16
17 return $offers['data'];
18 }
cURL
1 curl -X GET 'https://offersinc.ca/api/v1/offers/pos' \
2 -H 'X-API-Key: mk_your_api_key_here'
GET /offers/{id}

Retrieve complete details for a specific offer by ID. Returns full offer information including terms, conditions, validity periods, and all configuration details.

Query Parameters

Parameter Type Required Description
id integer Required Offer ID

Responses

200 Successfully retrieved offer

JSON Response
1 {
2 "success": true,
3 "data": {
4 "id": 42,
5 "name": "Coffee Rewards",
6 "title": "20% in DD Credits",
7 "description": "Earn 20% back in DD credits on all coffee purchases over $5",
8 "type": "%",
9 "discount": "20.00",
10 "discount_display": "20%",
11 "price_per_item": null,
12 "category": "Food & Beverage",
13 "status": "active",
14 "approval_status": "approved",
15 "pos_enabled": true,
16 "featured": true,
17 "valid_period": {
18 "start": "2025-01-01",
19 "end": "2025-12-31"
20 },
21 "is_active": true,
22 "created_at": "2025-01-01T00:00:00Z",
23 "approved_at": "2025-01-02T10:00:00Z"
24 }
25 }

404 Offer not found

JSON Response
1 {
2 "success": false,
3 "error": "not_found",
4 "message": "Offer not found"
5 }

Code Examples

PHP
1 <?php
2
3 $offerId = 42;
4 $url = "https://offersinc.ca/api/v1/offers/{$offerId}";
5
6 $ch = curl_init($url);
7 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
8 curl_setopt($ch, CURLOPT_HTTPHEADER, [
9 'X-API-Key: mk_your_api_key_here'
10 ]);
11
12 $response = json_decode(curl_exec($ch), true);
13
14 if ($response['success']) {
15 $offer = $response['data'];
16 echo "Offer: {$offer['title']}\n";
17 echo "Discount: {$offer['discount_display']}\n";
18 echo "Status: " . ($offer['is_active'] ? 'Active' : 'Inactive') . "\n";
19 }
cURL
1 curl -X GET 'https://offersinc.ca/api/v1/offers/42' \
2 -H 'X-API-Key: mk_your_api_key_here'
POST /offers/calculate

Calculate the exact DD discount for a given offer and purchase amount. Use this before processing a transaction to determine how much DD credit to charge and how much discount to apply. Essential for dynamic pricing and accurate transaction processing.

Request Body

Parameter Type Required Description
offer_id integer Required The offer ID to calculate
quantity integer Optional Number of items (default: 1)
total_amount number Optional Total purchase amount before discount

Responses

200 Successfully calculated discount

JSON Response
1 {
2 "success": true,
3 "data": {
4 "offer_id": 42,
5 "offer_name": "20% in DD Credits",
6 "quantity": 2,
7 "subtotal": "25.00",
8 "dd_to_charge": "5.00",
9 "discount_amount": "5.00",
10 "customer_pays": "20.00",
11 "calculation_method": "percentage",
12 "discount_rate": "20%"
13 }
14 }

400 Invalid calculation parameters

JSON Response
1 {
2 "success": false,
3 "error": "invalid_calculation",
4 "message": "Cannot calculate discount for this offer type with the provided parameters"
5 }

404 Offer not found

JSON Response
1 {
2 "success": false,
3 "error": "not_found",
4 "message": "Offer not found"
5 }

Code Examples

PHP
1 <?php
2
3 function calculateDiscount($offerId, $totalAmount, $quantity = 1) {
4 $ch = curl_init('https://offersinc.ca/api/v1/offers/calculate');
5
6 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
7 curl_setopt($ch, CURLOPT_POST, true);
8 curl_setopt($ch, CURLOPT_HTTPHEADER, [
9 'X-API-Key: mk_your_api_key_here',
10 'Content-Type: application/json'
11 ]);
12 curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
13 'offer_id' => $offerId,
14 'quantity' => $quantity,
15 'total_amount' => $totalAmount
16 ]));
17
18 $response = json_decode(curl_exec($ch), true);
19 curl_close($ch);
20
21 if ($response['success']) {
22 $calc = $response['data'];
23
24 return [
25 'dd_charge' => $calc['dd_to_charge'],
26 'discount' => $calc['discount_amount'],
27 'customer_pays' => $calc['customer_pays']
28 ];
29 }
30
31 return null;
32 }
33
34 // Usage in checkout
35 $calculation = calculateDiscount(42, 25.00, 2);
36
37 if ($calculation) {
38 echo "Customer pays: $" . $calculation['customer_pays'] . "\n";
39 echo "DD charged: $" . $calculation['dd_charge'] . "\n";
40 echo "Discount applied: $" . $calculation['discount'] . "\n";
41 }
JavaScript
1 async function calculateOfferDiscount(offerId, amount, quantity = 1) {
2 const response = await fetch('https://offersinc.ca/api/v1/offers/calculate', {
3 method: 'POST',
4 headers: {
5 'X-API-Key': 'mk_your_api_key_here',
6 'Content-Type': 'application/json'
7 },
8 body: JSON.stringify({ offer_id: offerId, total_amount: amount, quantity })
9 });
10
11 const data = await response.json();
12
13 if (data.success) {
14 return data.data;
15 }
16
17 return null;
18 }
19
20 // Update price in real-time as customer types
21 document.getElementById('amount-input').addEventListener('input', async (e) => {
22 const amount = parseFloat(e.target.value);
23 const offerId = document.getElementById('offer-select').value;
24
25 if (amount > 0 && offerId) {
26 const calc = await calculateOfferDiscount(offerId, amount);
27
28 if (calc) {
29 document.getElementById('customer-pays').textContent = `$${calc.customer_pays}`;
30 document.getElementById('dd-charged').textContent = `$${calc.dd_to_charge}`;
31 document.getElementById('savings').textContent = `$${calc.discount_amount}`;
32 }
33 }
34 });
Python
1 import requests
2
3 def calculate_dd_discount(offer_id, total_amount, quantity=1):
4 response = requests.post(
5 'https://offersinc.ca/api/v1/offers/calculate',
6 headers={'X-API-Key': 'mk_your_api_key_here'},
7 json={
8 'offer_id': offer_id,
9 'total_amount': total_amount,
10 'quantity': quantity
11 }
12 )
13
14 if response.status_code == 200:
15 data = response.json()
16 if data['success']:
17 return data['data']
18
19 return None
20
21 # Example
22 calc = calculate_dd_discount(42, 25.00, 2)
23 if calc:
24 print(f"Subtotal: ${calc['subtotal']}")
25 print(f"DD Charged: ${calc['dd_to_charge']}")
26 print(f"Customer Pays: ${calc['customer_pays']}")
cURL
1 curl -X POST 'https://offersinc.ca/api/v1/offers/calculate' \
2 -H 'X-API-Key: mk_your_api_key_here' \
3 -H 'Content-Type: application/json' \
4 -d '{
5 "offer_id": 42,
6 "quantity": 2,
7 "total_amount": 25.00
8 }'
POST /transactions/lookup-customer Step 1: Validation

STEP 1: Validate customer PIN and check DD balance before processing transaction

Request Body

Parameter Type Required Description
customer_code string Required No description provided

Responses

200 Customer validated

JSON Response
1 {
2 "success": true,
3 "data": {
4 "customer_id": 456,
5 "name": "John Doe",
6 "dd_balance": "50.00"
7 }
8 }

404 Invalid PIN

JSON Response
1 {
2 "success": false,
3 "error": "not_found",
4 "message": "Invalid customer code"
5 }

Code Examples

PHP
1 <?php
2 $ch = curl_init('https://offersinc.ca/api/v1/transactions/lookup-customer');
3 curl_setopt($ch, CURLOPT_POST, true);
4 curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['customer_code' => '123456']));
5 curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: mk_key', 'Content-Type: application/json']);
6 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
7 $response = json_decode(curl_exec($ch), true);
8 if ($response['success']) {
9 $balance = $response['data']['dd_balance'];
10 echo "Balance: $$balance\n";
11 }
cURL
1 curl -X POST 'https://offersinc.ca/api/v1/transactions/lookup-customer' \
2 -H 'X-API-Key: mk_key' \
3 -H 'Content-Type: application/json' \
4 -d '{"customer_code": "123456"}'
GET /transactions/{id} Step 3: Confirm

STEP 3: Retrieve complete transaction details for confirmation and receipts

Query Parameters

Parameter Type Required Description
id integer Required No description provided

Responses

200 Transaction retrieved

JSON Response
1 {
2 "success": true,
3 "data": {
4 "id": 789,
5 "reference_number": "ORDER-12345",
6 "customer": {
7 "id": 456,
8 "name": "John Doe"
9 },
10 "offer": {
11 "id": 42,
12 "name": "20% in DD"
13 },
14 "amounts": {
15 "subtotal": "25.00",
16 "dd_used": "5.00",
17 "discount_applied": "5.00",
18 "cash_paid": "20.00"
19 },
20 "created_at": "2025-10-13T00:15:00Z"
21 }
22 }

404 Transaction not found

JSON Response
1 {
2 "success": false,
3 "error": "not_found",
4 "message": "Transaction not found"
5 }

Code Examples

PHP
1 <?php
2 $txnId = 789;
3 $ch = curl_init("https://offersinc.ca/api/v1/transactions/$txnId");
4 curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: mk_key']);
5 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
6 $response = json_decode(curl_exec($ch), true);
7 if ($response['success']) {
8 $txn = $response['data'];
9 echo "Transaction: {$txn['reference_number']}\n";
10 echo "DD Used: \${$txn['amounts']['dd_used']}\n";
11 }
cURL
1 curl -X GET 'https://offersinc.ca/api/v1/transactions/789' \
2 -H 'X-API-Key: mk_key'
GET /transactions

Retrieve paginated transaction history with filtering

Query Parameters

Parameter Type Required Description
start_date string Optional No description provided
end_date string Optional No description provided
customer_id integer Optional No description provided
per_page integer Optional No description provided

Responses

200 Success

JSON Response
1 {
2 "success": true,
3 "data": [
4 {
5 "id": 789,
6 "customer": {
7 "id": 456,
8 "name": "John Doe"
9 },
10 "amounts": {
11 "subtotal": "25.00",
12 "dd_used": "5.00"
13 }
14 }
15 ],
16 "pagination": {
17 "current_page": 1,
18 "total": 342
19 }
20 }

Code Examples

cURL
1 curl 'https://offersinc.ca/api/v1/transactions?per_page=50' -H 'X-API-Key: mk_key'
POST /transactions Step 2: Charge

STEP 2: Charge customer DD credits and create transaction record

Request Body

Parameter Type Required Description
customer_code string Required No description provided
offer_id integer Required No description provided
total_amount number Required No description provided
dd_credits_to_use number Required No description provided
discount_amount number Required No description provided
cash_paid number Optional No description provided
reference_number string Optional No description provided

Responses

201 Transaction created

JSON Response
1 {
2 "success": true,
3 "data": {
4 "id": 789,
5 "reference_number": "ORDER-12345",
6 "amounts": {
7 "dd_used": "5.00",
8 "cash_paid": "20.00"
9 },
10 "created_at": "2025-10-13T00:15:00Z"
11 }
12 }

400 Insufficient balance

JSON Response
1 {
2 "success": false,
3 "error": "insufficient_balance",
4 "message": "Customer does not have sufficient DD credits"
5 }

Code Examples

PHP
1 <?php
2 $ch = curl_init('https://offersinc.ca/api/v1/transactions');
3 curl_setopt($ch, CURLOPT_POST, true);
4 curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
5 'customer_code' => '123456',
6 'offer_id' => 42,
7 'total_amount' => 25.00,
8 'dd_credits_to_use' => 5.00,
9 'discount_amount' => 5.00,
10 'cash_paid' => 20.00,
11 'reference_number' => 'ORD-' . time()
12 ]));
13 curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: mk_key', 'Content-Type: application/json']);
14 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
15 $response = json_decode(curl_exec($ch), true);
16 if ($response['success']) {
17 echo "Transaction ID: {$response['data']['id']}\n";
18 }
cURL
1 curl -X POST 'https://offersinc.ca/api/v1/transactions' \
2 -H 'X-API-Key: mk_key' \
3 -H 'Content-Type: application/json' \
4 -d '{
5 "customer_code": "123456",
6 "offer_id": 42,
7 "total_amount": 25.00,
8 "dd_credits_to_use": 5.00,
9 "discount_amount": 5.00,
10 "cash_paid": 20.00
11 }'
GET /pos/employees

Retrieve all employees for your merchant account with powerful filtering. Manage your team, track active staff, and organize by role. Essential for building custom POS systems and employee management interfaces.

Query Parameters

Parameter Type Required Description
active_only boolean Optional Filter to active employees only (true/false)
managers_only boolean Optional Filter to managers only (true/false)
include_deleted boolean Optional Include deactivated employees (true/false)

Responses

200 Successfully retrieved employees

JSON Response
1 {
2 "success": true,
3 "data": [
4 {
5 "id": 1,
6 "name": "John Doe",
7 "is_manager": false,
8 "is_active": true,
9 "last_login_at": "2025-10-13T01:30:00Z",
10 "created_at": "2025-01-15T10:00:00Z",
11 "deleted_at": null
12 }
13 ]
14 }

Code Examples

PHP
1 <?php
2 $ch = curl_init('https://offersinc.ca/api/v1/pos/employees?active_only=true');
3 curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: mk_key']);
4 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
5 $employees = json_decode(curl_exec($ch), true);
cURL
1 curl 'https://offersinc.ca/api/v1/pos/employees?active_only=true' \
2 -H 'X-API-Key: mk_key'
POST /pos/employees

Add a new employee to your team with PIN-based authentication. Assign manager role and set initial active status. PIN must be unique within your merchant account.

Request Body

Parameter Type Required Description
name string Required No description provided
pin_code string Required No description provided
is_manager boolean Optional No description provided
is_active boolean Optional No description provided

Responses

201 Employee created

JSON Response
1 {
2 "success": true,
3 "data": {
4 "id": 1,
5 "name": "John Doe",
6 "is_manager": false,
7 "is_active": true
8 },
9 "message": "Employee created successfully"
10 }

422 Validation error or duplicate PIN

JSON Response
1 {
2 "success": false,
3 "error": "duplicate_pin",
4 "message": "PIN code already in use by another employee"
5 }

Code Examples

PHP
1 <?php
2 $ch = curl_init('https://offersinc.ca/api/v1/pos/employees');
3 curl_setopt($ch, CURLOPT_POST, true);
4 curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['name' => 'John Doe', 'pin_code' => '1234']));
5 curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: mk_key', 'Content-Type: application/json']);
6 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
7 $result = json_decode(curl_exec($ch), true);
cURL
1 curl -X POST 'https://offersinc.ca/api/v1/pos/employees' \
2 -H 'X-API-Key: mk_key' \
3 -d '{"name": "John Doe", "pin_code": "1234"}'