How the GiveCheck Badge Works (Technical Deep Dive)

The GiveCheck badge is the most visible element of the platform — a small widget that sits on your website and tells visitors exactly how much of your revenue goes to charity, verified in real time. But how does it actually work under the hood? This post is for the technically curious founders who want to understand the engineering before they embed.

The Embed Code

Adding the GiveCheck badge to your site is a single script tag:

<script src="https://badge.givecheck.org/v1/embed.js" data-company="your-slug"></script>

That's it. The script is lightweight (under 4KB gzipped) and loads asynchronously so it never blocks your page render. It creates a shadow DOM element to prevent style conflicts with your existing CSS.

What Happens When the Script Loads

Here's the sequence of events when a visitor loads a page with the GiveCheck badge:

1. Script initialization: The embed script reads the data-company attribute to identify which company's badge to render.
2. API call: The script makes a GET request to https://api.givecheck.org/v1/badge/{slug}. This endpoint returns a JSON payload with the company's current verification status, giving percentage, tier, and display configuration.
3. Rendering: Based on the API response, the script renders the appropriate badge variant inside a shadow DOM container. This includes the giving percentage, verification checkmark, and 10% Club indicator if applicable.
4. Caching: The badge data is cached in the visitor's browser for 15 minutes to reduce API calls. After the cache expires, the next page load triggers a fresh API call.

The Verification Pipeline

The badge displays data that's computed through a multi-step verification pipeline that runs on the 1st of each month:

1. Revenue pull: GiveCheck queries the Stripe API using the company's read-only OAuth token. It retrieves the total gross revenue for the previous calendar month. This uses Stripe's balance_transactions endpoint, filtered by type and date range.
2. Donation pull: GiveCheck queries Every.org's API to retrieve all donations made by the company during the same month. This includes the amount, recipient nonprofit, and transaction status.
3. Calculation: The system divides total verified donations by total verified revenue to get the MRG percentage. Both numbers are stored for audit purposes.
4. Status update: The company's badge status is updated in the database. If the percentage is 10% or higher, the 10% Club flag is set. If giving has dropped to zero, the badge enters a grace period (typically one month) before going gray.

The Gray Badge: Enforcement

The enforcement mechanism is simple but effective. If a company's verified giving drops to 0% for two consecutive months, their badge transitions to a gray state. The gray badge doesn't show a percentage — it shows "Verification Lapsed." This is visible to anyone who visits the company's website.

The gray badge can't be hidden or removed through the API — it's a deliberate design choice. If you embed the GiveCheck badge, you're opting into public accountability. You can always remove the script tag from your site, but as long as it's there, it tells the truth.

Security Considerations

Several security measures protect the badge system:

• Read-only Stripe access: GiveCheck's OAuth scope is limited to reading balance transactions and account information. It cannot create charges, modify customers, or access sensitive payment data.
• Server-side rendering: The badge data is computed server-side. The JavaScript embed is a display layer only — it cannot modify verification data.
• Rate limiting: The badge API is rate-limited per IP and per company slug to prevent abuse.
• CORS restrictions: The badge API only responds to requests from domains that the company has registered in their GiveCheck settings.
• No PII exposure: The badge API never returns customer data, transaction details, or any personally identifiable information. It returns only the company name, giving percentage, tier, and verification timestamp.

Customization Options

The badge supports several display options via data attributes: data-theme (light or dark), data-size (small, medium, large), and data-style (badge, banner, minimal). These let you match the widget to your site's design without writing any CSS.

For advanced users, the raw API endpoint is available for building custom badge implementations. As long as you're displaying accurate, current data from the API, you're free to design the display however you'd like.