REST API

Overview
The Subscription Events API allows external systems to send subscription-related events to AttributionX via a server-to-server REST API endpoint. This is designed for platforms that process subscriptions and need to track subscription status changes in the attribution system.

Endpoint

POST https://myxznsjxiabywzqxedih.supabase.co/functions/v1/subscription-events

Authentication

Authentication is performed using an API key that must be included in the request body. The API key is a UUID string that identifies your registered host.

Request Format

Headers

Content-Type: application/json

Request Body

Event Types

• payment_received - A payment has been received for the subscription

• subscription_cancelled - The subscription has been cancelled

Subscription Status Values

Status

Description

Event Processing

1. Event is stored in the subscription_events table (event sourcing pattern)

2. Background worker processes the event and:

   • Finds the previously created subscription

   • Updates the subscription data in the subscriptions table

   • Updates the associated deal/transaction status

Examples

Payment Received (Active)

curl -X POST https://myxznsjxiabywzqxedih.supabase.co/functions/v1/subscription-events \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "123456789-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "eventType": "payment_received",
    "status": "active",
    "amount": 99.99,
    "currency": "USD",
    "subscriptionId": "sub_12345"
  }'

Payment Received (Trial)

curl -X POST https://myxznsjxiabywzqxedih.supabase.co/functions/v1/subscription-events \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "123456789-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "eventType": "payment_received",
    "status": "in_trial",
    "amount": 0,
    "currency": "USD",
    "subscriptionId": "sub_12345"
  }'

Subscription Cancelled

curl -X POST https://myxznsjxiabywzqxedih.supabase.co/functions/v1/subscription-events \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "123456789-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "eventType": "subscription_cancelled",
    "status": "cancelled",
    "currency": "USD",
    "subscriptionId": "sub_12345"
  }'

JavaScript/TypeScript Example

const response = await fetch('https://myxznsjxiabywzqxedih.supabase.co/functions/v1/subscription-events', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    apiKey: '123456789-e29b-41d4-a716-446655440000',
    email: 'user@example.com',
    eventType: 'payment_received',
    status: 'active',
    amount: 99.99,
    currency: 'USD',
    subscriptionId: 'sub_12345'
  })
});

if (response.status === 201) {
  console.log('Event recorded successfully');
}

Response Codes

Code

Description

Error Responses

Missing required field:

{
  "error": "Missing required field: email"
}

Invalid event type:

{
  "error": "Invalid eventType. Allowed values: payment_received, subscription_cancelled"
}

Invalid status:

{
  "error": "Invalid status. Allowed values: future, in_trial, active, non_renewing, paused, cancelled, transferred"
}

Authentication failed:

{
  "error": "No apiKey received"
}

{
  "error": "Invalid apiKey received"
}

{
  "error": "The apiKey is not registered."
}