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

# Geofencing

> Create location-based campaigns by checking customer, product, or SKU coordinates against locations you define

<Info>
  <Badge color="gray">Enterprise feature</Badge>

  Geofencing is available only for Enterprise clients. Contact your technical account manager or [Voucherify support](https://www.voucherify.io/contact-support) to enable it.
</Info>

Use geofencing to create location-specific campaigns by controlling who can redeem and which products are eligible, based on customer, product, or SKU location.

You can:

* Limit redemptions to customers in specific locations
* Discount or exclude products based on their location
* Exclude particular areas from applying discounts

Geofencing works with all campaign types: discount coupons, cart promotions, loyalty programs, gift cards, and referral programs.

## What geofencing does and doesn't do

Geofencing doesn't track location automatically.

Voucherify checks locations only when coordinates are sent in the API request (for example, during voucher redemption).

You have to:

* Create location boundaries in the dashboard
* Store coordinates in metadata (customer, product, or SKU)
* Send the current coordinates in the request

<Warning>
  If no location is sent, geofencing rules are skipped.
</Warning>

## How geofencing works

Geofencing works by comparing coordinates you send with locations you define.

It uses three elements:

* Location objects: areas you draw on a map (circles or polygons)
* Geopoint metadata: latitude and longitude saved on customers, products, or SKUs
* Segments or collections: groups created by checking whether coordinates fall inside a location

When a customer redeems a voucher, Voucherify checks whether the coordinates sent in metadata are inside the allowed location boundaries used in validation rules.

## Choose what you want to control

You can use geofencing in two independent ways:

* Customer location: controls who can redeem.
* Product or SKU location: controls which items are discounted, required, or excluded.

You can use one or both in the same campaign.

## Manage locations

Go to **Campaign hub** > **Locations** in the dashboard to create and manage location objects.

### Create a location

Create a new location as follows.

<Steps>
  <Step title="Open the location creator">
    Select **Create location** in the top-right corner.
  </Step>

  <Step title="Find your target area">
    Use the map or search bar to navigate to the area where you want to create a location.
  </Step>

  <Step title="Define boundaries">
    Draw the location boundaries using one of two options:

    * **Circle**: Set a center point and radius.
    * **Polygon**: Draw a custom shape by placing points on the map.

    Use the map editor controls to manage your boundaries:

    | Control           | Description                                                  |
    | ----------------- | ------------------------------------------------------------ |
    | Re-center         | Brings the selected location back into focus on the map      |
    | Draw polygon      | Draws a custom polygon boundary by placing points on the map |
    | Draw circle       | Draws a circular boundary using a center point and radius    |
    | Edit boundaries   | Enables edit mode to adjust existing boundaries              |
    | Delete boundaries | Removes selected boundaries from the location                |
    | Zoom in / out     | Zooms the map in or out                                      |
  </Step>

  <Step title="Name and save">
    Enter a **Location name** and save.
  </Step>
</Steps>

A new location is added to the location list.

### Location manager options

When managing an already created location, you can use the tricolon ⁝ to display the following options:

| Option     | Description                                                                     |
| ---------- | ------------------------------------------------------------------------------- |
| Show usage | Shows which resources use the location (product collections, customer segments) |
| Edit       | Modify the location name or boundaries                                          |
| Duplicate  | Create a copy of the location                                                   |
| Delete     | Remove the location                                                             |

## Geofencing with customer location

Customer geofencing limits who is allowed to redeem a campaign.

<Steps>
  <Step title="Create a location">
    Create a location that defines where customers are allowed to redeem.
  </Step>

  <Step title="Create customer geopoint metadata">
    Go to **Project settings** > **Metadata schema** > **Customer** and create a new metadata definition:

    * **Type**: Geopoint
    * **Name**: for example `customer_location`

    This metadata stores coordinates in `geo:latitude,longitude` format.
  </Step>

  <Step title="Create a location-based customer segment">
    Create a segment as follows:

    1. Go to **Customers** > **Find and apply filters**.
    2. Select **Custom attributes (metadata)**.
    3. Choose the geopoint metadata property.
    4. Select a **Location object** as the filter value.
    5. Confirm and select **Apply**.

    The segment updates automatically when customer locations change.
  </Step>

  <Step title="Add a validation rule">
    Add a validation rule as follows:

    1. Create or edit a campaign.
    2. In the validation rule builder, add a condition based on **Customer segment**.
    3. Select the location-based segment.
    4. Save the rule.

    Only customers from that segment, which means those inside the defined location, can redeem the campaign.
  </Step>

  <Step title="Pass customer location during redemption">
    When redeeming a voucher, send the customer's current location:

    ```json highlight={5} theme={null}
    {
      "customer": {
        "source_id": "customer_123",
        "metadata": {
          "customer_location": "geo:40.7128,-74.0060"
        }
      }
    }
    ```
  </Step>
</Steps>

## Geofencing with product or SKU location

Product and SKU geofencing controls which items are eligible for discounts or required in the cart.

Product and SKU geofencing works the same way:

* Use **Product metadata** if the location applies to the whole product.
* Use **SKU metadata** if different SKUs have different locations.

<Steps>
  <Step title="Create a location">
    Create a location that defines allowed product or SKU locations.
  </Step>

  <Step title="Create product or SKU geopoint metadata">
    Create metadata schema as follows:

    1. Go to **Project settings** > **Metadata schema**.
    2. Select **Product** or **SKU**.
    3. Create a metadata definition:
       * **Type**: Geopoint
       * **Name**: for example `product_location`
  </Step>

  <Step title="Create a location-based product collection">
    Create a new collection as follows

    1. Go to **Products** > **Find and apply filters**.
    2. Select **Custom attributes (metadata)**.
    3. Choose the geopoint metadata property.
    4. Select a **Location** object.
    5. Confirm and select **Apply**.
    6. Select **Create dynamic collection** and save it.
  </Step>

  <Step title="Use the collection in validation rules">
    You can use location-based collections to:

    * Discount or exclude products from specific locations.
    * Require products from a specific location to be in the cart.

    In the validation rule builder, expand **Products structure validation rules** and choose how order items should match the collection:

    * **Any**: at least one item must be from this location *(most common)*
    * **Every**: all items must be from this location
    * **None**: no items can be in this location

    If you choose **Any** or **Every**, you can also define:

    * Minimum quantity of matching items
    * Minimum subtotal of matching items
  </Step>

  <Step title="Pass product or SKU location during redemption">
    Send product or SKU coordinates in the order items:

    ```json lines highlight={8} theme={null}
      {
        "order": {
          "items": [
            {
              "product_id": "prod_123",
              "quantity": 1,
              "metadata": {
                "product_location": "geo:37.786971,-122.399677"
              }
            }
          ]
        }
      }
    ```

    <Warning>
      If the `product_location` metadata is missing or empty, the product or SKU will not match any location-based collection.
    </Warning>

    Voucherify validates whether item coordinates match the collection filters.
  </Step>
</Steps>

## Troubleshooting

If geofencing doesn't work, check the following:

* A geopoint metadata field exists (customer, product, or SKU)
* Coordinates are sent in the request using geo:latitude,longitude
* The coordinates are inside the location boundaries
* The correct segment or collection is used in validation rules
* Validation rules are enabled in the campaign

## Related features

Geofencing connects customer data, product data, and campaign rules. Use the resources below to set up the required elements and integrate geofencing into your workflows.

<AccordionGroup>
  <Accordion title="Customer segments">
    Apart from using customer segments to group customers by location, you can create even more complex scenarios. Create a segment based on geopoint metadata and a location object and other customer attributes, then use them together in validation rules to control who can redeem.

    Read the [Customer segments](/prepare/customer-segments) guide to learn more.
  </Accordion>

  <Accordion title="Product collections">
    Apart from using product collections to group products or SKUs by location, you can create even more complex scenarios. Create a dynamic collection based on geopoint metadata and a location object and other product or SKU attributes, then use them together in validation rules to control which items are eligible.

    Read the [Product collections](/prepare/product-collections) guide to learn more.
  </Accordion>

  <Accordion title="Validation rules">
    Apart from using validation rules to apply location-based segments and collections to your campaigns, you can create even more complex scenarios. You can require customers from a specific segment, check whether order items belong to a location-based collection, and limit to a specific cart structure and safeguard your campaign budget with other conditions.

    Read the [Create validation rules](/optimize/create-validation-rules) guide to learn more.
  </Accordion>

  <Accordion title="Metadata">
    Geofencing uses geopoint metadata to store and send coordinates. You need to define geopoint metadata fields on customers, products, or SKUs before using geofencing.

    Read the [Metadata](/prepare/metadata) guide to learn more.
  </Accordion>

  <Accordion title="Developer setup: Geofencing API">
    Developers need to send location coordinates in API requests for geofencing to work. The key integration points are:

    * **Validations**: Check eligibility before redemption using the [Validate Stacked Discounts](/api-reference/validations/validate-stackable-discounts) endpoint with location metadata included.
    * **Redemptions**: Send customer or product geopoint metadata in the [Redeem Stacked Discounts](/api-reference/redemptions/redeem-stackable-discounts) request body to trigger location-based validation.
    * **Customers**: Manage customer profiles and metadata using the [Customers API](/api-reference/customers/customer-object).
    * **Metadata schemas**: List metadata schemas for geopoint metadata fields using the [Metadata Schemas API](/api-reference/metadata-schemas/metadata-schema-object).
    * **Locations**: View location objects using the [Location Object](/api-reference/locations/location-object) reference.
    * **Segments**: Manage location-based segments using the [Segments API](/api-reference/segments/segment-object).
    * **Product collections**: Manage location-based collections using the [Product Collections API](/api-reference/product-collections/product-collection-object).
  </Accordion>
</AccordionGroup>