> ## Documentation Index
> Fetch the complete documentation index at: https://agentref.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# WordPress Integration

> Install AgentRef on a WordPress site and understand when WordPress checkout flows do or do not map cleanly to AgentRef.

WordPress gives you multiple installation options, but the safest AgentRef setup is still the same: load the script site-wide and keep checkout on a supported Stripe path.

## Before you start

* Set the program website in AgentRef to the same root domain your WordPress site uses.
* Copy the exact script snippet from `Settings -> Integration`.
* If WordPress is only your marketing site and checkout happens on `app.example.com`, install AgentRef on both surfaces.

## Recommended installation

<Tabs>
  <Tab title="Plugin or header injector">
    If your site already uses a site-wide header-code plugin or theme option, paste the AgentRef script into the global head field.

    ```html theme={null}
    <script
      defer
      src="https://www.agentref.co/api/tracking/script.js?pid=YOUR_PROGRAM_ID"
    ></script>
    ```
  </Tab>

  <Tab title="Child theme">
    If you prefer code, add the script through `wp_head` in your child theme instead of editing the parent theme directly.

    ```php theme={null}
    add_action('wp_head', function () {
      ?>
      <script
        defer
        src="https://www.agentref.co/api/tracking/script.js?pid=YOUR_PROGRAM_ID"
      ></script>
      <?php
    }, 20);
    ```
  </Tab>
</Tabs>

<Tip>
  If you use caching, minification, or CDN plugins, clear those caches after installing the script.
</Tip>

## Checkout compatibility on WordPress

| Checkout pattern                                                                    | Recommendation                                                                                                                                    |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Stripe Payment Links, Buy Buttons, or Pricing Tables embedded on WordPress pages    | Supported directly.                                                                                                                               |
| Custom Stripe Checkout Session created by your own WordPress plugin or backend code | Supported, but you must follow the [Stripe guide](/docs/integration/stripe).                                                                      |
| WooCommerce or another native WordPress ecommerce checkout                          | Not an automatic AgentRef checkout surface today unless you explicitly bridge attribution into Stripe metadata or report conversions server-side. |

<Warning>
  This is the key WordPress caveat: installing the script on a WooCommerce storefront captures referral visits, but it does not by itself guarantee automatic order attribution through WooCommerce's native checkout path.
</Warning>

## Multi-domain and consent notes

* Shared subdomains under one root can share AgentRef cookies if the script is installed where the journey begins.
* Different root domains cannot share first-party cookies automatically.
* If you use a consent manager, call `window.AgentRef.setConsent('granted')` after the visitor opts in.

## Verify the installation

<Steps>
  <Step title="Open a live affiliate link">
    Land on your published WordPress site with a real referral link.
  </Step>

  <Step title="Confirm cookies">
    Check for `agentref_cid` and `agentref_pid` in browser cookies.
  </Step>

  <Step title="Run a published-site test">
    Add `?agentref_debug=1` or `?agentref_verify=1` to a live page and inspect the result.
  </Step>

  <Step title="Validate the checkout path">
    If you use anything beyond hosted Stripe surfaces, confirm your checkout integration matches the [Stripe guide](/docs/integration/stripe).
  </Step>
</Steps>

## Troubleshooting

* The script is visible in WordPress admin but not on the live site: a cache or optimization layer is still serving the old template.
* Clicks arrive but sales do not: this usually means WooCommerce or another plugin owns checkout and does not pass AgentRef metadata into Stripe.
* Cookies exist on the marketing site but not in the app: install AgentRef on both subdomains.

## Related docs

<CardGroup cols={3}>
  <Card title="Stripe Checkout" icon="credit-card" href="/docs/integration/stripe">
    Required for custom WordPress-to-Stripe checkout bridges.
  </Card>

  <Card title="Server-Side Tracking" icon="server" href="/docs/tracking/server-side">
    Use this when your commerce stack cannot pass through AgentRef automatically.
  </Card>

  <Card title="Consent and GDPR" icon="shield" href="/docs/tracking/consent-gdpr">
    Coordinate AgentRef with your cookie banner.
  </Card>
</CardGroup>