Zapier API Reference

Technical documentation for the SharpDuel Zapier integration API.

Base URL

https://api.sharpduel.com/api/v1/zapier

Authentication

All API requests require authentication via API key in the header:

X-Zapier-API-Key: zap_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API Key Details

• Generate keys from your SharpDuel dashboard (Integrations > Zapier)
• Keys are prefixed with zap_
• Each key is tied to a specific store
• Keys are hashed before storage - save it when generated

Rate Limiting

Limit:100 requests/minute

Scope:Per API key

Response headers:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Endpoints

GET/auth/test

Verify API key and get store information

Response:

{
  "success": true,
  "message": "Authentication successful",
  "store_id": "64abc123def456789012345",
  "store_name": "Premium Picks"
}

POST/hooks

Subscribe a webhook URL to receive events

Request Body:

{
  "hookUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
  "event": "new_subscription"
}

Response:

{
  "success": true,
  "id": "a1b2c3d4e5f6789012345678"
}

DELETE/hooks/:hookId

Unsubscribe a webhook

Response:

{
  "success": true,
  "message": "Webhook unsubscribed successfully"
}

GET/events/:eventType

Get recent events for testing/polling

Response:

[
  {
    "id": "evt_abc123def456",
    "event_name": "new_subscription",
    "timestamp": "2025-01-15T10:30:00Z",
    "store": {
      "id": "64abc123def456789012345",
      "name": "Premium Picks",
      "slug": "premium-picks"
    },
    "customer": {
      "id": "cust_xyz789",
      "email": "[email protected]",
      "name": "John Doe"
    },
    "subscription": {
      "id": "sub_123456789",
      "packageName": "Pro Package",
      "amount": 4999,
      "currency": "usd"
    }
  }
]

Event Types

Subscription Events

new_subscriptionCustomer subscribes to a package

subscription_renewedRecurring payment succeeds

subscription_cancelledSubscription is fully cancelled

pending_cancellationSubscription scheduled for cancellation at period end

payment_failedPayment attempt fails

Customer Events

customer_createdNew customer record created

refund_issuedRefund processed for a subscription

coupon_redeemedCoupon/discount applied to subscription

Review Events

review_submittedCustomer submits a review

review_approvedAdmin approves a review

Affiliate Events

affiliate_commission_earnedAffiliate earns commission from referral

affiliate_payout_processedAffiliate payout is approved

Package Events

package_createdNew package created in store

Webhook Payload Examples

When events occur, SharpDuel sends a POST request to registered webhook URLs with the following payload structure:

`new_subscription`

{
  "id": "evt_abc123",
  "event_name": "new_subscription",
  "timestamp": "2025-01-15T10:30:00Z",
  "store": {
    "id": "64abc123def456789012345",
    "name": "Premium Picks",
    "slug": "premium-picks"
  },
  "customer": {
    "id": "cust_xyz789",
    "email": "[email protected]",
    "name": "John Doe"
  },
  "subscription": {
    "id": "sub_stripe_id",
    "packageName": "Pro Package",
    "amount": 4999,
    "currency": "usd",
    "status": "active",
    "interval": "month",
    "renewalCount": 1
  }
}

`subscription_cancelled`

{
  "id": "evt_abc123",
  "event_name": "subscription_cancelled",
  "timestamp": "2025-01-15T10:30:00Z",
  "store": { ... },
  "customer": {
    "id": "cust_xyz789",
    "email": "[email protected]",
    "name": "John Doe"
  },
  "subscription": {
    "id": "sub_stripe_id",
    "packageName": "Pro Package",
    "cancelledAt": "2025-01-15T10:30:00Z"
  }
}

`affiliate_commission_earned`

{
  "id": "evt_abc123",
  "event_name": "affiliate_commission_earned",
  "timestamp": "2025-01-15T10:30:00Z",
  "store": { ... },
  "affiliate": {
    "id": "aff_mongodb_id",
    "email": "[email protected]",
    "name": "Jane Smith"
  },
  "commission": {
    "amount": 1000,
    "currency": "usd",
    "percentage": 20,
    "referredCustomer": "[email protected]",
    "packageName": "Pro Package",
    "subscriptionId": "sub_stripe_id"
  }
}

Important Notes

• All monetary amounts are in cents (e.g., 4999 = $49.99)
• All timestamps are in ISO 8601 format with UTC timezone
• IDs prefixed with sub_ are Stripe subscription IDs
• IDs without prefix are MongoDB ObjectIds

Error Codes

Status	Code	Description
400	`missing_fields`	Required fields not provided
400	`invalid_webhook_url`	Webhook URL not from Zapier
401	`invalid_api_key`	API key is invalid or expired
401	`missing_api_key`	No API key provided
403	`integration_disabled`	Zapier integration is disabled
404	`webhook_not_found`	Webhook subscription not found
429	`rate_limit_exceeded`	Too many requests
500	`internal_error`	Server error

← Back to Zapier Help Need help? Contact Support