Birthday.Gold Partner API

Integrate birthday rewards directly into your business systems

Overview Authentication User Management Campaigns Rewards Analytics Webhooks SDKs

API Overview

Build powerful integrations with Birthday.Gold's Partner API

User Management

Enroll members, manage profiles, and track birthday celebrations seamlessly.

Coming Soon

Campaign Management

Create, schedule, and monitor marketing campaigns targeted at birthday celebrants.

Coming Soon

Reward Programs

Design and deploy custom birthday reward programs with flexible redemption options.

Coming Soon

Analytics & Reporting

Access detailed insights on redemptions, engagement, and ROI metrics.

Coming Soon
API Access

The Birthday.Gold Partner API is currently under development. Join our partner program to be notified when API access becomes available.

Authentication

Secure API access with OAuth 2.0 and API keys

Authentication Methods

API Key Authentication

For server-to-server integrations, use your API key in the request header:

Authorization: Bearer YOUR_API_KEY

OAuth 2.0

For user-authorized actions, implement OAuth 2.0 flow:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=YOUR_REDIRECT_URI

User Management API

Manage Birthday.Gold members from your platform

POST /api/v1/users/enroll

Enroll a new user in Birthday.Gold

Request Body
{
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "birthday": "1990-06-15",
  "phone": "+1234567890",
  "source": "partner_enrollment",
  "partner_user_id": "USR123456"
}
Response
{
  "success": true,
  "user": {
    "id": "bguser_1234567890",
    "email": "user@example.com",
    "status": "active",
    "enrollment_date": "2025-07-06T10:30:00Z"
  }
}
GET /api/v1/users/{user_id}

Retrieve user details and enrollment status

PUT /api/v1/users/{user_id}

Update user profile information

DELETE /api/v1/users/{user_id}

Remove user from Birthday.Gold (soft delete)

Campaign Management API

Create and manage targeted birthday marketing campaigns

POST /api/v1/campaigns

Create a new birthday campaign

Request Body
{
  "name": "Summer Birthday Special",
  "description": "20% off for July birthdays",
  "start_date": "2025-07-01",
  "end_date": "2025-07-31",
  "target_criteria": {
    "birth_month": 7,
    "age_range": {
      "min": 18,
      "max": 65
    }
  },
  "reward": {
    "type": "percentage_discount",
    "value": 20,
    "applicable_to": "entire_purchase"
  }
}
GET /api/v1/campaigns

List all campaigns with filtering options

Query Parameters
Parameter Type Description
status string Filter by campaign status (active, scheduled, completed)
start_date date Filter campaigns starting after this date
limit integer Number of results per page (default: 20)
GET /api/v1/campaigns/{campaign_id}/analytics

Get detailed analytics for a specific campaign

Rewards Program API

Configure and manage birthday reward offerings

POST /api/v1/rewards

Create a new reward program

Request Body
{
  "name": "Birthday Free Dessert",
  "type": "free_item",
  "description": "Complimentary dessert during birthday month",
  "terms": [
    "Valid during birthday month only",
    "One redemption per member",
    "Dine-in only"
  ],
  "redemption_method": "qr_code",
  "locations": ["all"]
}
POST /api/v1/rewards/{reward_id}/validate

Validate a reward redemption attempt

POST /api/v1/rewards/{reward_id}/redeem

Process a reward redemption

Analytics & Reporting API

Access comprehensive data on your birthday programs

GET /api/v1/analytics/overview

Get high-level metrics for your account

Response Example
{
  "period": "last_30_days",
  "metrics": {
    "total_members": 1523,
    "new_enrollments": 87,
    "redemptions": 342,
    "redemption_rate": 0.225,
    "average_transaction_value": 45.67,
    "revenue_impact": 15632.14
  }
}
GET /api/v1/analytics/redemptions

Detailed redemption analytics with filtering

GET /api/v1/analytics/demographics

Member demographic insights

Webhooks

Receive real-time notifications for important events

Available Webhook Events

user.enrolled

Triggered when a new user successfully enrolls

{
  "event": "user.enrolled",
  "timestamp": "2025-07-06T10:30:00Z",
  "data": {
    "user_id": "bguser_1234567890",
    "email": "user@example.com",
    "enrollment_source": "partner_api"
  }
}

reward.redeemed

Triggered when a member redeems a reward

campaign.completed

Triggered when a campaign ends

Webhook Configuration

POST /api/v1/webhooks

Register a new webhook endpoint

SDKs & Libraries

Get started quickly with our official SDKs

PHP SDK

Native PHP library with full API coverage

composer require birthdaygold/partner-sdk-php
Coming Soon

JavaScript SDK

Browser and Node.js compatible library

npm install @birthdaygold/partner-sdk
Coming Soon

Python SDK

Python library with async support

pip install birthdaygold-partner
Coming Soon

Ready to Integrate?

Join our partner program to get early access to the API

Become a Partner
Back to Partner Program