API Reference

enterprise+ plan

Integrate Giveawayz with your existing systems using the REST API. Programmatically query competitions, orders, and platform statistics with secure, key-based authentication.

Authentication

All API requests must include a valid API key in the Authorization header using the Bearer token scheme.

Authorization: Bearer gw_live_abc123def456...

API keys use the gw_live_ prefix and are SHA-256 hashed before storage. This means the full key is only shown once when you generate it -- store it securely, as it cannot be retrieved later.

Managing API Keys

Base URL

All API endpoints are relative to your platform's base URL:

https://your-subdomain.giveawayz.io/api/v1/

If you have a custom domain configured, you can also use:

https://your-custom-domain.com/api/v1/

Endpoints

GET /competitions

Returns a paginated list of all competitions for your organisation.

Query parameters:

| Parameter | Type | Description | |-----------|------|-------------| | page | number | Page number (default: 1) | | limit | number | Results per page (default: 20, max: 100) | | status | string | Filter by status: upcoming, active, completed, paused |

Example request:

curl -X GET "https://your-subdomain.giveawayz.io/api/v1/competitions?status=active&limit=10" \
  -H "Authorization: Bearer gw_live_abc123def456..."

Example response:

{
  "data": [
    {
      "id": "comp_8f3k2j1m",
      "title": "Win a PS5 Pro Bundle",
      "status": "active",
      "ticketPrice": 2.99,
      "maxTickets": 500,
      "ticketsSold": 312,
      "startDate": "2026-02-15T09:00:00Z",
      "endDate": "2026-03-15T23:59:00Z",
      "drawType": "scheduled",
      "createdAt": "2026-02-10T14:30:00Z"
    },
    {
      "id": "comp_9a4b5c6d",
      "title": "£1,000 Cash Giveaway",
      "status": "active",
      "ticketPrice": 1.50,
      "maxTickets": 1000,
      "ticketsSold": 847,
      "startDate": "2026-02-20T12:00:00Z",
      "endDate": "2026-03-20T12:00:00Z",
      "drawType": "flash",
      "createdAt": "2026-02-18T09:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2,
    "totalPages": 1
  }
}

GET /competitions/:id

Returns full details for a single competition.

Example request:

curl -X GET "https://your-subdomain.giveawayz.io/api/v1/competitions/comp_8f3k2j1m" \
  -H "Authorization: Bearer gw_live_abc123def456..."

Example response:

{
  "data": {
    "id": "comp_8f3k2j1m",
    "title": "Win a PS5 Pro Bundle",
    "description": "Enter for your chance to win a brand new PS5 Pro with two controllers and three games.",
    "status": "active",
    "ticketPrice": 2.99,
    "maxTickets": 500,
    "ticketsSold": 312,
    "maxPerCustomer": 10,
    "startDate": "2026-02-15T09:00:00Z",
    "endDate": "2026-03-15T23:59:00Z",
    "drawType": "scheduled",
    "drawDate": "2026-03-16T18:00:00Z",
    "category": "Electronics",
    "revenue": 933.88,
    "createdAt": "2026-02-10T14:30:00Z",
    "updatedAt": "2026-02-28T11:00:00Z"
  }
}

GET /orders

Returns a paginated list of orders, with optional filters.

Query parameters:

| Parameter | Type | Description | |-----------|------|-------------| | page | number | Page number (default: 1) | | limit | number | Results per page (default: 20, max: 100) | | competitionId | string | Filter by competition ID | | status | string | Filter by status: paid, refunded, pending | | from | string | Start date (ISO 8601) | | to | string | End date (ISO 8601) |

Example request:

curl -X GET "https://your-subdomain.giveawayz.io/api/v1/orders?competitionId=comp_8f3k2j1m&status=paid&limit=5" \
  -H "Authorization: Bearer gw_live_abc123def456..."

Example response:

{
  "data": [
    {
      "id": "ord_1a2b3c4d",
      "competitionId": "comp_8f3k2j1m",
      "customerEmail": "jane@example.com",
      "ticketCount": 3,
      "amount": 8.97,
      "discountCode": null,
      "discountAmount": 0,
      "status": "paid",
      "createdAt": "2026-02-25T16:42:00Z"
    },
    {
      "id": "ord_5e6f7g8h",
      "competitionId": "comp_8f3k2j1m",
      "customerEmail": "tom@example.com",
      "ticketCount": 5,
      "amount": 11.96,
      "discountCode": "LAUNCH20",
      "discountAmount": 2.99,
      "status": "paid",
      "createdAt": "2026-02-25T14:18:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 5,
    "total": 312,
    "totalPages": 63
  }
}

GET /stats

Returns platform-level statistics for your organisation.

Example request:

curl -X GET "https://your-subdomain.giveawayz.io/api/v1/stats" \
  -H "Authorization: Bearer gw_live_abc123def456..."

Example response:

{
  "data": {
    "totalRevenue": 14523.50,
    "totalTicketsSold": 6841,
    "totalEntrants": 2103,
    "activeCompetitions": 3,
    "completedCompetitions": 12,
    "averageTicketsPerCompetition": 456
  }
}

Error Codes

All error responses follow a consistent format:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key."
  }
}

| HTTP Status | Code | Description | |-------------|------|-------------| | 401 | UNAUTHORIZED | Missing or invalid API key. Check that your key is correct and has not been revoked. | | 403 | FORBIDDEN | The API key does not have permission to access this resource. | | 404 | NOT_FOUND | The requested resource does not exist. Check the ID in your request. | | 429 | RATE_LIMITED | You have exceeded the rate limit. Wait before retrying. | | 500 | SERVER_ERROR | An unexpected error occurred. If this persists, contact support. |

Rate Limiting

API requests are limited to 100 requests per minute per key. If you exceed this limit, you will receive a 429 response with a Retry-After header indicating how many seconds to wait.

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Related

• Webhooks — Receive real-time event notifications instead of polling the API
• Custom Domains — Use your own domain as the API base URL
• Team Management — Only Admin role members can manage API keys
• Pricing Plans — API access is available on the Enterprise plan