# Authentication
Source: https://docs.givebutter.com/api-reference/authentication

Securely authenticate API requests using Bearer token authentication with API keys.

The Givebutter API uses **Bearer token authentication** to secure all API requests. All requests must be made over HTTPS.

## Quick Start

Include your API key in the `Authorization` header of every request:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.givebutter.com/v1/campaigns \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript Node.js / JavaScript theme={null}
  const response = await fetch('https://api.givebutter.com/v1/campaigns', {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  });
  ```

  ```python Python theme={null}
  import requests

  headers = {'Authorization': 'Bearer YOUR_API_KEY'}
  response = requests.get('https://api.givebutter.com/v1/campaigns', headers=headers)
  ```

  ```php PHP theme={null}
  $ch = curl_init('https://api.givebutter.com/v1/campaigns');
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer YOUR_API_KEY'
  ]);
  $response = curl_exec($ch);
  ```

  ```ruby Ruby theme={null}
  require 'net/http'

  uri = URI('https://api.givebutter.com/v1/campaigns')
  request = Net::HTTP::Get.new(uri)
  request['Authorization'] = 'Bearer YOUR_API_KEY'

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end
  ```

  ```go Go theme={null}
  client := &http.Client{}
  req, _ := http.NewRequest("GET", "https://api.givebutter.com/v1/campaigns", nil)
  req.Header.Add("Authorization", "Bearer YOUR_API_KEY")

  resp, err := client.Do(req)
  ```

  ```java Java theme={null}
  HttpClient client = HttpClient.newHttpClient();
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.givebutter.com/v1/campaigns"))
      .header("Authorization", "Bearer YOUR_API_KEY")
      .build();

  HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
  ```
</CodeGroup>

## Getting Your API Key

1. Go to **Settings** → **Integrations** → **API Keys** in your [Givebutter Dashboard](https://givebutter.com/dashboard)
2. Click **Create New API Key** and give it a name
3. Copy your API key immediately and store it securely

<Warning>Your API key is shown only once. Never share it or commit it to version control.</Warning>

## Authentication Errors

### 401 Unauthorized

Your API key is missing, invalid, or revoked.

```json theme={null}
{
  "message": "Unauthenticated."
}
```

**Common causes:**

* API key is missing from the request
* API key is incorrect or has typos
* API key has been revoked
* Using `Authorization: YOUR_API_KEY` instead of `Authorization: Bearer YOUR_API_KEY`

### 403 Forbidden

Your API key is valid but lacks permission for this resource.

```json theme={null}
{
  "message": "This action is unauthorized."
}
```

**Common causes:**

* API key has restricted permissions
* Trying to access another organization's data
* Resource has been archived or deleted


# Create a discount code
Source: https://docs.givebutter.com/api-reference/campaign-discount-codes/create-a-discount-code

https://givebutter.com/docs/api.json post /v1/campaigns/{campaign}/discount-codes



# Delete a discount code
Source: https://docs.givebutter.com/api-reference/campaign-discount-codes/delete-a-discount-code

https://givebutter.com/docs/api.json delete /v1/campaigns/{campaign}/discount-codes/{discountCode}



# Get a discount code
Source: https://docs.givebutter.com/api-reference/campaign-discount-codes/get-a-discount-code

https://givebutter.com/docs/api.json get /v1/campaigns/{campaign}/discount-codes/{discountCode}



# List all discount codes
Source: https://docs.givebutter.com/api-reference/campaign-discount-codes/list-all-discount-codes

https://givebutter.com/docs/api.json get /v1/campaigns/{campaign}/discount-codes



# Update a discount code
Source: https://docs.givebutter.com/api-reference/campaign-discount-codes/update-a-discount-code

https://givebutter.com/docs/api.json put /v1/campaigns/{campaign}/discount-codes/{discountCode}



# Delete a campaign member
Source: https://docs.givebutter.com/api-reference/campaign-members/delete-a-campaign-member

https://givebutter.com/docs/api.json delete /v1/campaigns/{campaign}/members/{member}



# Get a campaign member
Source: https://docs.givebutter.com/api-reference/campaign-members/get-a-campaign-member

https://givebutter.com/docs/api.json get /v1/campaigns/{campaign}/members/{member}



# List all campaign members
Source: https://docs.givebutter.com/api-reference/campaign-members/list-all-campaign-members

https://givebutter.com/docs/api.json get /v1/campaigns/{campaign}/members



# Delete a campaign team
Source: https://docs.givebutter.com/api-reference/campaign-teams/delete-a-campaign-team

https://givebutter.com/docs/api.json delete /v1/campaigns/{campaign}/teams/{team}



# Get a campaign team
Source: https://docs.givebutter.com/api-reference/campaign-teams/get-a-campaign-team

https://givebutter.com/docs/api.json get /v1/campaigns/{campaign}/teams/{team}



# List all campaign teams
Source: https://docs.givebutter.com/api-reference/campaign-teams/list-all-campaign-teams

https://givebutter.com/docs/api.json get /v1/campaigns/{campaign}/teams



# Create a campaign ticket
Source: https://docs.givebutter.com/api-reference/campaign-tickets/create-a-campaign-ticket

https://givebutter.com/docs/api.json post /v1/campaigns/{campaign}/items/tickets



# Get a campaign ticket
Source: https://docs.givebutter.com/api-reference/campaign-tickets/get-a-campaign-ticket

https://givebutter.com/docs/api.json get /v1/campaigns/{campaign}/items/tickets/{ticketId}



# List all campaign tickets
Source: https://docs.givebutter.com/api-reference/campaign-tickets/list-all-campaign-tickets

https://givebutter.com/docs/api.json get /v1/campaigns/{campaign}/items/tickets



# Create a campaign
Source: https://docs.givebutter.com/api-reference/campaigns/create-a-campaign

https://givebutter.com/docs/api.json post /v1/campaigns



# Delete a campaign
Source: https://docs.givebutter.com/api-reference/campaigns/delete-a-campaign

https://givebutter.com/docs/api.json delete /v1/campaigns/{campaign}



# Get a campaign
Source: https://docs.givebutter.com/api-reference/campaigns/get-a-campaign

https://givebutter.com/docs/api.json get /v1/campaigns/{campaign}



# List all campaigns
Source: https://docs.givebutter.com/api-reference/campaigns/list-all-campaigns

https://givebutter.com/docs/api.json get /v1/campaigns



# Update a campaign
Source: https://docs.givebutter.com/api-reference/campaigns/update-a-campaign

https://givebutter.com/docs/api.json put /v1/campaigns/{campaign}



# Create a contact activity
Source: https://docs.givebutter.com/api-reference/contact-activities/create-a-contact-activity

https://givebutter.com/docs/api.json post /v1/contacts/{contact}/activities



# Delete a contact activity
Source: https://docs.givebutter.com/api-reference/contact-activities/delete-a-contact-activity

https://givebutter.com/docs/api.json delete /v1/contacts/{contact}/activities/{activity}



# Get a contact activity
Source: https://docs.givebutter.com/api-reference/contact-activities/get-a-contact-activity

https://givebutter.com/docs/api.json get /v1/contacts/{contact}/activities/{activity}



# List all contact activities
Source: https://docs.givebutter.com/api-reference/contact-activities/list-all-contact-activities

https://givebutter.com/docs/api.json get /v1/contacts/{contact}/activities



# Update a contact activity
Source: https://docs.givebutter.com/api-reference/contact-activities/update-a-contact-activity

https://givebutter.com/docs/api.json put /v1/contacts/{contact}/activities/{activity}



# Add tags to a contact
Source: https://docs.givebutter.com/api-reference/contact-tags/add-tags-to-a-contact

https://givebutter.com/docs/api.json post /v1/contacts/{contact}/tags/add



# Remove tags from a contact
Source: https://docs.givebutter.com/api-reference/contact-tags/remove-tags-from-a-contact

https://givebutter.com/docs/api.json post /v1/contacts/{contact}/tags/remove



# Sync tags for a contact
Source: https://docs.givebutter.com/api-reference/contact-tags/sync-tags-for-a-contact

https://givebutter.com/docs/api.json post /v1/contacts/{contact}/tags/sync



# Create a contact
Source: https://docs.givebutter.com/api-reference/contacts/create-a-contact

https://givebutter.com/docs/api.json post /v1/contacts



# Delete a contact
Source: https://docs.givebutter.com/api-reference/contacts/delete-a-contact

https://givebutter.com/docs/api.json delete /v1/contacts/{contact}



# Get a contact
Source: https://docs.givebutter.com/api-reference/contacts/get-a-contact

https://givebutter.com/docs/api.json get /v1/contacts/{contact}



# List all contacts
Source: https://docs.givebutter.com/api-reference/contacts/list-all-contacts

https://givebutter.com/docs/api.json get /v1/contacts



# Restore a contact
Source: https://docs.givebutter.com/api-reference/contacts/restore-a-contact

https://givebutter.com/docs/api.json patch /v1/contacts/{contact}/restore



# Update a contact
Source: https://docs.givebutter.com/api-reference/contacts/update-a-contact

https://givebutter.com/docs/api.json put /v1/contacts/{contact}



# Errors
Source: https://docs.givebutter.com/api-reference/errors

The Givebutter API uses standard HTTP status codes to indicate the success or failure of requests.

## HTTP Status Codes

### Client Error Codes (4xx)

| Code | Name                 | Description                                                                   | Common Causes                                                                    |
| ---- | -------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| 400  | Bad Request          | Malformed request syntax or invalid request parameters.                       | Invalid JSON, missing required parameters, malformed data                        |
| 401  | Unauthorized         | Authentication required. API key missing, invalid, or revoked.                | Missing Authorization header, invalid API key, revoked key                       |
| 403  | Forbidden            | Authentication succeeded, but insufficient permissions for this resource.     | API key lacks permissions, accessing another org's resources                     |
| 404  | Not Found            | Requested resource does not exist or was not found.                           | Invalid resource ID, resource deleted, typo in URL                               |
| 405  | Method Not Allowed   | HTTP method not supported for this endpoint (e.g., POST on a GET-only route). | Using wrong HTTP method (POST instead of GET)                                    |
| 409  | Conflict             | Request conflicts with current resource state (e.g., duplicate record).       | Duplicate resource, race condition, resource locked                              |
| 422  | Unprocessable Entity | Request syntax valid, but semantic errors in data (validation failures).      | Missing required fields, invalid data types, values out of range                 |
| 429  | Too Many Requests    | Rate limit exceeded. Wait before making additional requests.                  | Too many requests in short period, see [Rate Limits](/api-reference/rate-limits) |

### Server Error Codes (5xx)

| Code | Name                  | Description                                                        | What To Do                           |
| ---- | --------------------- | ------------------------------------------------------------------ | ------------------------------------ |
| 500  | Internal Server Error | Unexpected error on the server. Contact support if issue persists. | Retry with exponential backoff       |
| 502  | Bad Gateway           | Invalid response from upstream server. Usually temporary.          | Retry after brief delay              |
| 503  | Service Unavailable   | Server temporarily unavailable (maintenance or overload).          | Retry after delay, check status page |
| 504  | Gateway Timeout       | Request timed out waiting for upstream server.                     | Retry with exponential backoff       |

## Validation Errors

When a request fails validation (422 status), the response includes an `errors` object with field-specific messages:

```json theme={null}
{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required.", "The email must be a valid email address."],
    "amount": ["The amount must be greater than 0."]
  }
}
```


# Create a fund
Source: https://docs.givebutter.com/api-reference/funds/create-a-fund

https://givebutter.com/docs/api.json post /v1/funds



# Delete a fund
Source: https://docs.givebutter.com/api-reference/funds/delete-a-fund

https://givebutter.com/docs/api.json delete /v1/funds/{fund}



# Get a fund
Source: https://docs.givebutter.com/api-reference/funds/get-a-fund

https://givebutter.com/docs/api.json get /v1/funds/{fund}



# List all funds
Source: https://docs.givebutter.com/api-reference/funds/list-all-funds

https://givebutter.com/docs/api.json get /v1/funds



# Update a fund
Source: https://docs.givebutter.com/api-reference/funds/update-a-fund

https://givebutter.com/docs/api.json put /v1/funds/{fund}



# Add a contact to a household
Source: https://docs.givebutter.com/api-reference/household-contacts/add-a-contact-to-a-household

https://givebutter.com/docs/api.json post /v1/households/{household}/contacts



# Get a contact associated with a household
Source: https://docs.givebutter.com/api-reference/household-contacts/get-a-contact-associated-with-a-household

https://givebutter.com/docs/api.json get /v1/households/{household}/contacts/{contact}



# List all contacts associated with a household
Source: https://docs.givebutter.com/api-reference/household-contacts/list-all-contacts-associated-with-a-household

https://givebutter.com/docs/api.json get /v1/households/{household}/contacts



# Remove a contact from a household
Source: https://docs.givebutter.com/api-reference/household-contacts/remove-a-contact-from-a-household

https://givebutter.com/docs/api.json delete /v1/households/{household}/contacts/{contact}



# Create a household
Source: https://docs.givebutter.com/api-reference/households/create-a-household

https://givebutter.com/docs/api.json post /v1/households



# Delete a household
Source: https://docs.givebutter.com/api-reference/households/delete-a-household

https://givebutter.com/docs/api.json delete /v1/households/{household}



# Get a household
Source: https://docs.givebutter.com/api-reference/households/get-a-household

https://givebutter.com/docs/api.json get /v1/households/{household}



# List all households
Source: https://docs.givebutter.com/api-reference/households/list-all-households

https://givebutter.com/docs/api.json get /v1/households



# Update a household
Source: https://docs.givebutter.com/api-reference/households/update-a-household

https://givebutter.com/docs/api.json put /v1/households/{household}



# Get a message
Source: https://docs.givebutter.com/api-reference/messages/get-a-message

https://givebutter.com/docs/api.json get /v1/messages/{message}



# List all messages
Source: https://docs.givebutter.com/api-reference/messages/list-all-messages

https://givebutter.com/docs/api.json get /v1/messages



# Pagination
Source: https://docs.givebutter.com/api-reference/pagination

Efficiently work with large datasets using cursor-based and offset pagination in the Givebutter API.

The Givebutter API uses pagination to break large result sets into manageable pages. This improves performance and allows you to retrieve data incrementally rather than loading thousands of records at once.

## Pagination Response Format

All paginated endpoints return responses in this structure:

<CodeGroup>
  ```json Response Structure theme={null}
  {
    "data": [
      // Array of resources (campaigns, transactions, contacts, etc.)
    ],
    "links": {
      "first": "https://api.givebutter.com/v1/campaigns?page=1",
      "last": "https://api.givebutter.com/v1/campaigns?page=5",
      "prev": "https://api.givebutter.com/v1/campaigns?page=1",
      "next": "https://api.givebutter.com/v1/campaigns?page=3"
    },
    "meta": {
      "current_page": 2,
      "from": 21,
      "last_page": 5,
      "path": "https://api.givebutter.com/v1/campaigns",
      "per_page": 20,
      "to": 40,
      "total": 95
    }
  }
  ```

  ```json First Page Example theme={null}
  {
    "data": [
      {
        "id": "camp_abc123",
        "title": "Annual Gala"
        // ... campaign data
      },
      {
        "id": "camp_def456",
        "title": "Spring Fundraiser"
        // ... campaign data
      }
      // ... 18 more campaigns
    ],
    "links": {
      "first": "https://api.givebutter.com/v1/campaigns?page=1",
      "last": "https://api.givebutter.com/v1/campaigns?page=5",
      "prev": null,
      "next": "https://api.givebutter.com/v1/campaigns?page=2"
    },
    "meta": {
      "current_page": 1,
      "from": 1,
      "last_page": 5,
      "path": "https://api.givebutter.com/v1/campaigns",
      "per_page": 20,
      "to": 20,
      "total": 95
    }
  }
  ```

  ```json Last Page Example theme={null}
  {
    "data": [
      {
        "id": "camp_xyz789",
        "title": "Year End Campaign"
        // ... campaign data
      }
      // ... only 15 campaigns on last page
    ],
    "links": {
      "first": "https://api.givebutter.com/v1/campaigns?page=1",
      "last": "https://api.givebutter.com/v1/campaigns?page=5",
      "prev": "https://api.givebutter.com/v1/campaigns?page=4",
      "next": null
    },
    "meta": {
      "current_page": 5,
      "from": 81,
      "last_page": 5,
      "path": "https://api.givebutter.com/v1/campaigns",
      "per_page": 20,
      "to": 95,
      "total": 95
    }
  }
  ```
</CodeGroup>

## Pagination Metadata

### Links Object

The `links` object provides ready-to-use URLs for navigating pages:

| Field   | Description                                         | Value When Not Available |
| ------- | --------------------------------------------------- | ------------------------ |
| `first` | URL to the first page of results                    | Never null               |
| `last`  | URL to the last page of results                     | Never null               |
| `prev`  | URL to the previous page (only if current page > 1) | `null` on first page     |
| `next`  | URL to the next page (only if more pages exist)     | `null` on last page      |

<Tip>
  The `next` link is the easiest way to paginate. Keep following `next` until it becomes `null` to
  fetch all results.
</Tip>

### Meta Object

The `meta` object provides detailed pagination state:

| Field          | Description                                      | Example                                   |
| -------------- | ------------------------------------------------ | ----------------------------------------- |
| `current_page` | The current page number (1-indexed)              | `2`                                       |
| `from`         | The index of the first item on this page         | `21`                                      |
| `to`           | The index of the last item on this page          | `40`                                      |
| `last_page`    | The total number of pages                        | `5`                                       |
| `per_page`     | Number of items per page                         | `20`                                      |
| `total`        | Total number of items across all pages           | `95`                                      |
| `path`         | Base URL for the resource (without query params) | `https://api.givebutter.com/v1/campaigns` |

## Query Parameters

Control pagination behavior with these query parameters:

| Parameter  | Description                             | Default | Max   |
| ---------- | --------------------------------------- | ------- | ----- |
| `page`     | The page number to retrieve (1-indexed) | `1`     | -     |
| `per_page` | Number of items per page                | `20`    | `100` |

<CodeGroup>
  ```bash Request Specific Page theme={null}
  curl "https://api.givebutter.com/v1/campaigns?page=3" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash Custom Page Size theme={null}
  curl "https://api.givebutter.com/v1/campaigns?per_page=50" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash Page 2 with 50 Items theme={null}
  curl "https://api.givebutter.com/v1/campaigns?page=2&per_page=50" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

<Note>
  The maximum `per_page` value is **100**. Requesting more than 100 items per page will return an
  error.
</Note>


# Get a payout
Source: https://docs.givebutter.com/api-reference/payouts/get-a-payout

https://givebutter.com/docs/api.json get /v1/payouts/{payout}



# List all payouts
Source: https://docs.givebutter.com/api-reference/payouts/list-all-payouts

https://givebutter.com/docs/api.json get /v1/payouts



# Get a pledge
Source: https://docs.givebutter.com/api-reference/pledges/get-a-pledge

https://givebutter.com/docs/api.json get /v1/pledges/{pledge}



# List all pledges
Source: https://docs.givebutter.com/api-reference/pledges/list-all-pledges

https://givebutter.com/docs/api.json get /v1/pledges



# Rate Limits
Source: https://docs.givebutter.com/api-reference/rate-limits

Understand API rate limits to ensure reliable access.

The Givebutter API is rate limited to **500 requests per minute**.

When you exceed this limit, you'll receive a `429 Too Many Requests` response with a `Retry-After` header indicating how many seconds to wait before retrying.


# Get a recurring plan
Source: https://docs.givebutter.com/api-reference/recurring-plans/get-a-recurring-plan

https://givebutter.com/docs/api.json get /v1/plans/{plan}



# List all recurring plans
Source: https://docs.givebutter.com/api-reference/recurring-plans/list-all-recurring-plans

https://givebutter.com/docs/api.json get /v1/plans



# Get ssov1account
Source: https://docs.givebutter.com/api-reference/sso-accounts/get-ssov1account

https://givebutter.com/docs/api.json get /sso/v1/account



# Get ssov1campaigns
Source: https://docs.givebutter.com/api-reference/sso-campaigns/get-ssov1campaigns

https://givebutter.com/docs/api.json get /sso/v1/campaigns/{campaign}



# Get a ticket
Source: https://docs.givebutter.com/api-reference/tickets/get-a-ticket

https://givebutter.com/docs/api.json get /v1/tickets/{ticket}



# List all tickets
Source: https://docs.givebutter.com/api-reference/tickets/list-all-tickets

https://givebutter.com/docs/api.json get /v1/tickets



# Create a transaction
Source: https://docs.givebutter.com/api-reference/transactions/create-a-transaction

https://givebutter.com/docs/api.json post /v1/transactions



# Get a transaction
Source: https://docs.givebutter.com/api-reference/transactions/get-a-transaction

https://givebutter.com/docs/api.json get /v1/transactions/{transaction}



# List all transactions
Source: https://docs.givebutter.com/api-reference/transactions/list-all-transactions

https://givebutter.com/docs/api.json get /v1/transactions



# Update a transaction
Source: https://docs.givebutter.com/api-reference/transactions/update-a-transaction

https://givebutter.com/docs/api.json put /v1/transactions/{transaction}



# Get a webhook activity
Source: https://docs.givebutter.com/api-reference/webhook-activities/get-a-webhook-activity

https://givebutter.com/docs/api.json get /v1/webhooks/{webhook}/activities/{activity}



# List all webhook activities
Source: https://docs.givebutter.com/api-reference/webhook-activities/list-all-webhook-activities

https://givebutter.com/docs/api.json get /v1/webhooks/{webhook}/activities



# Create a webhook
Source: https://docs.givebutter.com/api-reference/webhooks/create-a-webhook

https://givebutter.com/docs/api.json post /v1/webhooks



# Delete a webhook
Source: https://docs.givebutter.com/api-reference/webhooks/delete-a-webhook

https://givebutter.com/docs/api.json delete /v1/webhooks/{webhook}



# Get a webhook
Source: https://docs.givebutter.com/api-reference/webhooks/get-a-webhook

https://givebutter.com/docs/api.json get /v1/webhooks/{webhook}



# List all webhooks
Source: https://docs.givebutter.com/api-reference/webhooks/list-all-webhooks

https://givebutter.com/docs/api.json get /v1/webhooks



# Update a webhook
Source: https://docs.givebutter.com/api-reference/webhooks/update-a-webhook

https://givebutter.com/docs/api.json put /v1/webhooks/{webhook}



# Analytics & Attribution
Source: https://docs.givebutter.com/widgets/advanced/analytics

Track where your donations come from with automatic attribution data capture.

Givebutter Widgets automatically capture and store attribution data when visitors interact with your donation forms. This powerful feature helps you understand which marketing channels, campaigns, and content drive the most donations, allowing you to optimize your fundraising strategy.

## Automatic Tracking

The following parameters are automatically tracked when someone visits a page with a widget installed:

### UTM Parameters

UTM (Urchin Tracking Module) parameters are the standard way to track marketing campaign performance:

| Parameter      | Description                                                    | Example                            |
| -------------- | -------------------------------------------------------------- | ---------------------------------- |
| `utm_source`   | Identifies the source of your traffic                          | `facebook`, `google`, `newsletter` |
| `utm_medium`   | Specifies the marketing medium                                 | `social`, `email`, `cpc`, `banner` |
| `utm_campaign` | Names the specific campaign or promotional effort              | `spring-fundraiser`, `year-end`    |
| `utm_term`     | Tracks specific keywords in paid search campaigns              | `nonprofit-donation`, `charity`    |
| `utm_content`  | Distinguishes between different content or ads in one campaign | `blue-button`, `hero-cta`          |

### Platform Click IDs

Platform-specific identifiers for advanced tracking and conversion measurement:

| Parameter | Platform      | Description                                               |
| --------- | ------------- | --------------------------------------------------------- |
| `gclid`   | Google Ads    | Google Click ID for conversion tracking                   |
| `wbraid`  | Google Ads    | Web to App tracking on iOS 14+ (privacy-safe)             |
| `gbraid`  | Google Ads    | App to Web tracking on iOS 14+ (privacy-safe)             |
| `gclsrc`  | Google Ads    | Identifies the Google Ads source (ads, other services)    |
| `dclid`   | Google (DCM)  | DoubleClick Click ID for Display & Video 360              |
| `fbclid`  | Meta/Facebook | Facebook Click ID for conversion tracking and attribution |

## Troubleshooting

<Warning>
  **Attribution data not appearing?** Ensure the Widgets library is installed on the page where
  visitors land with UTM parameters. The library must load before the user navigates away.
</Warning>


# URL Prefill Parameters
Source: https://docs.givebutter.com/widgets/advanced/url-prefill

Pre-fill donation amount and frequency using URL parameters.

Givebutter Widgets support URL parameters that automatically pre-fill the donation amount and frequency when donors visit your page. This works with both button widgets (popup forms) and inline form widgets.

## Supported Parameters

| Parameter   | Description                         | Example              |
| ----------- | ----------------------------------- | -------------------- |
| `amount`    | Preset donation amount (in dollars) | `?amount=50`         |
| `frequency` | Donation frequency                  | `?frequency=monthly` |

### Frequency Options

Supported values for `frequency`:

* `monthly` - Donate every month
* `quarterly` - Donate every 3 months
* `yearly` - Donate once per year

## Examples

### Preset Donation Amount

Direct donors to a specific giving level:

```plaintext theme={null}
https://yoursite.org/donate?amount=100
```

### Monthly Giving Campaign

Create links for recurring donation campaigns:

```plaintext theme={null}
https://yoursite.org/donate?amount=25&frequency=monthly
```

This pre-fills a \$25/month recurring donation.


# Interactive Examples
Source: https://docs.givebutter.com/widgets/examples

See Givebutter Widgets in action with interactive, customizable examples.

Explore live, interactive examples of Givebutter Widgets. These are real, functioning widgets that demonstrate how they'll look and behave on your website.

<Info>
  **Note:** These examples use a demo Givebutter account. When you implement widgets on your site,
  you'll use your own Account ID and Campaign Codes.
</Info>

## Button Widget

<Tabs>
  <Tab title="Default">
    <div>
      <GivebutterWidget />
    </div>

    ```html theme={null}
    <givebutter-button campaign="YOUR_CAMPAIGN_CODE"></givebutter-button>
    ```
  </Tab>

  <Tab title="Event Tickets">
    <div>
      <GivebutterWidget label="Get Tickets" icon="ticket" />
    </div>

    ```html theme={null}
    <givebutter-button
      campaign="YOUR_CAMPAIGN_CODE"
      label="Get Tickets"
      icon="ticket"
      background-color="#6366F1"
      label-color="#FFFFFF"
      border-radius="8"
    ></givebutter-button>
    ```
  </Tab>

  <Tab title="Ghost">
    <div>
      <GivebutterWidget label="Learn More" icon="none" />
    </div>

    ```html theme={null}
    <givebutter-button
      campaign="YOUR_CAMPAIGN_CODE"
      label="Learn More"
      background-color="transparent"
      label-color="#059669"
      border-color="#059669"
      border-width="2"
      border-radius="8"
      drop-shadow="false"
      icon="none"
    ></givebutter-button>
    ```
  </Tab>

  <Tab title="Urgent Appeal">
    <div>
      <GivebutterWidget label="Donate Now" />
    </div>

    ```html theme={null}
    <givebutter-button
      campaign="YOUR_CAMPAIGN_CODE"
      label="Donate Now"
      background-color="#DC2626"
      label-color="#FFFFFF"
      border-radius="4"
    ></givebutter-button>
    ```
  </Tab>

  <Tab title="Pill">
    <div>
      <GivebutterWidget label="Send a Gift" icon="gift" />
    </div>

    ```html theme={null}
    <givebutter-button
      campaign="YOUR_CAMPAIGN_CODE"
      label="Send a Gift"
      icon="gift"
      background-color="#EC4899"
      label-color="#FFFFFF"
      border-radius="100"
    ></givebutter-button>
    ```
  </Tab>
</Tabs>

## Form Widget

<Tabs>
  <Tab title="Default">
    <div>
      <GivebutterWidget />
    </div>

    ```html theme={null}
    <givebutter-giving-form campaign="YOUR_CAMPAIGN_CODE"></givebutter-giving-form>
    ```
  </Tab>

  <Tab title="Card Style">
    <div>
      <h3>Support Our Cause</h3>
      <p>Your donation makes a real difference in our community.</p>

      <GivebutterWidget />
    </div>

    ```html theme={null}
    <div
      style="
      max-width: 600px;
      margin: 0 auto;
      padding: 2rem;
      background: white;
      border: 1px solid #e5e7eb;
      border-radius: 12px;
      box-shadow: 0 4px 6px rgba(0,0,0,0.1);
    "
    >
      <h3>Support Our Cause</h3>
      <p>Your donation makes a real difference in our community.</p>
      <givebutter-giving-form campaign="YOUR_CAMPAIGN_CODE"></givebutter-giving-form>
    </div>
    ```
  </Tab>

  <Tab title="Bordered Section">
    <div>
      <GivebutterWidget />
    </div>

    ```html theme={null}
    <div
      style="
      max-width: 600px;
      margin: 0 auto;
      padding: 1.5rem;
      border: 2px solid #3b82f6;
      border-radius: 8px;
      border-left: 6px solid #3b82f6;
    "
    >
      <givebutter-giving-form campaign="YOUR_CAMPAIGN_CODE"></givebutter-giving-form>
    </div>
    ```
  </Tab>
</Tabs>

## Goal Bar Widget

<Tabs>
  <Tab title="Default">
    <div>
      <GivebutterWidget />
    </div>

    ```html theme={null}
    <givebutter-goal-bar campaign="YOUR_CAMPAIGN_CODE"></givebutter-goal-bar>
    ```
  </Tab>

  <Tab title="Custom Colors">
    <div>
      <GivebutterWidget />
    </div>

    ```html theme={null}
    <givebutter-goal-bar
      campaign="YOUR_CAMPAIGN_CODE"
      progress-bar-color="#8B5CF6"
      text-color="#1F2937"
    ></givebutter-goal-bar>
    ```
  </Tab>

  <Tab title="Minimal">
    <div>
      <GivebutterWidget />
    </div>

    ```html theme={null}
    <givebutter-goal-bar
      campaign="YOUR_CAMPAIGN_CODE"
      show-raised-percentage="false"
      show-goal-amount="false"
      size="sm"
    ></givebutter-goal-bar>
    ```
  </Tab>

  <Tab title="Large">
    <div>
      <GivebutterWidget />
    </div>

    ```html theme={null}
    <givebutter-goal-bar
      campaign="YOUR_CAMPAIGN_CODE"
      progress-bar-color="#DC2626"
      size="lg"
    ></givebutter-goal-bar>
    ```
  </Tab>

  <Tab title="Thermometer">
    <div>
      <GivebutterWidget type="thermometer" />
    </div>

    A classic thermometer-style visualization for your fundraising progress.

    ```html theme={null}
    <givebutter-goal-bar
      campaign="YOUR_CAMPAIGN_CODE"
      type="thermometer"
      progress-bar-color="#DC2626"
    ></givebutter-goal-bar>
    ```
  </Tab>
</Tabs>

## Signup Form Widget

<Tabs>
  <Tab title="Default">
    <div>
      <GivebutterWidget />
    </div>

    ```html theme={null}
    <givebutter-signup-form account="YOUR_ACCOUNT_ID"></givebutter-signup-form>
    ```
  </Tab>

  <Tab title="With Title">
    <div>
      <GivebutterWidget title="Stay Connected" description="Get updates about our work" />
    </div>

    ```html theme={null}
    <givebutter-signup-form
      account="YOUR_ACCOUNT_ID"
      title="Stay Connected"
      description="Get updates about our work"
    ></givebutter-signup-form>
    ```
  </Tab>

  <Tab title="Custom Button">
    <div>
      <GivebutterWidget title="Join Our Newsletter" />
    </div>

    ```html theme={null}
    <givebutter-signup-form
      account="YOUR_ACCOUNT_ID"
      title="Join Our Newsletter"
      button-text="Subscribe Now"
      button-background-color="#8B5CF6"
    ></givebutter-signup-form>
    ```
  </Tab>

  <Tab title="Card Style">
    <div>
      <h3>Join Our Community</h3>
      <p>Get exclusive updates and early access</p>

      <GivebutterWidget />
    </div>

    ```html theme={null}
    <div style="
      max-width: 500px;
      padding: 2rem;
      background: white;
      border: 1px solid #e5e7eb;
      border-radius: 12px;
      box-shadow: 0 4px 6px rgba(0,0,0,0.1);
    ">
      <h3>Join Our Community</h3>
      <p>Get exclusive updates and early access</p>
      <givebutter-signup-form
        account="YOUR_ACCOUNT_ID"
        button-text="Count Me In"
      ></givebutter-signup-form>
    </div>
    ```
  </Tab>
</Tabs>


# Getting Started
Source: https://docs.givebutter.com/widgets/getting-started

Learn how to embed donation forms and buttons directly on your own website.

Givebutter Widgets allow you to seamlessly integrate donation forms, buttons, and other fundraising elements directly into your website. With just a few lines of code, you can start accepting donations without redirecting users away from your site.

## Prerequisites

Before you begin, you'll need:

* An active Givebutter account
* A campaign set up in your Givebutter Dashboard
* Access to edit your website's HTML

## Installing the Widgets Library

Installing Widgets is fast and easy. Simply add the following code snippet inside the `<head></head>` tag of your website and we'll take care of the rest.

<CodeGroup>
  ```html HTML theme={null}
  <script async src="https://widgets.givebutter.com/latest.umd.cjs?acct=YOUR_ACCOUNT_ID"></script>
  ```
</CodeGroup>

<Note>
  Replace `YOUR_ACCOUNT_ID` with your Account ID from your Givebutter Dashboard. We recommend
  including the code snippet on every page of your site for consistent tracking and analytics.
</Note>

### Finding Your Account ID

To find your Account ID:

1. Log in to your [Givebutter Dashboard](https://givebutter.com/dashboard)
2. Navigate to **Settings** > **Integrations**
3. Look for your **Account ID** in the Widgets section
4. Copy and paste it into the script tag above

## Embedding Widgets

Once you've installed the Widgets library, you can embed widgets anywhere on your website:

* **[Button Widget](/widgets/widget-types/button)** - A customizable button that opens a donation popup
* **[Form Widget](/widgets/widget-types/form)** - An inline donation form embedded on your page
* **[Goal Bar Widget](/widgets/widget-types/goal-bar)** - A progress bar showing campaign fundraising status
* **[Signup Form Widget](/widgets/widget-types/signup-form)** - A form to capture email subscribers

### Quick Setup (Dashboard)

1. Go to your campaign's **Sharing** → **Widgets** in the Givebutter Dashboard
2. Select the widget type and customize settings
3. Copy the generated code and paste it on your website

```html theme={null}
<givebutter-widget id="YOUR_WIDGET_ID"></givebutter-widget>
```

### Manual Setup

For more control, use the specific widget tags with your campaign code:

<CodeGroup>
  ```html Button theme={null}
  <givebutter-button campaign="YOUR_CAMPAIGN_CODE"></givebutter-button>
  ```

  ```html Form theme={null}
  <givebutter-giving-form campaign="YOUR_CAMPAIGN_CODE"></givebutter-giving-form>
  ```

  ```html Goal Bar theme={null}
  <givebutter-goal-bar campaign="YOUR_CAMPAIGN_CODE"></givebutter-goal-bar>
  ```

  ```html Signup Form theme={null}
  <givebutter-signup-form account="YOUR_ACCOUNT_ID"></givebutter-signup-form>
  ```
</CodeGroup>

## Finding Your Campaign Code

Your Campaign Code is a unique identifier for each campaign:

1. Go to your campaign in the Dashboard
2. Look at the top section near the title
3. The Campaign Code is the six-character text
4. Use this code in your widget tags

## Next Steps

Now that you've installed the Widgets library, explore the different widget types to find the best fit for your fundraising needs:

* **[Button Widget](/widgets/widget-types/button)** - Perfect for adding donate buttons anywhere on your site
* **[Form Widget](/widgets/widget-types/form)** - Embed a full donation form directly on your page
* **[Goal Bar Widget](/widgets/widget-types/goal-bar)** - Show campaign progress to motivate donors
* **[Signup Form Widget](/widgets/widget-types/signup-form)** - Grow your email list with a simple signup form


# GoDaddy
Source: https://docs.givebutter.com/widgets/website-builders/godaddy

Add Givebutter widgets to your GoDaddy Website Builder site.

<Note>
  For a step-by-step walkthrough with screenshots, see our [full GoDaddy
  guide](https://help.givebutter.com/en/articles/8225055-how-to-use-givebutter-widgets-on-a-godaddy-website).
</Note>

<Info>
  These instructions are for GoDaddy Website Builder. If you're using WordPress hosting from
  GoDaddy, see our [WordPress guide](/widgets/website-builders/wordpress) instead.
</Info>

## Prerequisites

* A GoDaddy Website Builder site (any plan)
* A Givebutter account with at least one published campaign

## Installation

GoDaddy requires both the library code and widget code to be added together in a single HTML section.

<Steps>
  <Step title="Get Your Codes">
    1. In Givebutter, go to **Settings** → **Developers** → **Widgets**
    2. Click **GoDaddy** and copy the library code
    3. Go to your campaign's **Sharing** → **Widgets** → **Embed**
    4. Copy the widget embed code
  </Step>

  <Step title="Add to GoDaddy">
    1. Open your GoDaddy website editor
    2. Navigate to the page where you want the widget
    3. Click **Add Section** → **HTML**
    4. Paste the **library code** first, then the **widget code** below it
    5. Click **Done** then **Publish**
  </Step>
</Steps>

**Combined code example:**

```html theme={null}
<script async src="https://widgets.givebutter.com/latest.umd.cjs?acct=YOUR_ACCOUNT_ID"></script>
<givebutter-widget id="YOUR_WIDGET_ID"></givebutter-widget>
```

<Warning>
  GoDaddy doesn't support site-wide header/footer code. You must add widgets to each page
  individually.
</Warning>

## Fixing Layout Issues

**White space around widget:**

* For static buttons: Set a smaller **Forced Height** in the HTML section settings
* For floating buttons: No adjustment needed

**Form gets cut off:**

* Remove any **Forced Height** constraint from the HTML section

## Customization

### Floating Button Position

```html theme={null}
<givebutter-widget id="YOUR_WIDGET_ID" position="bottom-left"></givebutter-widget>
```

Options: `bottom-right` (default), `bottom-left`

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget doesn't appear">
    * Both library code AND widget code must be in the same HTML section
    * Library code must be first, widget code below
    * Campaign must be published (not draft)
    * Page must be published
  </Accordion>

  <Accordion title="Widget appears on wrong pages">
    GoDaddy requires manual installation per page. Only add the code to pages where you want the
    widget.
  </Accordion>
</AccordionGroup>


# Squarespace
Source: https://docs.givebutter.com/widgets/website-builders/squarespace

Embed Givebutter widgets on your Squarespace website using Code Injection.

<Note>
  For a step-by-step walkthrough with screenshots, see our [full Squarespace
  guide](https://help.givebutter.com/en/articles/7198277-how-to-use-givebutter-widgets-on-a-squarespace-website).
</Note>

<Warning>
  **Squarespace Core, Plus, or Advanced plan required.** Code Injection is not available on Basic
  plans.
</Warning>

## Prerequisites

* A Squarespace Core, Plus, or Advanced plan
* A Givebutter account with at least one published campaign

## Installation

### Step 1: Add Library Code (Once)

1. In Givebutter, go to **Settings** → **Developers** → **Widgets**
2. Click **Squarespace** and copy the library code
3. In Squarespace, go to **Website** → **Pages** → **Website Tools** → **Code Injection**
4. Paste the library code in the **Header** section
5. Click **Save**

### Step 2: Add Widget to Page

1. In Givebutter, go to your campaign's **Sharing** → **Widgets** → **Embed**
2. Copy the widget embed code
3. In Squarespace, edit the page where you want the widget
4. Click **+** and add a **Code** block
5. Paste the widget code and save

```html theme={null}
<givebutter-widget id="YOUR_WIDGET_ID"></givebutter-widget>
```

## Customization

### Floating Button Position

```html theme={null}
<givebutter-widget id="YOUR_WIDGET_ID" position="bottom-left"></givebutter-widget>
```

Options: `bottom-right` (default), `bottom-left`

### Hide Widget on Specific Pages

Add this CSS to the page's **Advanced** → **Page Header Code Injection**:

```html theme={null}
<style>
  givebutter-widget[id='YOUR_WIDGET_ID'] {
    display: none;
  }
</style>
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget doesn't appear">
    * Library code must be in Code Injection → Header
    * Widget code must be in a Code block on the page
    * Campaign must be published (not draft)
    * Page changes must be saved
  </Accordion>

  <Accordion title="Widget appears cut off">
    Try adding more space around the Code block or use a full-width section.
  </Accordion>

  <Accordion title="Floating widget shows on wrong pages">
    Use the CSS hiding method above, or only add the widget to specific pages instead of using Code
    Injection.
  </Accordion>
</AccordionGroup>


# Weebly
Source: https://docs.givebutter.com/widgets/website-builders/weebly

Install Givebutter widgets on your Weebly website.

<Note>
  For a step-by-step walkthrough with screenshots, see our [full Weebly
  guide](https://help.givebutter.com/en/articles/7203871-how-to-use-givebutter-widgets-on-a-weebly-website).
</Note>

## Prerequisites

* A Weebly website (any plan)
* A Givebutter account with at least one published campaign

## Installation

### Step 1: Add Library Code (Once)

1. In Givebutter, go to **Settings** → **Developers** → **Widgets**
2. Click **Weebly** and copy the library code
3. In Weebly, go to **Settings** → **SEO**
4. Paste the library code in the **Header Code** field
5. Click **Save**

### Step 2: Add Widget to Page

1. In Givebutter, go to your campaign's **Sharing** → **Widgets** → **Embed**
2. Copy the widget embed code
3. In Weebly, go to the **Build** tab
4. Drag an **Embed Code** block to your page
5. Paste the widget code and publish

```html theme={null}
<givebutter-widget id="YOUR_WIDGET_ID"></givebutter-widget>
```

<Warning>
  Widgets will **not display in the Weebly editor**. You must publish and view your live site to see
  them.
</Warning>

## Customization

### Floating Button Position

```html theme={null}
<givebutter-widget id="YOUR_WIDGET_ID" position="bottom-left"></givebutter-widget>
```

Options: `bottom-right` (default), `bottom-left`

### Hide Widget on Specific Pages

Add this CSS to **Settings** → **SEO** → **Header Code**:

```html theme={null}
<style>
  givebutter-widget[id='YOUR_WIDGET_ID'] {
    display: none;
  }
</style>
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget doesn't appear">
    * Library code must be in Settings → SEO → Header Code
    * Widget code must be in an Embed Code block
    * Campaign must be published (not draft)
    * Site must be published (not just saved)
    * Clear browser cache and refresh
  </Accordion>

  <Accordion title="Widget appears cut off">
    Try using a full-width Embed Code block or a different page template.
  </Accordion>

  <Accordion title="Multiple widgets on same page">
    Add multiple Embed Code blocks, each with only the widget code. The library code in the header
    handles all widgets.
  </Accordion>
</AccordionGroup>


# Wix
Source: https://docs.givebutter.com/widgets/website-builders/wix

Add Givebutter donation widgets to your Wix website.

<Note>
  For a step-by-step walkthrough with screenshots, see our [full Wix
  guide](https://help.givebutter.com/en/articles/6464972-how-to-use-givebutter-widgets-on-a-wix-website).
</Note>

<Warning>
  **Paid Wix plan required.** You need a Light, Core, Business, or Business Elite plan with a custom
  domain to use Custom elements. Free Wix sites cannot install widgets.
</Warning>

## Prerequisites

* A paid Wix plan with custom domain
* A Givebutter account with at least one published campaign

## Installation

<Steps>
  <Step title="Get Your Codes">
    1. In Givebutter, go to **Settings** → **Developers** → **Widgets**
    2. Click **Wix** and copy the **Server URL** (library code)
    3. Go to your campaign's **Sharing** → **Widgets** → **Embed**
    4. Copy the **Widget ID** (shown in green in the code)
  </Step>

  <Step title="Add Custom Element">
    1. In the Wix editor, click **+** → **Embed Code** → **Custom element** 2. Click **Choose Source**
    2. Enter your **Server URL** and set Tag name to `givebutter-widget` 4. Click **Apply**
  </Step>

  <Step title="Set Widget ID">
    1. Click **Set Attributes** → **Add Attribute**
    2. Set Attribute name: `id` and Value: your Widget ID
    3. Click **Apply**
    4. Position the widget and **Publish**
  </Step>
</Steps>

<Tip>To make a widget appear site-wide, add it to your site's **header** or **footer**.</Tip>

## Customization

### Floating Button Position

1. Click **Set Attributes** → **Add Attribute**
2. Set Attribute name: `position` and Value: `bottom-left`
3. Click **Apply**

Options: `bottom-right` (default), `bottom-left`

### Hide Widget on Specific Pages

Add this CSS in **Settings** → **Custom Code** for that page:

```css theme={null}
givebutter-widget[id='YOUR_WIDGET_ID'] {
  display: none;
}
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget appears cropped in preview">
    This is normal. The widget displays properly on your published live site.
  </Accordion>

  <Accordion title="Widget doesn't load">
    * Must be on a paid Wix plan (not free) - Server URL must be correct - Tag name must be exactly
      `givebutter-widget` - Widget ID attribute must be set correctly - Campaign must be published
  </Accordion>

  <Accordion title="Widget only appears on one page">
    Move the custom element to your site's header or footer for site-wide display.
  </Accordion>
</AccordionGroup>


# WordPress
Source: https://docs.givebutter.com/widgets/website-builders/wordpress

Add Givebutter donation widgets to your WordPress website with the free plugin.

<Note>
  For a step-by-step walkthrough with screenshots, see our [full WordPress
  guide](https://help.givebutter.com/en/articles/7141647-how-to-use-givebutter-widgets-on-a-wordpress-website).
</Note>

<Warning>
  **WordPress.com Business or eCommerce plan required.** Free WordPress plans cannot install
  plugins. Self-hosted WordPress.org sites work with any plan.
</Warning>

## Prerequisites

* WordPress.com Business/eCommerce plan or self-hosted WordPress.org site
* A Givebutter account with at least one published campaign

## Installation

<Steps>
  <Step title="Install the Plugin">
    1. In Givebutter, go to **Settings** → **Developers** → **Widgets**
    2. Click **WordPress** and download the plugin
    3. In WordPress, go to **Plugins** → **Add New** → **Upload Plugin**
    4. Upload the file and click **Install Now** → **Activate**
  </Step>

  <Step title="Configure the Plugin">
    1. Go to **Settings** → **Givebutter Widgets** 2. Enter your Givebutter Account ID (found in
       **Settings** → **Developers** → **Widgets**) 3. Click **Save Changes**
  </Step>

  <Step title="Add a Widget">
    1. In Givebutter, go to your campaign's **Sharing** → **Widgets** → **Embed**
    2. Copy the Widget ID
    3. Edit your WordPress page/post
    4. Add a **Shortcode** block with: `[givebutter-widget id="YOUR_WIDGET_ID"]`
    5. Publish
  </Step>
</Steps>

### Alternative: Custom HTML Block

Instead of a shortcode, you can use a **Custom HTML** block:

```html theme={null}
<givebutter-widget id="YOUR_WIDGET_ID"></givebutter-widget>
```

## Customization

### Floating Button Position

```html theme={null}
<givebutter-widget id="YOUR_WIDGET_ID" position="bottom-left"></givebutter-widget>
```

Options: `bottom-right` (default), `bottom-left`

### Hide Widget on Specific Pages

Add this CSS to your theme's Custom CSS:

```css theme={null}
givebutter-widget[id='YOUR_WIDGET_ID'] {
  display: none;
}
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget doesn't appear">
    * Account ID must be correct in plugin settings
    * Campaign must be published (not draft)
    * Widget ID must be correct
    * Clear cache and refresh
  </Accordion>

  <Accordion title="Widget appears cut off">
    Try adding the widget to a full-width section or adjust your theme's content width settings.
  </Accordion>
</AccordionGroup>


# Button Widget
Source: https://docs.givebutter.com/widgets/widget-types/button

Embed a customizable donation button that opens a popup form on your site.

The Button Widget creates an attractive, clickable button on your website that opens a donation form in a popup modal. It's perfect for adding donation functionality without disrupting your page layout.

## Prerequisites

Before using the Button Widget, make sure you've [installed the Widgets library](/widgets/getting-started).

## Quick Setup

The fastest way to add a button widget is through the Givebutter Dashboard:

1. Visit your [Givebutter Dashboard](https://givebutter.com/dashboard)
2. Select your campaign and navigate to **Sharing** > **Widgets**
3. Choose **Button** as the widget type and customize the appearance
4. Copy the generated code and paste it on your site

```html theme={null}
<givebutter-widget id="YOUR_WIDGET_ID"></givebutter-widget>
```

<div>
  <GivebutterWidget />
</div>

## Manual Setup

For full control without using the dashboard, create buttons directly with the `<givebutter-button>` tag:

<CodeGroup>
  ```html Basic Button theme={null}
  <givebutter-button campaign="{YOUR_CAMPAIGN_CODE}"></givebutter-button>
  ```

  ```html Customized Button theme={null}
  <givebutter-button
    campaign="{YOUR_CAMPAIGN_CODE}"
    label="Support Our Mission"
    background-color="#FF6B6B"
    label-color="#FFFFFF"
    border-radius="8"
  ></givebutter-button>
  ```

  ```html Multiple Buttons theme={null}
  <!-- Different campaigns on the same page -->
  <givebutter-button campaign="general-fund" label="General Fund"></givebutter-button>

  <givebutter-button
    campaign="scholarship-fund"
    label="Scholarships"
    background-color="#4ECDC4"
  ></givebutter-button>
  ```
</CodeGroup>

## Configuration Options

Customize your button's appearance by adding attributes to the `<givebutter-button>` element:

### Required Attributes

| Attribute  | Description                              | Example       |
| ---------- | ---------------------------------------- | ------------- |
| `campaign` | Your campaign code (from your dashboard) | `my-campaign` |

### Styling Attributes

| Attribute          | Description                              | Default   | Type                                              |
| ------------------ | ---------------------------------------- | --------- | ------------------------------------------------- |
| `label`            | Text displayed on the button             | `Donate`  | String                                            |
| `hide-label`       | Hide the label text (icon only)          | `false`   | Boolean                                           |
| `label-color`      | Color of the text and icon               | `#FFFFFF` | Hex Color Code                                    |
| `background-color` | Background color of the button           | `#3366FF` | Hex Color Code                                    |
| `border-color`     | Color of the button border               | None      | Hex Color Code                                    |
| `border-width`     | Width of the border in pixels            | `0`       | Number                                            |
| `border-radius`    | Corner roundness (higher = more rounded) | `100`     | Number                                            |
| `drop-shadow`      | Display a shadow beneath the button      | `true`    | Boolean                                           |
| `icon`             | Icon to display                          | `heart`   | `heart`, `gift`, `giving_hands`, `ticket`, `none` |
| `icon-position`    | Position of the icon                     | `left`    | `left`, `right`                                   |
| `type`             | How the button opens the form            | `modal`   | `modal`, `link`                                   |
| `max-width`        | Maximum width of the modal               | `560px`   | CSS value                                         |

### Positioning

Use these attributes to create a fixed-position floating button:

| Attribute           | Description                          | Default | Options                                                                               |
| ------------------- | ------------------------------------ | ------- | ------------------------------------------------------------------------------------- |
| `position`          | Fixed position on the screen         | None    | `top-left`, `top-right`, `middle-left`, `middle-right`, `bottom-left`, `bottom-right` |
| `vertical-offset`   | Vertical offset from edge (pixels)   | `16`    | Number                                                                                |
| `horizontal-offset` | Horizontal offset from edge (pixels) | `16`    | Number                                                                                |

### Examples

<Tabs>
  <Tab title="Rounded Button">
    <div>
      <GivebutterWidget label="Buy Tickets" icon="ticket" />
    </div>

    ```html theme={null}
    <givebutter-button
      campaign="YOUR_CAMPAIGN_CODE"
      label="Buy Tickets"
      background-color="#6366F1"
      border-radius="100"
      drop-shadow="true"
      icon="ticket"
    ></givebutter-button>
    ```
  </Tab>

  <Tab title="Square Button">
    <div>
      <GivebutterWidget label="Donate Now" />
    </div>

    ```html theme={null}
    <givebutter-button
      campaign="YOUR_CAMPAIGN_CODE"
      label="Donate Now"
      background-color="#DC2626"
      border-radius="4"
      drop-shadow="false"
    ></givebutter-button>
    ```
  </Tab>

  <Tab title="Outlined Button">
    <div>
      <GivebutterWidget label="Become a Member" />
    </div>

    ```html theme={null}
    <givebutter-button
      campaign="YOUR_CAMPAIGN_CODE"
      label="Become a Member"
      background-color="#FFFFFF"
      label-color="#059669"
      border-color="#059669"
      border-width="2"
      border-radius="8"
    ></givebutter-button>
    ```
  </Tab>
</Tabs>

## Troubleshooting

<Warning>
  **Button not appearing?** Make sure you've [installed the Widgets
  library](/widgets/getting-started) on your page and that your campaign code is correct.
</Warning>

<Note>
  **Color not working?** Hex codes must include the `#` symbol (e.g., `#FF8A00` not `FF8A00`).
</Note>


# Form Widget
Source: https://docs.givebutter.com/widgets/widget-types/form

Embed a full donation form directly on your page for a seamless giving experience.

The Form Widget embeds a complete donation form inline on your webpage. Unlike the button widget which opens a popup, the form widget displays directly on your page, creating a seamless experience without any popups or redirects.

## Prerequisites

Before using the Form Widget, make sure you've [installed the Widgets library](/widgets/getting-started).

## Quick Setup

The fastest way to add a form widget is through the Givebutter Dashboard:

1. Visit your [Givebutter Dashboard](https://givebutter.com/dashboard)
2. Select your campaign and navigate to **Sharing** > **Widgets**
3. Choose **Form** as the widget type and customize the appearance
4. Copy the generated code and paste it on your site

```html theme={null}
<givebutter-widget id="YOUR_WIDGET_ID"></givebutter-widget>
```

<div>
  <GivebutterWidget />
</div>

## Manual Setup

For full control without using the dashboard, create forms directly with the `<givebutter-giving-form>` tag:

<CodeGroup>
  ```html Basic Form theme={null}
  <givebutter-giving-form campaign="YOUR_CAMPAIGN_CODE"></givebutter-giving-form>
  ```

  ```html With Goal Bar theme={null}
  <givebutter-giving-form campaign="YOUR_CAMPAIGN_CODE" show-goal-bar="true"></givebutter-giving-form>
  ```

  ```html Custom Width theme={null}
  <givebutter-giving-form campaign="YOUR_CAMPAIGN_CODE" max-width="500px"></givebutter-giving-form>
  ```
</CodeGroup>

## Configuration Options

### Required Attributes

| Attribute  | Description                              | Example       |
| ---------- | ---------------------------------------- | ------------- |
| `campaign` | Your campaign code (from your dashboard) | `my-campaign` |

### Optional Attributes

| Attribute       | Description                       | Default |
| --------------- | --------------------------------- | ------- |
| `show-goal-bar` | Display a goal bar above the form | `false` |
| `theme-color`   | Theme color for the goal bar      | None    |
| `max-width`     | Maximum width of the form         | `560px` |
| `max-height`    | Maximum height of the form        | None    |

<Note>
  The form's internal styling (colors, fonts, branding) is controlled through your Givebutter
  Dashboard campaign settings and automatically applied.
</Note>

## Layout Considerations

The form widget is responsive and will adapt to its container width. Consider these best practices:

<AccordionGroup>
  <Accordion title="Container Width">
    For optimal display:

    * **Minimum width**: 320px (mobile phones)
    * **Recommended width**: 400-600px for best readability
    * **Maximum width**: No limit, but forms look best under 800px
  </Accordion>

  <Accordion title="Page Layout">
    Common layout patterns: - **Full-width section**: Great for dedicated donation pages - **Sidebar
    widget**: Works in sidebars 300px+ wide - **Centered container**: Most popular for focused
    donation experiences - **Multi-column**: Use columns for multiple campaign forms
  </Accordion>

  <Accordion title="Height & Scrolling">
    * Forms expand automatically to fit content - No fixed height needed - Forms include all fields,
      so ensure adequate vertical space - Consider page length when embedding multiple forms
  </Accordion>

  <Accordion title="Mobile Responsiveness">
    * Forms automatically optimize for mobile devices
    * Touch-friendly input fields and buttons
    * Stacks elements vertically on small screens
    * Test on actual mobile devices for best results
  </Accordion>
</AccordionGroup>

## Troubleshooting

<Warning>
  **Form not appearing?** Make sure you've [installed the Widgets library](/widgets/getting-started)
  on your page and that your campaign code is correct.
</Warning>

<AccordionGroup>
  <Accordion title="Form appears too small">
    The form adapts to its container. Ensure the container is at least 320px wide. Check for CSS that might be constraining the width.
  </Accordion>

  <Accordion title="Form is cut off">
    Forms expand vertically to fit content. Ensure there's no `max-height` or `overflow: hidden` on
    parent containers.
  </Accordion>

  <Accordion title="Multiple forms on one page">
    You can embed multiple forms on the same page. Each will load independently. Consider spacing them
    with margin/padding for better UX.
  </Accordion>

  <Accordion title="Form styling doesn't match my site">
    Form styling is controlled in your Givebutter Dashboard under campaign settings. Update your campaign's design settings to match your brand.
  </Accordion>
</AccordionGroup>


# Goal Bar Widget
Source: https://docs.givebutter.com/widgets/widget-types/goal-bar

Display a visual fundraising progress bar to motivate donors and showcase campaign momentum.

The Goal Bar Widget displays a dynamic progress bar showing how much of your fundraising goal has been reached. It's a powerful social proof tool that creates urgency and motivates donors to contribute by visualizing campaign progress in real-time.

## Prerequisites

Before using the Goal Bar Widget, make sure you've [installed the Widgets library](/widgets/getting-started).

## Quick Setup

The fastest way to add a goal bar widget is through the Givebutter Dashboard:

1. Visit your [Givebutter Dashboard](https://givebutter.com/dashboard)
2. Select your campaign and navigate to **Sharing** > **Widgets**
3. Choose **Goal Bar** as the widget type and customize the appearance
4. Copy the generated code and paste it on your site

```html theme={null}
<givebutter-widget id="YOUR_WIDGET_ID"></givebutter-widget>
```

<div>
  <GivebutterWidget />
</div>

## Manual Setup

For full control without using the dashboard, create goal bars directly with the `<givebutter-goal-bar>` tag:

<CodeGroup>
  ```html Basic Goal Bar theme={null}
  <givebutter-goal-bar campaign="YOUR_CAMPAIGN_CODE"></givebutter-goal-bar>
  ```

  ```html Customized Goal Bar theme={null}
  <givebutter-goal-bar
    campaign="YOUR_CAMPAIGN_CODE"
    progress-bar-color="#3B82F6"
    size="lg"
  ></givebutter-goal-bar>
  ```

  ```html Minimal Goal Bar theme={null}
  <givebutter-goal-bar
    campaign="YOUR_CAMPAIGN_CODE"
    show-raised-percentage="false"
    show-goal-amount="false"
    size="sm"
  ></givebutter-goal-bar>
  ```
</CodeGroup>

## Configuration Options

Customize your goal bar's appearance by adding attributes to the `<givebutter-goal-bar>` element:

### Required Attributes

| Attribute  | Description                              | Example       |
| ---------- | ---------------------------------------- | ------------- |
| `campaign` | Your campaign code (from your dashboard) | `my-campaign` |

### Styling Attributes

| Attribute                | Description                       | Default        | Type                          |
| ------------------------ | --------------------------------- | -------------- | ----------------------------- |
| `progress-bar-color`     | Color of the progress bar fill    | `green`        | Hex Color Code                |
| `background-color`       | Background color of the container | `#FFFFFF`      | Hex Color Code                |
| `text-color`             | Color of text labels              | `#000000`      | Hex Color Code                |
| `border-color`           | Border color of the container     | None           | Hex Color Code                |
| `border-width`           | Border width in pixels            | `1`            | Number                        |
| `border-radius`          | Corner roundness in pixels        | `0`            | Number                        |
| `padding`                | Inner padding in pixels           | `16`           | Number                        |
| `size`                   | Height of the progress bar        | `md`           | `sm`, `md`, `lg`              |
| `max-width`              | Maximum width of the widget       | `100%`         | CSS value                     |
| `show-amount-raised`     | Show the amount raised            | `true`         | Boolean                       |
| `show-raised-percentage` | Show the percentage complete      | `true`         | Boolean                       |
| `show-goal-amount`       | Show the goal amount              | `true`         | Boolean                       |
| `type`                   | Style of the goal display         | `progress-bar` | `progress-bar`, `thermometer` |

## Examples

<Tabs>
  <Tab title="Default Style">
    <div>
      <GivebutterWidget />
    </div>

    ```html theme={null}
    <givebutter-goal-bar campaign="YOUR_CAMPAIGN_CODE"></givebutter-goal-bar>
    ```
  </Tab>

  <Tab title="Brand Colors">
    <div>
      <GivebutterWidget />
    </div>

    ```html theme={null}
    <givebutter-goal-bar
      campaign="YOUR_CAMPAIGN_CODE"
      progress-bar-color="#8B5CF6"
      text-color="#1F2937"
    ></givebutter-goal-bar>
    ```
  </Tab>

  <Tab title="Minimal">
    <div>
      <GivebutterWidget />
    </div>

    ```html theme={null}
    <givebutter-goal-bar
      campaign="YOUR_CAMPAIGN_CODE"
      show-raised-percentage="false"
      show-goal-amount="false"
      size="sm"
    ></givebutter-goal-bar>
    ```
  </Tab>

  <Tab title="Large">
    <div>
      <GivebutterWidget />
    </div>

    ```html theme={null}
    <givebutter-goal-bar
      campaign="YOUR_CAMPAIGN_CODE"
      progress-bar-color="#DC2626"
      size="lg"
    ></givebutter-goal-bar>
    ```
  </Tab>

  <Tab title="Thermometer">
    <div>
      <GivebutterWidget type="thermometer" />
    </div>

    The thermometer style displays your fundraising progress as a vertical thermometer, which is a classic visual metaphor for fundraising campaigns.

    ```html theme={null}
    <givebutter-goal-bar
      campaign="YOUR_CAMPAIGN_CODE"
      widgetType="thermometer"
      progress-bar-color="#DC2626"
    ></givebutter-goal-bar>
    ```
  </Tab>
</Tabs>

## Troubleshooting

<Warning>
  **Goal bar not appearing?** Make sure you've [installed the Widgets
  library](/widgets/getting-started) on your page and that your campaign code is correct.
</Warning>

<AccordionGroup>
  <Accordion title="Goal bar shows $0 or 0%">
    Common causes:

    * Campaign hasn't received any donations yet
    * Campaign goal not set in Dashboard
    * Campaign is not published/active
    * Incorrect campaign code

    **Solution:** Verify your campaign is active and has a goal set in your Givebutter Dashboard.
  </Accordion>

  <Accordion title="Goal bar doesn't fit container">
    The goal bar is responsive and will fill its container width. If it appears too wide or narrow:

    * Wrap it in a container with max-width
    * Use CSS to control the parent element's width
    * Check for conflicting CSS styles

    ```html theme={null}
    <div style="max-width: 600px; margin: 0 auto;">
      <givebutter-goal-bar campaign="YOUR_CAMPAIGN_CODE"></givebutter-goal-bar>
    </div>
    ```
  </Accordion>
</AccordionGroup>


# Signup Form Widget
Source: https://docs.givebutter.com/widgets/widget-types/signup-form

Capture email subscribers and grow your mailing list with an embedded signup form.

The Signup Form Widget lets you collect email addresses and grow your subscriber base directly from your website. Perfect for newsletters, updates, and building your donor community without requiring donations.

## Prerequisites

Before using the Signup Form Widget, make sure you've [installed the Widgets library](/widgets/getting-started).

## Quick Setup

The fastest way to add a signup form widget is through the Givebutter Dashboard:

1. Visit your [Givebutter Dashboard](https://givebutter.com/dashboard)
2. Navigate to **Marketing** > **Signup Forms**
3. Create and customize your signup form
4. Copy the generated code and paste it on your site

```html theme={null}
<givebutter-widget id="YOUR_WIDGET_ID"></givebutter-widget>
```

## Manual Setup

For full control without using the dashboard, create signup forms directly with the `<givebutter-signup-form>` tag:

<CodeGroup>
  ```html Basic Signup Form theme={null}
  <givebutter-signup-form
    account="YOUR_ACCOUNT_ID"
    title="Stay Connected"
    description="Get updates about our work"
  ></givebutter-signup-form>
  ```

  ```html Custom Button theme={null}
  <givebutter-signup-form
    account="YOUR_ACCOUNT_ID"
    title="Join Our Newsletter"
    description="Weekly updates delivered to your inbox"
    button-text="Subscribe Now"
    button-background-color="#3B82F6"
  ></givebutter-signup-form>
  ```

  ```html With Image Banner theme={null}
  <givebutter-signup-form
    account="YOUR_ACCOUNT_ID"
    title="Stay in the Loop"
    description="Be the first to know about events"
    layout="stacked"
    image="https://example.com/banner.jpg"
  ></givebutter-signup-form>
  ```
</CodeGroup>

## Configuration Options

### Required Attributes

| Attribute | Description                           | Example       |
| --------- | ------------------------------------- | ------------- |
| `account` | Your account ID (from your dashboard) | `acct_abc123` |

### Content Attributes

| Attribute     | Description                 | Default |
| ------------- | --------------------------- | ------- |
| `title`       | Form heading text           | None    |
| `description` | Subheading/description text | None    |

### Button Attributes

| Attribute                 | Description               | Default     |
| ------------------------- | ------------------------- | ----------- |
| `button-text`             | Text on the submit button | `Subscribe` |
| `button-text-color`       | Button text color         | None        |
| `button-background-color` | Button background color   | None        |

### Layout Attributes

| Attribute       | Description                | Default  | Options                           |
| --------------- | -------------------------- | -------- | --------------------------------- |
| `layout`        | Form layout style          | `simple` | `simple`, `stacked`, `two_column` |
| `border-radius` | Corner roundness in pixels | `0`      | Number                            |
| `image`         | Background image URL       | None     | URL                               |
| `image-sizing`  | How the image fits         | `cover`  | `cover`, `fit`, `stretch`         |

### Behavior Attributes

| Attribute    | Description                   | Default  | Options           |
| ------------ | ----------------------------- | -------- | ----------------- |
| `type`       | Form display type             | `static` | `static`, `popup` |
| `open-delay` | Delay before popup opens (ms) | `5000`   | Number            |
| `channel`    | Communication channel         | `email`  | `email`, `sms`    |

## Layout Considerations

The signup form widget is lightweight and responsive. Consider these best practices:

<AccordionGroup>
  <Accordion title="Container Width">
    For optimal display:

    * **Minimum width**: 280px (mobile phones)
    * **Recommended width**: 300-500px for best readability
    * **Maximum width**: No limit, but forms look best under 600px
  </Accordion>

  <Accordion title="Page Placement">
    Common placement patterns: - **Footer**: Capture subscribers at the bottom of every page -
    **Sidebar**: Great for blog posts and content pages - **Pop-up/Modal**: Attention-grabbing (use
    sparingly) - **Inline**: Within blog posts or between content sections - **Landing Page Hero**:
    Primary CTA for list-building pages
  </Accordion>

  <Accordion title="Height & Spacing">
    * Signup forms are compact (typically 80-120px tall) - Include adequate padding around the form -
      Consider success message height when planning layout - Forms expand slightly on validation errors
  </Accordion>

  <Accordion title="Mobile Responsiveness">
    * Forms automatically optimize for mobile devices
    * Touch-friendly input fields and buttons
    * Keyboard opens automatically on focus
    * Test on actual mobile devices for best results
  </Accordion>
</AccordionGroup>

## Troubleshooting

<Warning>
  **Form not appearing?** Make sure you've [installed the Widgets library](/widgets/getting-started)
  on your page and that your account ID is correct.
</Warning>

<AccordionGroup>
  <Accordion title="Form appears unstyled">
    The form may still be loading. Ensure:

    * The widgets script is loaded correctly
    * Your account ID is valid
    * No JavaScript errors in the browser console
    * You're not blocking third-party scripts
  </Accordion>

  <Accordion title="Submissions not appearing in Dashboard">
    Check these common issues: - Account ID matches your Givebutter account - Form submission
    completed successfully (success message shown) - Allow a few minutes for data to sync - Check
    spam/junk folders if using email confirmation
  </Accordion>

  <Accordion title="Button not working">
    Verify that: - Email input has a valid email address - JavaScript is enabled in the browser - No
    ad blockers interfering with the widget - Check browser console for errors
  </Accordion>

  <Accordion title="Form styling doesn't match my site">
    Signup form styling is controlled in your Givebutter Dashboard under **Marketing** > **Signup Forms** > **Design**. Update your form design settings to match your brand.
  </Accordion>

  <Accordion title="Success message not displaying">
    The success message is configured in your Dashboard. Check:

    * Dashboard settings under **Marketing** > **Signup Forms** > **Messages**
    * Ensure success message is enabled
    * Try a different browser to rule out caching issues
  </Accordion>
</AccordionGroup>