Store management

In BFG, stores represent physical or online retail locations that are linked to a brand. These stores are managed through the BFG platform so brands can:

List where their products are available
Display store-specific contact and branding details (logo, phone, email, etc.)

Stores are entities tied to the authenticated brand. Each store record includes metadata like:

Name, address, and contact info
Capabilities (e.g., store_pickup, online_shopping)
Brand identity (e.g., logo, friendly_name)
Geolocation

List stores

Retrieves a paginated list of stores linked to the authenticated brand. Supports filtering, sorting, and pagination.

Endpoint: GET /api/manufacturers/stores

Query parameters

Parameter	Required	Description
`sort`	No	Sorts by the specified field.
`page_size`	No	Sets the number of results per page.
`page`	No	Sets the page number.
`filter[field]`	No	Filters stores by matching field values.
`filter[trashed]`	No	Filters based on whether the store is trashed.

Example request

curl --request GET \
  --get "https://api-sandbox.buyingfreedom.app/api/manufacturers/stores?sort=name&page=2&page_size=20&filter%5Bfield%5D=dolor&filter%5Btrashed%5D=with" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

Example response

{
  "data": [
    {
      "id": 11,
      "account_id": "73f05e76-9984-4a7d-9f9a-9dbb9c65c96d",
      "name": "Hendrix Armory",
      "friendly_name": "Hendrix Armory HQ",
      "logo_url": "https://example.com/logos/hendrix-armory.png",
      "phone": "4045552983",
      "email": "[email protected]",
      "website": "https://hendrixarmory.com",
      "store_pickup": true,
      "online_shopping": false,
      "allow_backorder": true,
      "low_stock_threshold": 8,
      "address_1": "789 WESTFIELD ROAD",
      "address_2": "BUILDING A",
      "address_3": null,
      "city": "GREENSBORO",
      "state": "NC",
      "postal_code": "27407",
      "country": "US",
      "timezone": "America/New_York",
      "longitude": -79.8194,
      "latitude": 36.0726,
      "is_residential": false,
      "full_address": "789 WESTFIELD ROAD, BUILDING A, GREENSBORO, NC 27407, US",
      "uses_ffl": true,
      "hours": [
        {
          "id": 4,
          "company_id": 11,
          "day_of_week": 1,
          "open_time": "10:00:00",
          "close_time": "18:00:00",
          "is_closed": false,
          "special": false,
          "created_at": "2024-02-01T10:00:00.000000Z",
          "updated_at": "2024-02-01T10:00:00.000000Z"
        }
      ],
      "tags": [
        {
          "id": 7,
          "name": "Veteran-Owned",
          "slug": "veteran-owned",
          "text": "Veteran-Owned",
          "color": "#17a2b8",
          "icon": "medal"
        }
      ],
      "types": [
        {
          "id": 5,
          "name": "Tactical Supply",
          "slug": "tactical-supply",
          "text": "Tactical Supply",
          "color": "#ffc107",
          "icon": "target"
        }
      ],
      "manufacturer_account_number": "MFG98765",
      "brand_terms_signed_at": "2024-03-01T15:45:00.000000Z",
      "show_on_locator": true,
      "show_stock_availability": true,
      "show_website": true,
      "custom_attributes": [
        {
          "id": 3,
          "company_attribute_id": 6,
          "company_attribute": {
            "id": 6,
            "name": "POS ID",
            "input_type": "text"
          },
          "value": "POS45678",
          "is_active": true
        }
      ],
      "is_promoted": true,
      "product_url": "https://example.com/products/hendrix",
      "inventory_url": "https://example.com/inventory/hendrix",
      "brand_signed_terms": true,
      "brand_terms_file": {
        "id": 9,
        "name": "signed-terms-hendrix.pdf",
        "file_name": "signed-terms-hendrix.pdf",
        "mime_type": "application/pdf",
        "size": 204800,
        "url": "https://example.com/media/agreements/signed-terms-hendrix.pdf"
      },
      "created_at": "2024-02-01T00:00:00.000000Z",
      "updated_at": "2024-02-01T00:00:00.000000Z",
      "deleted_at": null
    }
  ],
  "links": {
    "first": "https://api.example.com/api/manufacturers/stores?page=1",
    "last": "https://api.example.com/api/manufacturers/stores?page=5",
    "prev": "https://api.example.com/api/manufacturers/stores?page=1",
    "next": "https://api.example.com/api/manufacturers/stores?page=3"
  },
  "meta": {
    "current_page": 2,
    "from": 21,
    "last_page": 5,
    "path": "https://api.example.com/api/manufacturers/stores",
    "per_page": 20,
    "to": 40,
    "total": 87
  }
}

Create a store

Creates a new store and associates it with the authenticated brand.

Endpoint: POST /api/manufacturers/stores

To link an existing store to a brand, you can optionally get the ffl_license_number by calling the GET /api/ffls endpoint. In the response, use the value in ffl_number as the ffl_license_number in your Create a store request.

If the ffl_license_number exists in the BFG database, the system finds the matching store and associates it with the brand linked to the company token in the request.

If no FFL exists, the system checks for an exact match of address_1, city, state, and postal code. All values must match.

If no exact match is found, the system uses AI to look for possible typos or close matches.

If no existing store is found, the system creates a new store and links it to the brand determined by the token in the request.

Body parameters

Parameter	Required	Description
`ffl_license_number`	No	The store’s FFL license number.
`name`	Yes	The store name. Must be unique within the postal code. Max 255 characters.
`friendly_name`	No	A friendly display name for the store. Max 255 characters.
`logo`	No	The company logo. Must be a valid image file. Max size 2 MB.
`phone`	No	The store’s phone number. Max 25 characters.
`email`	No	The store’s email address. Must be valid. Max 255 characters.
`website`	No	The store’s website URL. Must be valid. Max 255 characters.
`store_pickup`	No	Set to true if the store offers store pickup.
`online_shopping`	No	Set to true if the store offers online shopping.
`low_stock_threshold`	No	Stock quantity that triggers low stock alerts.
`address_1`	No	The primary street address. Max 255 characters.
`address_2`	No	Optional secondary address line. Max 255 characters.
`address_3`	No	Optional tertiary address line. Max 255 characters.
`city`	No	The city where the store is located. Max 60 characters.
`state`	No	The state or province. For US, use valid two-letter code. Max 30 characters.
`postal_code`	No	Postal or ZIP code. Max 255 characters.
`country`	No	The country where the store is located. Max 255 characters.
`is_residential`	No	Set to true if the store is at a residential address.
`uses_ffl`	No	Set to true if the store uses FFL services.
`manufacturer_account_number`	No	The manufacturer’s account number. Max 255 characters.
`product_url`	No	The product URL. Must be valid. Max 255 characters.
`brand_url`	No	The brand URL. Must be valid. Max 255 characters.
`brand_signed_terms`	No	Set to true if brand terms have been signed.
`brand_terms_file`	No	Upload brand terms file (PDF).
`store_tags`	No	Pipe-separated list of store tags.
`store_types`	No	Pipe-separated list of store types.
`show_on_locator`	No	Set to true to show the store in the locator.
`show_stock_availability`	No	Set to true to display stock availability.
`show_website`	No	Set to true to display the store website.
`is_promoted`	No	Set to true if the store is promoted.
`custom_attributes`	No	Pipe-separated custom attributes in "Name: Value\|Name2: Value2" format.

Example request

curl --request POST \
  "https://api-sandbox.buyingfreedom.app/api/manufacturers/stores" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: multipart/form-data" \
  --header "Accept: application/json" \
  --form "ffl_license_number=HX9057301M23199" \
  --form "name=HENDRIX ARMORY" \
  --form "friendly_name=Hendrix Armory HQ" \
  --form "phone=9785550147" \
  --form "[email protected]" \
  --form "website=https://hendrixarmory.com" \
  --form "store_pickup=1" \
  --form "online_shopping=1" \
  --form "low_stock_threshold=8" \
  --form "address_1=425 ELM ST UNIT A" \
  --form "address_2=Suite 300" \
  --form "address_3=North Wing" \
  --form "city=STONEBRIDGE" \
  --form "state=TX" \
  --form "postal_code=75214" \
  --form "country=US" \
  --form "is_residential=0" \
  --form "uses_ffl=1" \
  --form "manufacturer_account_number=HX-MFG-91027" \
  --form "product_url=https://hendrixarmory.com/products" \
  --form "brand_url=https://hendrixarmory.com/brands" \
  --form "brand_signed_terms=1" \
  --form "store_tags[]=Veteran Owned" \
  --form "store_types[]=Sporting Goods" \
  --form "show_on_locator=1" \
  --form "show_stock_availability=1" \
  --form "show_website=1" \
  --form "is_promoted=0" \
  --form "custom_attributes[Account Number]=HX-ACCT-9812" \
  --form "custom_attributes[Billing ID]=99881" \
  --form "logo=@/path/to/logo.png" \
  --form "brand_terms_file=@/path/to/brand-terms.pdf"

Example response

{
  "data": {
    "id": 52,
    "account_id": "f17e10c3-a210-4a29-9f33-94f6017e6574",
    "name": "HENDRIX ARMORY",
    "friendly_name": "Hendrix Armory HQ",
    "logo_url": "https://example.com/logos/hendrix-armory.png",
    "phone": "9785550147",
    "email": "[email protected]",
    "website": "https://hendrixarmory.com",
    "store_pickup": true,
    "online_shopping": true,
    "allow_backorder": false,
    "low_stock_threshold": 8,
    "address_1": "425 ELM ST UNIT A",
    "address_2": "Suite 300",
    "address_3": "North Wing",
    "city": "STONEBRIDGE",
    "state": "TX",
    "postal_code": "75214",
    "country": "US",
    "timezone": "America/Chicago",
    "longitude": -96.7697,
    "latitude": 32.8072,
    "is_residential": false,
    "full_address": "425 ELM ST UNIT A, Suite 300, North Wing, STONEBRIDGE, TX 75214, US",
    "uses_ffl": true,
    "hours": [],
    "tags": [
      {
        "id": 5,
        "name": "Veteran Owned",
        "slug": "veteran-owned",
        "text": "Veteran Owned",
        "color": "#28a745",
        "icon": "flag"
      }
    ],
    "types": [
      {
        "id": 3,
        "name": "Sporting Goods",
        "slug": "sporting-goods",
        "text": "Sporting Goods",
        "color": "#fd7e14",
        "icon": "trophy"
      }
    ],
    "manufacturer_account_number": "HX-MFG-91027",
    "brand_terms_signed_at": "2024-05-20T09:45:00.000000Z",
    "show_on_locator": true,
    "show_stock_availability": true,
    "show_website": true,
    "custom_attributes": [
      {
        "id": 1,
        "company_attribute_id": 1,
        "company_attribute": {
          "id": 1,
          "name": "Account Number",
          "input_type": "text"
        },
        "value": "HX-ACCT-9812",
        "is_active": true
      },
      {
        "id": 2,
        "company_attribute_id": 2,
        "company_attribute": {
          "id": 2,
          "name": "Billing ID",
          "input_type": "text"
        },
        "value": "99881",
        "is_active": true
      }
    ],
    "is_promoted": false,
    "product_url": "https://hendrixarmory.com/products",
    "inventory_url": null,
    "brand_signed_terms": true,
    "brand_terms_file": {
      "id": 8,
      "name": "brand-terms.pdf",
      "file_name": "brand-terms.pdf",
      "mime_type": "ap_

Get a store

Retrieves the details of a specific store by its brand ID.

Endpoint: GET /api/manufacturers/stores/{account_id}

URL Parameters

account_id: The unique identifier of the store.

Example request

curl --request GET \
  --get "https://api-sandbox.buyingfreedom.app/api/manufacturers/stores/hendrix-armory" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

Example response

{
  "data": {
    "id": 301,
    "account_id": "e3721fd6-d3e2-4bc5-9270-52f91213b3c7",
    "name": "HENDRIX ARMORY",
    "friendly_name": "Hendrix Armory Flagship",
    "logo_url": "https://example.com/logos/hendrix-armory.png",
    "phone": "8005553210",
    "email": "[email protected]",
    "website": "https://hendrixarmory.com",
    "store_pickup": true,
    "online_shopping": true,
    "allow_backorder": false,
    "low_stock_threshold": 15,
    "address_1": "725 Mission Trail",
    "address_2": null,
    "address_3": null,
    "city": "Liberty Hill",
    "state": "TX",
    "postal_code": "78642",
    "country": "US",
    "timezone": "America/Chicago",
    "longitude": -97.7925,
    "latitude": 30.6648,
    "is_residential": false,
    "full_address": "725 Mission Trail, Liberty Hill, TX 78642, US",
    "uses_ffl": true,
    "hours": [
      {
        "id": 1,
        "company_id": 301,
        "day_of_week": 1,
        "open_time": "10:00:00",
        "close_time": "18:00:00",
        "is_closed": false,
        "special": false,
        "created_at": "2025-01-01T00:00:00.000000Z",
        "updated_at": "2025-01-01T00:00:00.000000Z"
      }
    ],
    "tags": [
      {
        "id": 1,
        "name": "Premium Store",
        "slug": "premium-store",
        "text": "Premium Store",
        "color": "#007bff",
        "icon": "star"
      }
    ],
    "types": [
      {
        "id": 1,
        "name": "Gun Store",
        "slug": "gun-store",
        "text": "Gun Store",
        "color": "#dc3545",
        "icon": "crosshairs"
      }
    ],
    "manufacturer_account_number": null,
    "brand_terms_signed_at": null,
    "show_on_locator": true,
    "show_stock_availability": true,
    "show_website": true,
    "custom_attributes": [],
    "is_promoted": false,
    "product_url": null,
    "inventory_url": null,
    "brand_signed_terms": false,
    "brand_terms_file": null,
    "created_at": "2025-01-01T00:00:00.000000Z",
    "updated_at": "2025-01-01T00:00:00.000000Z",
    "deleted_at": null
  }
}

Update a store

Updates store information for a specific brand. Some fields are immutable.

Endpoint: PUT /api/manufacturers/stores/{account_id}

Immutable fields

The following fields cannot be updated using this endpoint. If you include them in a request, they are ignored. To change these fields, contact your BFG representative.

name
friendly_name
address_1
address_2
address_3
city
state
postal_code
country
phone
ffl_license_number
email
website

URL parameters (mutable fields)

account_id: The unique identifier of the store.

Body parameters (mutable fields)

Field	Required	Description
`logo`	No	URL to the store’s logo image.
`store_pickup`	No	Indicates whether the store offers store pickup.
`online_shopping`	No	Indicates whether the store offers online shopping.
`auto_accept_order`	No	Whether orders are automatically accepted.
`low_stock_threshold`	No	The low stock threshold for inventory alerts.
`is_residential`	No	Set to `true` if the store is at a residential address.
`uses_ffl`	No	Set to `true` if the store uses FFL services.
`manufacturer_account_number`	No	The manufacturer account number.
`product_url`	No	The product URL. Must be valid. Maximum length: 255 characters.
`brand_url`	No	The brand URL. Must be valid. Maximum length: 255 characters.
`brand_signed_terms`	No	Set to `true` if brand terms have been signed.
`brand_terms_file`	No	Brand terms file upload. Must be a PDF file.
`store_tags`	No	Pipe-separated list of store tags.
`store_types`	No	Pipe-separated list of store types.
`show_on_locator`	No	Set to `true` to show the store in the locator.
`show_stock_availability`	No	Set to `true` to show stock levels.
`show_website`	No	Set to `true` to display the store website.
`is_promoted`	No	Set to `true` if the store is promoted.
`custom_attributes`	No	Pipe-separated custom attributes in `"Name: Value

Example request

curl --request PUT \
  "https://api-sandbox.buyingfreedom.app/api/manufacturers/stores/746c3a5b-9f92-4c02-8594-d3388f97fd13" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: multipart/form-data" \
  --header "Accept: application/json" \
  --form "ffl_license_number=982337001A00088" \
  --form "name=HENDRIX ARMORY" \
  --form "friendly_name=Hendrix Armory HQ" \
  --form "phone=8885552468" \
  --form "[email protected]" \
  --form "website=https://hendrixarmory.com" \
  --form "store_pickup=1" \
  --form "online_shopping=0" \
  --form "low_stock_threshold=15" \
  --form "address_1=725 Mission Trail" \
  --form "address_2=Building 2" \
  --form "address_3=Warehouse A" \
  --form "city=Liberty Hill" \
  --form "state=TX" \
  --form "postal_code=78642" \
  --form "country=US" \
  --form "is_residential=1" \
  --form "uses_ffl=1" \
  --form "manufacturer_account_number=MFG54321" \
  --form "product_url=https://hendrixarmory.com/catalog" \
  --form "brand_url=https://hendrixarmory.com/brands" \
  --form "brand_signed_terms=1" \
  --form "store_tags[]=Veteran Owned" \
  --form "store_types[]=Outdoor Store" \
  --form "show_on_locator=0" \
  --form "show_stock_availability=1" \
  --form "show_website=0" \
  --form "is_promoted=1" \
  --form "custom_attributes[Account Number]=DEF67890" \
  --form "custom_attributes[Billing ID]=99001" \
  --form "logo=@/private/tmp/phpXYZ1.png" \
  --form "brand_terms_file=@/private/tmp/phpXYZ2.pdf"

Example response

{
  "data": {
    "id": 301,
    "account_id": "bb12cd34-ef56-7890-ab12-cd34567890ef",
    "name": "HENDRIX ARMORY",
    "friendly_name": "Hendrix Armory HQ",
    "logo_url": "https://example.com/logos/hendrix-armory-updated.png",
    "phone": "8885552468",
    "email": "[email protected]",
    "website": "https://hendrixarmory.com",
    "store_pickup": true,
    "online_shopping": false,
    "allow_backorder": false,
    "low_stock_threshold": 15,
    "address_1": "725 Mission Trail",
    "address_2": "Building 2",
    "address_3": "Warehouse A",
    "city": "Liberty Hill",
    "state": "TX",
    "postal_code": "78642",
    "country": "US",
    "timezone": "America/Chicago",
    "longitude": -97.7925,
    "latitude": 30.6648,
    "is_residential": true,
    "full_address": "725 Mission Trail, Building 2, Warehouse A, Liberty Hill, TX 78642, US",
    "uses_ffl": true,
    "hours": [],
    "tags": [
      {
        "id": 3,
        "name": "Veteran Owned",
        "slug": "veteran-owned",
        "text": "Veteran Owned",
        "color": "#28a745",
        "icon": "flag"
      }
    ],
    "types": [
      {
        "id": 2,
        "name": "Outdoor Store",
        "slug": "outdoor-store",
        "text": "Outdoor Store",
        "color": "#28a745",
        "icon": "tree"
      }
    ],
    "manufacturer_account_number": "MFG54321",
    "brand_terms_signed_at": "2025-01-20T14:45:00.000000Z",
    "show_on_locator": false,
    "show_stock_availability": true,
    "show_website": false,
    "custom_attributes": [
      {
        "id": 1,
        "company_attribute_id": 1,
        "company_attribute": {
          "id": 1,
          "name": "Account Number",
          "input_type": "text"
        },
        "value": "DEF67890",
        "is_active": true
      },
      {
        "id": 2,
        "company_attribute_id": 2,
        "company_attribute": {
          "id": 2,
          "name": "Billing ID",
          "input_type": "text"
        },
        "value": "99001",
        "is_active": true
      }
    ],
    "is_promoted": true,
    "product_url": "https://hendrixarmory.com/catalog",
    "inventory_url": "https://hendrixarmory.com/inventory",
    "brand_signed_terms": true,
    "brand_terms_file": {
      "id": 2,
      "name": "updated-brand-terms.pdf",
      "file_name": "updated-brand-terms.pdf",
      "mime_type": "application/pdf",
      "size": 2048000,
      "url": "https://example.com/media/agreements/updated-brand-terms.pdf"
    },
    "created_at": "2024-01-01T00:00:00.000000Z",
    "updated_at": "2025-08-14T12:00:00.000000Z",
    "deleted_at": null
  },
  "status": "SUCCESS",
  "partial_update": true,
  "updated_fields": [
    "logo",
    "low_stock_threshold",
    "is_residential",
    "manufacturer_account_number",
    "product_url",
    "brand_url",
    "brand_signed_terms",
    "store_tags",
    "store_types",
    "custom_attributes"
  ],
  "ignored_fields": [
    "name",
    "email",
    "phone",
    "website",
    "address_1",
    "city",
    "state",
    "postal_code",
    "country"
  ],
  "message": "Some fields are immutable. Check the ignored_fields for more details.",
  "warnings": []
}