Geofence API v1
Contract: radius_delivery.geofences_v1 · Schema version 1.0
Geofence API v1 is the versioned Shopify data contract that lets Radius Ads Geofencing read delivery areas created in Radius Delivery. Radius Delivery remains the source of truth, while the Ads app turns the selected geography into a reviewable advertising-targeting change.
Both Shopify apps must be installed on the same store.
The merchant must install and authorize both Radius Delivery and Radius Ads Geofencing in the same Shopify store. Radius Delivery publishes the contract to that store, and Radius Ads Geofencing reads it through its own authenticated Shopify Admin API session.
Installing only one app is not enough. This public page documents the format, but it does not expose any merchant’s geofence data and does not provide a public Internet endpoint.
Shopify location
| Owner | Shop |
|---|---|
| Namespace | radius_delivery |
| Key | geofences_v1 |
| Type | json |
| Schema | 1.0 |
| Ownership | Merchant-owned Shopify metafield |
Radius Delivery creates the metafield definition and publishes the document after the merchant saves a valid delivery configuration. The non-reserved namespace allows another app installed and authorized by the same merchant to read the data through Shopify.
Published data
- Stable
geofence_idvalues - Monotonically increasing revisions
- Active and inactive area status
- Basic circles with center, radius and unit
- Original Pro polygon coordinates
- Separate inclusions and exclusions
- Source location labels and coordinates
- Publication and area update timestamps
Removed areas can remain in the document as inactive, allowing a consumer to detect the change without assuming that an external advertising target should be deleted automatically.
Example document
This fictional example shows the public contract shape. It is not connected to a live Shopify store.
{
"schema_version": "1.0",
"updated_at": "2026-08-28T00:00:00.000Z",
"geofences": [
{
"schema_version": "1.0",
"geofence_id": "gf_exampletorun001",
"name": "Toruń Delivery",
"status": "active",
"revision": 1,
"location": {
"source_type": "shopify_location",
"shopify_location_id": "gid://shopify/Location/EXAMPLE",
"label": "Toruń Store",
"latitude": 53.0138,
"longitude": 18.5984
},
"geometry": {
"type": "circle",
"center": { "latitude": 53.0138, "longitude": 18.5984 },
"radius": 12,
"unit": "km"
},
"inclusions": [],
"exclusions": [],
"delivery_type": "local_delivery",
"updated_at": "2026-08-28T00:00:00.000Z"
}
]
}Consumer query
An installed companion app reads the metafield from its authenticated server-side Shopify Admin GraphQL client:
query RadiusAdsReadGeofences {
shop {
metafield(namespace: "radius_delivery", key: "geofences_v1") {
value
type
updatedAt
}
}
}The query requires a valid Shopify app installation and server-side authorization for the merchant’s store. Access tokens must never be placed in website code or public documentation.
Security boundary
The document contains delivery geography only. It does not contain customers, orders, advertising access tokens, ad account IDs, campaign IDs or Meta Ad Set IDs. Radius Ads Geofencing keeps its platform authorization and advertising mappings separately.
Radius Ads Geofencing is a read-only consumer of this contract. It must not edit radius_delivery.geofences_v1 or change a live advertising target merely because a newer revision exists. The merchant reviews and approves each targeting update.
Compatibility and change detection
- Existing area IDs remain stable when an area is edited.
- Each saved change increases the area’s
revisionand updates its timestamp. - Consumers reject unsupported schema versions and preserve the last known safe mapping when data is missing or invalid.
- Additive optional fields may be introduced within v1.
- A breaking change requires a new schema version and a new Shopify metafield key.