API docs by Redocly

Geofence Offer Engine (1.0.0)

Download OpenAPI specification:

A Stripe-native geofence API that allows merchants to define promotional policies and automatically trigger personalized, location-based payment links when customers enter a physical zone.

merchants

Create Merchant

Request Body schema: application/json
required
name
required
string (Name)
email
required
string <email> (Email)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "email": "string",
  • "api_key": "string",
  • "stripe_account_id": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

List Merchants

query Parameters
skip
integer (Skip)
Default: 0
limit
integer (Limit)
Default: 50

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Merchant

path Parameters
merchant_id
required
string (Merchant Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "email": "string",
  • "api_key": "string",
  • "stripe_account_id": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

geofences

Create Geofence

Authorizations:
APIKeyHeader
path Parameters
merchant_id
required
string (Merchant Id)
Request Body schema: application/json
required
name
required
string (Name)
lat
required
number (Lat)
lng
required
number (Lng)
radius_meters
number (Radius Meters)
Default: 75
required
Array of objects (Discount Tiers)
max_discount
integer (Max Discount)
Default: 20
object (ActiveHours)
Default: {"start":"07:00","end":"20:00"}

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "lat": 0,
  • "lng": 0,
  • "radius_meters": 75,
  • "discount_tiers": [
    ],
  • "max_discount": 20,
  • "active_hours": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "merchant_id": "string",
  • "name": "string",
  • "lat": 0,
  • "lng": 0,
  • "radius_meters": 0,
  • "max_discount": 0,
  • "active_hours_start": "string",
  • "active_hours_end": "string",
  • "is_active": true,
  • "discount_tiers": [
    ],
  • "created_at": "2019-08-24T14:15:22Z"
}

List Geofences

path Parameters
merchant_id
required
string (Merchant Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Geofence

path Parameters
merchant_id
required
string (Merchant Id)
geofence_id
required
string (Geofence Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "merchant_id": "string",
  • "name": "string",
  • "lat": 0,
  • "lng": 0,
  • "radius_meters": 0,
  • "max_discount": 0,
  • "active_hours_start": "string",
  • "active_hours_end": "string",
  • "is_active": true,
  • "discount_tiers": [
    ],
  • "created_at": "2019-08-24T14:15:22Z"
}

Delete Geofence

Authorizations:
APIKeyHeader
path Parameters
merchant_id
required
string (Merchant Id)
geofence_id
required
string (Geofence Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Toggle Geofence

Authorizations:
APIKeyHeader
path Parameters
merchant_id
required
string (Merchant Id)
geofence_id
required
string (Geofence Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "merchant_id": "string",
  • "name": "string",
  • "lat": 0,
  • "lng": 0,
  • "radius_meters": 0,
  • "max_discount": 0,
  • "active_hours_start": "string",
  • "active_hours_end": "string",
  • "is_active": true,
  • "discount_tiers": [
    ],
  • "created_at": "2019-08-24T14:15:22Z"
}

checkins

Process Checkin

Public endpoint — no API key required. Accepts merchant_id either in the request body or as a query param. This makes it easy to use from the demo frontend.

query Parameters
Merchant Id (string) or Merchant Id (null) (Merchant Id)
Request Body schema: application/json
required
user_id
required
string (User Id)
lat
required
number (Lat)
lng
required
number (Lng)
Merchant Id (string) or Merchant Id (null) (Merchant Id)

Responses

Request samples

Content type
application/json
{
  • "user_id": "string",
  • "lat": 0,
  • "lng": 0,
  • "merchant_id": "string"
}

Response samples

Content type
application/json
{
  • "offer_id": "string",
  • "enabled": true,
  • "discount_percent": 0,
  • "personalization": {
    },
  • "loyalty": {
    },
  • "stripe_payment_link": "string",
  • "geofence_name": "string",
  • "message": "string"
}

Get Offer

path Parameters
offer_id
required
string (Offer Id)

Responses

Response samples

Content type
application/json
null

Get Loyalty Status

Returns a customer's current loyalty tier, token balance, and progress to the next tier. Useful for a loyalty card or progress bar in the frontend.

path Parameters
merchant_id
required
string (Merchant Id)
user_id
required
string (User Id)

Responses

Response samples

Content type
application/json
null

analytics

Get Analytics

path Parameters
merchant_id
required
string (Merchant Id)

Responses

Response samples

Content type
application/json
{
  • "merchant_id": "string",
  • "total_offers": 0,
  • "redeemed_offers": 0,
  • "redemption_rate": 0,
  • "total_revenue": 0,
  • "conversion_percent": 0
}

webhooks

Stripe Webhook

Receives Stripe webhook events. On checkout.session.completed → marks the matching offer as redeemed.

header Parameters
stripe-signature
string (Stripe-Signature)

Responses

Response samples

Content type
application/json
null

promotions

List Promotions

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Promotion

Request Body schema: application/json
required
company_id
required
string (Company Id)
description
required
string (Description)
timeline
required
string (Timeline)

Responses

Request samples

Content type
application/json
{
  • "company_id": "string",
  • "description": "string",
  • "timeline": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "company_id": "string",
  • "description": "string",
  • "timeline": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Get Promotions For Merchant

path Parameters
company_id
required
string (Company Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

meta

Health

Responses

Response samples

Content type
application/json
null

Mock Checkout

Local stand-in for Stripe Checkout — shown when no price_id is configured.

path Parameters
mock_id
required
string (Mock Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}