What Data Does BotRefund Need to Process Refunds? A Field-by-Field Guide

BotRefund requires five core data points from your website to process a refund: the order ID, the order amount, the currency, the customer email, and line-item details (what was purchased, quantity, price). You can also pass a refund reason and any custom metadata you find useful. These fields let BotRefund tie a refund claim to the specific session that produced the click, which is what makes the evidence convincing enough for Google and Meta to approve it.

In practice, your checkout or order management system already has this information. The task is mapping those fields into BotRefund's accepted format. This guide explains each field, why it matters, what a complete payload looks like, and common mistakes that slow down refunds.

What data does BotRefund actually need?

BotRefund uses a lightweight tracking script to detect bot clicks on your site. To process a refund, it needs to connect the order you want refunded to the session that generated the click. That connection depends on the fields below.

Required fields

• Order ID: A unique identifier for the purchase. It must be consistent across your store and BotRefund so the two can be matched.
• Amount: The total value of the order, in numeric form (for example, 149.00). This is the sum you want refunded.
• Currency: The ISO 4217 code (USD, EUR, GBP, etc.) so the refund amount is interpreted correctly.
• Customer email: The email address on the order. BotRefund uses it to verify the purchase and match it to a user session if needed.
• Line-item details: The products, quantities, and prices in the order. This helps confirm the order is real and provides context for the refund request.

Optional fields

• Refund reason: A free-text field explaining why you are requesting the refund. Useful when you are reporting invalid traffic to Google or Meta.
• Custom metadata: Any additional key-value pairs your team wants to attach, such as campaign ID, ad set ID, or a session ID.

If you skip optional fields, BotRefund can still process the refund, but the evidence pack will be thinner. The required fields give BotRefund enough to file a claim.

Why these fields matter for refund approval

Google and Meta do not approve refunds based on a simple request. They want to see a connection between the click you paid for and the session that triggered the order. The order ID links the purchase to a specific session. The amount and currency tell the platform exactly how much was wasted. The customer email confirms the order is genuine. Line items prove the order was real and not a test.

Without these fields, BotRefund can still detect bot traffic, but it cannot prepare a refund claim that meets the ad platforms' standards. The data is the raw material for the evidence report that BotRefund submits during negotiation.

The order ID is the anchor of a refund request. Without it, the ad platforms have no way to link a click to a purchase. With it, we can show them exactly what happened from the click to the conversion.

This is why getting the order field mapping right is not just a technical detail. It is the difference between a refund that gets approved and one that gets dismissed. Every field you correctly pass strengthens the case BotRefund builds on your behalf.

A sample JSON payload you can model

Here is a hypothetical example of what a refund request payload might look like. This is a clean, readable structure you can adapt in your integration.

{
  "order_id": "ORD-2024-00521",
  "amount": 149.00,
  "currency": "USD",
  "customer_email": "buyer@example.com",
  "line_items": [
    {
      "sku": "SILVER-PLAN",
      "name": "Silver Subscription",
      "quantity": 1,
      "unit_price": 149.00
    }
  ],
  "refund_reason": "Bot click detected with no human engagement",
  "metadata": {
    "campaign_id": "camp-123",
    "ad_group_id": "ag-456",
    "click_id": "GCLID-fj2093"
  }
}

This structure covers the required fields and includes optional ones. The exact JSON schema may vary by integration method. Always check the latest API documentation before going live.

How to map your website fields to BotRefund

Most e-commerce platforms already have these fields in their order objects. The work is usually a one-to-one mapping.

1. Find your order object. In Shopify, it is the order resource. In WooCommerce, it is the WC_Order or its REST API representation. Every field you need exists there.
2. Identify the matching keys. For example, Shopify's order['id'] maps to order_id. WooCommerce's order->get_total() maps to amount. Currency comes from store settings.
3. Extract line items. Loop through the items and build the line_items array.
4. Pass the payload. You can send it via a webhook, direct API call, or a data export.

If you use a third-party integration tool like Zapier or a custom script, the mapping is the same. The key is that the values are in the correct format and the order ID is unique.

Common mistakes that delay refund processing

Even with the right data, small errors can cause the claim to be rejected or paused. Here are the most frequent problems:

• Missing order ID: Some integrations accidentally send the session ID or customer ID instead. The order ID must be the primary key.
• Wrong currency format: Using “US Dollars” instead of “USD” can cause a mismatch.
• Amount without decimals: A float like 149.00 is expected. Sending 149.0 or 149 may be parsed incorrectly.
• Line items as a string: If you concatenate items into a single string, BotRefund cannot verify individual products.
• Using test data in production: Ensure you are sending real order data, not a dummy order from a staging site.

Always run a test transaction in BotRefund's sandbox mode before going live. That catches these mistakes early.

Key facts from BotRefund's documentation

These facts come directly from BotRefund's public pages. They show that the service is built on behavioral evidence, not just IP blocking.

Limitations and when the data requirements do not apply

BotRefund's data needs assume you have a real order to tie the refund request to. If you want a refund for a click that did not produce a purchase, the process is different. The refund request is filed based on the click ID, not the order data. In that case, the required fields are simply the click identifier (like GCLID or FBCLID) and the amount of ad spend you want to reclaim.

Also, if your site does not run the tracking script from the first click, you cannot recover refunds for those sessions. The script must be present before the interaction to capture the behavioral evidence. So the data requirements matter only after the script is installed.

Finally, refund approval is not guaranteed. Even with perfect data, Google and Meta have their own review processes. BotRefund improves your odds by providing solid evidence, but the platforms make the final call.

Frequently asked questions about refund data

Do I need to send my entire order database?

No. You only send the data for the orders you want to refund. BotRefund does not need a bulk export of all historical orders.

Can I send data via a webhook or API?

Yes, BotRefund accepts data through a REST API for custom integrations. The exact endpoint and verification process are covered in the developer documentation.

What if my store has multiple currencies?

Send the currency code that was used at checkout. BotRefund treats each order independently, so mixed-currency stores work fine as long as the code is correct.

Can I add custom fields later?

Yes, custom metadata fields are flexible. You can add them at any time, but they are optional for refund processing.

How long does it take to format the data?

Most developers set up the mapping in under an hour. If you use a plugin, the mapping is automatic.

Does BotRefund store my customer data securely?

BotRefund processes order data to file refund claims and does not sell or share it. You can check the privacy policy on the site for details.