Real-time store locator

The store locator in BFG is a feature that enables brands to register and manage the information of physical retail locations associated with a brand. This allows you to search store locations based on the following types:

General: Shows stores based on their distance to your device’s location and other custom filters
Product: Shows stores based on product availability and other custom filters

Use the following APIs to register stores for approval in BFG and specify product specifications for display in your store locator.

List brands

Use this endpoint to retrieve a list of brands that support physical store listings and are available for store registration. Each listed brand includes an account_id that is used to register a store under that brand using the Register a store API.

Endpoint: GET /api/store-locator/brands

Query parameters

Parameter	Required	Description
`sort`	No	Sorts the brands.
`page_size`	No	Sets the number of results per page.
`page`	No	Sets the page number.
`filter[field]`	No	Filters results by one or more field values.

Example request

curl --request GET \
  --get "https://api-sandbox.buyingfreedom.app/api/store-locator/brands?sort=name&page=2&page_size=20&filter%5Bfield%5D=outdoors&filter%5Btrashed%5D=fbcc27e3-417c-4e55-bb9a-4d122b7c3b6f" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

Example response

{
  "data": [
    {
      "name": "Hendrix Tactical Co.",
      "account_id": "f23a7859-2f5e-4f89-90c6-5cda78e2cd2f"
    },
    {
      "name": "ArmoryX",
      "account_id": "dab133e0-14e1-49d3-a327-fbe14fcd9b27"
    },
    {
      "name": "Liberty Outfitters",
      "account_id": "c671ea03-c6f3-4f2e-a9cb-8571a3d42214"
    }
  ],
  "links": {
    "first": "https://atlas.com/api/store-locator/brands?page=1",
    "last": "https://atlas.com/api/store-locator/brands?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://atlas.com/api/store-locator/brands?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://atlas.com/api/store-locator/brands",
    "per_page": 10,
    "to": 3,
    "total": 3
  }
}

Register a store

Use this endpoint to submit a store for approval in BFG and associate it with the brand specified in the client request. This also lets you specify store metadata such as the following:

FFL license number for firearm retailers
Contact details
Store pickup and e-commerce labels
Full address and logo

After using the Register a store API, the store is listed on the Candidate Stores page (Stores > Candidates Stores) in BFG for approval. When approved, the store is then displayed in your store locator for discovery by customers.

Endpoint: POST /api/store-locator/register

Body parameters

Parameter	Required	Description
`brand_account_id`	Yes	`account_id` retrieved from the `List brands` API.
`ffl_license_number`	No	Federal firearms license (FFL) number.
`name`	Yes	Store name.
`logo`	No	URL to the store's logo image.
`phone`	No	Store contact phone number.
`email`	No	Store contact email address.
`website`	No	Store website URL.
`store_pickup`	No	Whether the store supports local pickup.
`online_shopping`	No	Whether the store offers online shopping.
`address_1`	Yes if `ffl_license_number` is null	Street address line 1.
`address_2`	No	Street address line 2.
`address_3`	No	Street address line 3.
`city`	No	City name.
`state`	No	State abbreviation.
`postal_code`	No	US ZIP code (5 digits or ZIP+4 format).
`country`	No	Country code (ISO 3166-1 alpha-2).

Note: ffl_license_number has the following conditions:

If an FFL number is found, the store's address information from the FFL database of BFG will replace the address information provided in the request.
If no FFL number is found, the store’s address will be taken from the API request. If that address doesn’t match any record in the BFG database, the system will search Google for the address and save the results.

If the store has an FFL, it's recommended to provide the FFL in the request to ensure the most accurate information is used.

Example request

curl --request POST \
  "https://api-sandbox.buyingfreedom.app/api/store-locator/register" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: multipart/form-data" \
  --header "Accept: application/json" \
  --form "brand_account_id=8a5e71e2-4a20-4a31-924c-1024fdc782a9" \
  --form "ffl_license_number=473990204D88214" \
  --form "name=HENDRIX ARMORY" \
  --form "phone=7025558912" \
  --form "[email protected]" \
  --form "website=https://hendrixarmory.example" \
  --form "store_pickup=1" \
  --form "online_shopping=1" \
  --form "address_1=4927 RIVERSTONE PARKWAY" \
  --form "address_2=Building 4" \
  --form "address_3=Unit B" \
  --form "city=ROCKWELL" \
  --form "state=NV" \
  --form "postal_code=89012" \
  --form "country=US" \
  --form "logo=@/private/var/folders/abc/temp/phpXyZlmn"

Example response

{
  "data": {
    "id": 3127,
    "account_id": "8a5e71e2-4a20-4a31-924c-1024fdc782a9",
    "ffl_license_number": "473990204D88214",
    "name": "HENDRIX ARMORY",
    "logo_url": "https://bfg-atlas-dev.s3.amazonaws.com/companies/logos/3127/204/logo-hendrix.png",
    "phone": "7025558912",
    "email": null,
    "website": null,
    "store_pickup": false,
    "online_shopping": false,
    "address_1": "4927 RIVERSTONE PARKWAY",
    "address_2": null,
    "address_3": null,
    "city": "ROCKWELL",
    "state": "NV",
    "postal_code": "89012",
    "country": null,
    "created_at": "2025-04-24T09:07:13.000000Z",
    "updated_at": "2025-04-24T09:07:13.000000Z"
  }
}

Note: The account_id retrieved in the response is used in the Update Product Inventory and Bulk Update Product Inventories APIs.

Subscribing to Product Webhooks for Inventory Updates

Technology Partners must subscribe to the product webhook to receive events when a manufacturer adds new products. Once a webhook event is received, the Technology Partner should update the inventory of that product in their system and sync it to the appropriate stores using the Product Inventory API.

Daily Heartbeat API Call

Use the health check endpoint to verify that your system connection with BFG is active and healthy. This endpoint returns system-level information such as database connectivity, cache status, storage, and queue system health.

Endpoint: GET /api/health?account_id={account_id}

Query Parameters

Parameter	Required	Description
`account_id`	No	`account_id` retrieved in the Register a store API response.

Example Request

curl -X GET "https://api-stg.buyingfreedom.app/api/health" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response

{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00.000000Z",
  "execution_time_ms": 45.23,
  "version": {
    "app": "1.0.0",
    "laravel": "11.x",
    "php": "8.3.0"
  },
  "environment": "production",
  "checks": {
    "database": {
      "status": "healthy",
      "message": "Database connection successful",
      "response_time_ms": 12.45
    },
    "cache": {
      "status": "healthy",
      "message": "Cache system operational",
      "response_time_ms": 8.23
    },
    "storage": {
      "status": "healthy",
      "message": "Storage system operational",
      "response_time_ms": 15.67
    },
    "queue": {
      "status": "healthy",
      "message": "Queue system operational",
      "response_time_ms": 8.88,
      "queue_size": 42
    }
  },
  "summary": {
    "total_checks": 4,
    "healthy": 4,
    "degraded": 0,
    "unhealthy": 0,
    "disabled": 0
  }
}

Note: If you provide an account_id, the system finds the matching store and updates all related rows in store_inventory_sources by setting last_connected_at to the current timestamp. This action signals a successful connection (heartbeat). The updated last_connected_at value appears in product inventory responses that include the store_inventory_source key.