Givvv API
One API call to accept a donation. We handle payment processing, donor management, receipting, recurring subscriptions, and reporting. You build the experience.
The Givvv API uses REST conventions, returns JSON responses, authenticates via API keys, and processes payments through Stripe Connect. All endpoints are scoped to your organization.
Quick start
https://app.givvv.comcurl https://app.givvv.com/api/v1/donations \
-H "Authorization: Bearer gvvv_your_key" \
-H "Content-Type: application/json" \
-d '{"amount": 50, "donor_email": "[email protected]"}'Authentication
The Givvv API uses API keys to authenticate requests. Include your key in theAuthorizationheader as a Bearer token.
Keys are created in your Givvv dashboard under Developers → API Keys. Each key can be scoped to specific permissions and rate-limited independently.
Keep your API keys secret
Never expose keys in client-side code, public repos, or browser requests. Use them only from your server.
Authorization: Bearer gvvv_abc123def456...Errors
Givvv uses conventional HTTP status codes. All error responses include a type field to help you handle errors programmatically.
401authentication_errorThe API key is missing, invalid, or expired.
403authorization_errorThe API key lacks the required scope for this action.
400validation_errorThe request body failed schema validation.
404not_foundThe requested resource does not exist.
429rate_limit_errorToo many requests. Back off and retry.
500api_errorAn internal error occurred on our side.
{
"error": {
"message": "Invalid API key",
"type": "authentication_error"
}
}Pagination
All list endpoints return paginated results. Use limit (max 100) and offset query parameters to navigate through results.
Pagination fields
totalTotal number of matching records
limitNumber of records returned in this page
offsetNumber of records skipped
has_moreWhether more records exist beyond this page
GET /api/v1/donations?limit=20&offset=40
{
"data": [ ... ],
"pagination": {
"total": 142,
"limit": 20,
"offset": 40,
"has_more": true
}
}Rate Limits
API requests are rate limited per key. The default limit is 60 requests per minute. Rate limit status is returned in response headers.
Response headers
X-RateLimit-LimitMaximum requests allowed in the window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp when the window resets
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1711540800/api/v1/donationsCreate a donation
Creates a new donation and returns a Stripe client secret for completing the payment on your frontend. Givvv handles donor deduplication, Stripe Connect routing, fee calculation, and receipt generation automatically.
Body parameters
amountDonation amount in dollars (1 — 999,999)
donor_emailDonor's email address
donor_nameDonor's full name
donor_phoneDonor's phone number
designationFund designation. Defaults to "General Fund"
notesOptional note from the donor
recurringWhether this is a recurring donation. Defaults to false
recurring_intervalOne of: weekly, bi-weekly, 1st-15th, monthly, quarterly, yearly
currencyThree-letter currency code. Defaults to NZD
idempotency_keyUnique key to prevent duplicate donations
metadataArbitrary key-value pairs (string values only)
donations:writecurl -X POST https://app.givvv.com/api/v1/donations \
-H "Authorization: Bearer gvvv_your_key" \
-H "Content-Type: application/json" \
-d '{
"amount": 50,
"donor_email": "[email protected]",
"donor_name": "Jane Doe",
"designation": "General Fund"
}'{
"data": {
"client_secret": "pi_3abc...secret_xyz",
"stripe_account_id": "acct_1abc...",
"payment_methods": {
"card": true
},
"currency": "NZD"
}
}/api/v1/donationsList donations
Returns a paginated list of donations for your organization, ordered by most recent first.
Query parameters
limitNumber of results (1-100, default 50)
offsetNumber of results to skip (default 0)
statusFilter by status: succeeded, pending, failed
sinceISO 8601 date — only return donations after this date
donations:readcurl "https://app.givvv.com/api/v1/donations?status=succeeded&limit=20" \
-H "Authorization: Bearer gvvv_your_key"{
"data": [
{
"id": "d4e5f6a7-...",
"amount": 50.00,
"currency": "NZD",
"status": "succeeded",
"designation": "General Fund",
"recurring": false,
"donor_id": "a1b2c3d4-...",
"created_at": "2026-03-27T10:30:00Z"
}
],
"pagination": {
"total": 142,
"limit": 50,
"offset": 0,
"has_more": true
}
}/api/v1/donations/:idGet a donation
Retrieves the full details of a single donation, including notes, fee information, form data, and refund status.
donations:readcurl "https://app.givvv.com/api/v1/donations/d4e5f6a7-..." \
-H "Authorization: Bearer gvvv_your_key"{
"data": {
"id": "d4e5f6a7-...",
"amount": 50.00,
"currency": "NZD",
"status": "succeeded",
"designation": "General Fund",
"notes": "Keep up the great work!",
"recurring": false,
"donor_id": "a1b2c3d4-...",
"fee_amount": 1.75,
"fee_covered": true,
"form_data": { ... },
"refunded_at": null,
"refund_amount": null,
"created_at": "2026-03-27T10:30:00Z",
"updated_at": "2026-03-27T10:31:00Z"
}
}/api/v1/donations/:id/receiptGet a receipt
Returns structured receipt data for a succeeded donation, including donor info, organization tax details, and payment breakdown. Use this to render receipts in your own format.
donations:readcurl "https://app.givvv.com/api/v1/donations/d4e5f6a7-.../receipt" \
-H "Authorization: Bearer gvvv_your_key"{
"data": {
"receipt_id": "d4e5f6a7-...",
"donation_date": "2026-03-27T10:30:00Z",
"amount": 50.00,
"currency": "NZD",
"designation": "General Fund",
"fee_amount": 1.75,
"fee_covered": true,
"total_charged": 51.75,
"recurring": false,
"card_last4": "4242",
"card_brand": "visa",
"donor": {
"name": "Jane Doe",
"email": "[email protected]"
},
"organization": {
"name": "My Church",
"address": "123 Main St",
"country": "NZ",
"charities_registration_number": "CC12345"
}
}
}/api/v1/donations/:id/refundRefund a donation
Process a full or partial refund through Stripe. Omit amount for a full refund. Partial refunds can be issued multiple times up to the original amount.
Body parameters
amountPartial refund amount in dollars. Omit for full refund.
reasonOne of: duplicate, fraudulent, requested_by_customer (default)
donations:writecurl -X POST "https://app.givvv.com/api/v1/donations/d4e5f6a7-.../refund" \
-H "Authorization: Bearer gvvv_your_key" \
-H "Content-Type: application/json" \
-d '{"amount": 25.00, "reason": "requested_by_customer"}'{
"data": {
"refund_id": "re_abc123...",
"amount": 25.00,
"status": "succeeded",
"is_full_refund": false,
"remaining_balance": 25.00
}
}/api/v1/donorsCreate a donor
Creates a new donor or returns the existing one if a donor with that email already exists. Deduplicates by email automatically. Use this to register donors before they donate — for pledges, imports, or event registration.
Body parameters
emailDonor's email address (used for deduplication)
nameDonor's full name
phoneDonor's phone number
donors:readcurl -X POST https://app.givvv.com/api/v1/donors \
-H "Authorization: Bearer gvvv_your_key" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"name": "Jane Doe"
}'{
"data": {
"id": "a1b2c3d4-...",
"name_search": "jane doe",
"status": "active",
"giving_status": null,
"total_given": 0,
"donation_count": 0,
"created_at": "2026-03-27T..."
},
"created": true
}/api/v1/donorsList donors
Returns a paginated list of donors. Use the search parameter to filter by name.
Query parameters
limitNumber of results (1-100, default 50)
offsetNumber of results to skip (default 0)
searchSearch donors by name
donors:readcurl "https://app.givvv.com/api/v1/donors?search=jane" \
-H "Authorization: Bearer gvvv_your_key"{
"data": [
{
"id": "a1b2c3d4-...",
"name_search": "jane doe",
"status": "active",
"giving_status": "active",
"total_given": 1250.00,
"donation_count": 12,
"first_donation_at": "2025-06-15T...",
"last_donation_at": "2026-03-20T..."
}
],
"pagination": { ... }
}/api/v1/donors/:idGet a donor
Retrieves a single donor with their 50 most recent donations included.
donors:readcurl "https://app.givvv.com/api/v1/donors/a1b2c3d4-..." \
-H "Authorization: Bearer gvvv_your_key"{
"data": {
"id": "a1b2c3d4-...",
"name_search": "jane doe",
"status": "active",
"giving_status": "active",
"total_given": 1250.00,
"donation_count": 12,
"recent_donations": [
{
"id": "d4e5f6a7-...",
"amount": 50.00,
"status": "succeeded",
"designation": "General Fund",
"created_at": "2026-03-27T..."
}
]
}
}/api/v1/donors/:idUpdate a donor
Updates a donor's name, phone, or status. Only the fields you include will be changed.
Body parameters
nameDonor's full name
phoneDonor's phone number
statusOne of: active, inactive
donors:readcurl -X PATCH "https://app.givvv.com/api/v1/donors/a1b2c3d4-..." \
-H "Authorization: Bearer gvvv_your_key" \
-H "Content-Type: application/json" \
-d '{"name": "Jane Smith"}'{
"data": {
"id": "a1b2c3d4-...",
"name_search": "jane smith",
"status": "active",
"giving_status": "active",
"total_given": 1250.00,
"donation_count": 12,
"created_at": "2025-06-15T..."
}
}/api/v1/campaignsCreate a campaign
Creates a new fundraising campaign. Campaigns can have goals, date ranges, suggested amounts, and customizable display settings. Starts in draft status by default — set status to 'active' to publish immediately.
Body parameters
nameCampaign name (max 200 chars)
descriptionFull campaign description (max 5000 chars)
goal_amountFundraising goal in dollars
start_dateISO 8601 start date
end_dateISO 8601 end date
suggested_amountsPreset donation amounts (max 10)
theme_colorHex color code (e.g. #3b82f6)
statusOne of: draft (default), active
show_goalShow goal amount publicly (default true)
show_progress_barShow progress bar (default true)
campaigns:writecurl -X POST https://app.givvv.com/api/v1/campaigns \
-H "Authorization: Bearer gvvv_your_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Building Fund 2026",
"goal_amount": 50000,
"suggested_amounts": [50, 100, 250, 500],
"status": "active"
}'{
"data": {
"id": "camp_abc123-...",
"name": "Building Fund 2026",
"slug": "building-fund-2026",
"status": "active",
"goal_amount": 50000,
"current_amount": 0,
"donor_count": 0,
"created_at": "2026-03-27T..."
}
}/api/v1/campaignsList campaigns
Returns a paginated list of campaigns. Filter by status to find active, draft, or completed campaigns.
Query parameters
limitNumber of results (1-100, default 50)
offsetNumber of results to skip
statusFilter: draft, active, paused, completed
campaigns:readcurl "https://app.givvv.com/api/v1/campaigns?status=active" \
-H "Authorization: Bearer gvvv_your_key"{
"data": [
{
"id": "camp_abc123-...",
"name": "Building Fund 2026",
"slug": "building-fund-2026",
"status": "active",
"goal_amount": 50000,
"current_amount": 12500,
"donor_count": 45
}
],
"pagination": { ... }
}/api/v1/campaigns/:idGet a campaign
Retrieves full details of a single campaign including all configuration and current progress.
campaigns:readcurl "https://app.givvv.com/api/v1/campaigns/camp_abc123-..." \
-H "Authorization: Bearer gvvv_your_key"/api/v1/campaigns/:idUpdate a campaign
Update campaign details, goal, dates, or status. Change status to 'active' to publish a draft, or 'completed' to end a campaign.
Body parameters
nameCampaign name
goal_amountUpdated goal amount
statusOne of: draft, active, paused, completed
end_dateISO 8601 end date
campaigns:writecurl -X PATCH "https://app.givvv.com/api/v1/campaigns/camp_abc123-..." \
-H "Authorization: Bearer gvvv_your_key" \
-H "Content-Type: application/json" \
-d '{"goal_amount": 75000}'/api/v1/campaigns/:id/analyticsCampaign analytics
Returns detailed metrics for a campaign: total raised, unique donors, average gift, daily donation trends, and goal progress percentage.
campaigns:readcurl "https://app.givvv.com/api/v1/campaigns/camp_abc123-.../analytics" \
-H "Authorization: Bearer gvvv_your_key"{
"data": {
"campaign": {
"id": "camp_abc123-...",
"name": "Building Fund 2026",
"status": "active",
"goal_amount": 50000
},
"metrics": {
"total_raised": 12500.00,
"total_donations": 45,
"unique_donors": 32,
"average_donation": 277.78,
"largest_donation": 2500,
"recurring_count": 8,
"fees_covered": 125.50,
"goal_progress": 25.0
},
"donations_over_time": [
{ "date": "2026-03-25", "amount": 1500, "count": 5 },
{ "date": "2026-03-26", "amount": 2200, "count": 8 }
]
}
}/api/v1/designationsList designations
Returns all fund designations that have been used in your donations. Useful for populating dropdown menus in your custom donation forms.
donations:readcurl "https://app.givvv.com/api/v1/designations" \
-H "Authorization: Bearer gvvv_your_key"{
"data": [
"General Fund",
"Building Fund",
"Missions"
]
}/api/v1/webhooksCreate a webhook
Registers a webhook endpoint. Givvv will POST event payloads to your URL with an HMAC signature for verification. The signing secret is only returned on creation.
Body parameters
urlHTTPS endpoint URL to receive events
eventsArray of event types to subscribe to
integrations:writecurl -X POST https://app.givvv.com/api/v1/webhooks \
-H "Authorization: Bearer gvvv_your_key" \
-H "Content-Type: application/json" \
-d '{
"url": "https://yoursite.com/webhooks/givvv",
"events": ["donation.succeeded", "donor.created"]
}'{
"data": {
"id": "wh_abc123...",
"url": "https://yoursite.com/webhooks/givvv",
"events": ["donation.succeeded", "donor.created"],
"is_active": true,
"secret": "whsec_a1b2c3d4e5f6...",
"created_at": "2026-03-27T..."
}
}/api/v1/webhooksList webhooks
Returns all registered webhook endpoints for your organization.
integrations:readcurl "https://app.givvv.com/api/v1/webhooks" \
-H "Authorization: Bearer gvvv_your_key"{
"data": [
{
"id": "wh_abc123...",
"url": "https://yoursite.com/webhooks/givvv",
"events": ["donation.succeeded"],
"is_active": true,
"created_at": "2026-03-27T..."
}
]
}/api/v1/webhooks/:idDelete a webhook
Permanently removes a webhook endpoint. Events will no longer be delivered to this URL.
integrations:writecurl -X DELETE "https://app.givvv.com/api/v1/webhooks/wh_abc123..." \
-H "Authorization: Bearer gvvv_your_key"{
"data": {
"deleted": true
}
}Webhook Event Types
When you register a webhook, Givvv sends a POST request to your URL whenever a subscribed event occurs. Each delivery includes an X-Givvv-Signature header for HMAC verification using your webhook secret.
donation.succeededA donation payment completed successfully.
donation.failedA donation payment attempt failed.
donation.refundedA donation was fully or partially refunded.
donor.createdA new donor record was created in your organization.
donor.updatedA donor's information was updated.
subscription.createdA recurring donation schedule was set up.
subscription.cancelledA recurring donation was cancelled by the donor or admin.
subscription.payment_failedA scheduled recurring payment failed to process.
{
"event": "donation.succeeded",
"created_at": "2026-03-27T10:31:00Z",
"data": {
"id": "d4e5f6a7-...",
"amount": 50.00,
"currency": "NZD",
"status": "succeeded",
"donor_id": "a1b2c3d4-...",
"designation": "General Fund"
}
}