Product management

Access and manage product data in your BFG catalog through the API.

Products in BFG represent catalog items that are available for sale, distribution, or promotion. Each product includes structured metadata such as title, UPC, SKU, model number, pricing, media, and tags. These can be connected to inventory and promotional pricing logic. Product records are scoped to your brand and retrieved through the API.

List products

Use this endpoint to get a paginated list of products associated with your company. List products supports extensive filtering and optional inclusion of related metadata such as categories, tags, and inventories.

Endpoint: GET /api/products

Query parameters

Name	Required	Description
`sort`	No	Sorts the products.
`page`	No	Sets the page number.
`page_size`	No	Sets the number of results per page.
`include`	No	Comma-separated list of related resources to include (e.g., `tags`, `categories`).
`filter[field]`	No	Filters results by specific fields (e.g., `title`).
`filter[trashed]`	No	Includes soft-deleted records. Values: `with`, `only`, or `without`.
`include_inventory`	No	If set to `1`, returns inventory information with each product.
`filter[with_inventory]`	No	Filters for products that have inventory (`1`) or not (`0`).
`filter[retailer_ids]`	No	Filters by one or more retailer IDs.
`filter[inventory_sources]`	No	Filters by inventory source IDs.
`filter[product_ids]`	No	Filters by specific product IDs.
`filter[has_images]`	No	Filters by image presence.
`filter[has_categories]`	No	Filters by category assignment.
`filter[has_description]`	No	Filters by description presence.
`filter[has_facets]`	No	Filters by facet assignment.
`filter[has_manufacturer]`	No	Filters by valid manufacturer.
`filter[upc_valid]`	No	Filters by UPC validity.

Example request

curl --request GET \
  --get "https://api-sandbox.buyingfreedom.app/api/products?sort=-title&page=2&page_size=20&include=%60tags%60%2C+%60categories%60%2C+%60manufacturerCategories%60&filter%5Bfield%5D=Battery&filter%5Btrashed%5D=with&include_inventory=1&filter%5Bwith_inventory%5D=1&filter%5Bretailer_ids%5D[]=12&filter%5Bretailer_ids%5D[]=18&filter%5Bretailer_ids%5D[]=21&filter%5Binventory_sources%5D[]=12&filter%5Binventory_sources%5D[]=18&filter%5Binventory_sources%5D[]=21&filter%5Bproduct_ids%5D[]=101&filter%5Bproduct_ids%5D[]=102&filter%5Bproduct_ids%5D[]=103&filter%5Bhas_images%5D=1&filter%5Bhas_categories%5D=&filter%5Bhas_description%5D=1&filter%5Bhas_facets%5D=&filter%5Bhas_manufacturer%5D=1&filter%5Bupc_valid%5D=" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

Example response

{
  "data": [
    {
      "id": 101,
      "company_id": 201,
      "company": {
        "name": "Zephyr Components Inc.",
        "account_id": "ba12f4dc-994e-41b8-afa7-1a2345fc91bc"
      },
      "title": "Zephyr Lithium Battery Pack – 2600mAh",
      "description": "A compact, high-performance battery pack designed for reliable power delivery.",
      "upc": "031234567890",
      "sku": "ZPH-2600",
      "model_number": "ZPH-LB2600",
      "msrp_price": "34.99",
      "map_price": "31.49",
      "current_map_price": null,
      "upp_price": "29.99",
      "mtp_price": "27.99",
      "map_promotions": [
        {
          "id": 202,
          "title": "End-of-Season Promo",
          "description": "MAP Holiday for Zephyr Batteries",
          "promotion_type": "MAP_HOLIDAY",
          "promotion_value": null
        }
      ],
      "inventories": [
        {
          "retailer_id": 18,
          "retailer": {
            "name": "Northlight Industrial",
            "account_id": "9d8a10ff-1847-4c21-b772-312fcd9f04a2",
            "longitude": "-115.143",
            "latitude": "36.1699"
          },
          "location_code": "NORTHLIGHT_WEST",
          "quantity": 85,
          "location_cost": "25.00"
        },
        {
          "retailer_id": 21,
          "retailer": {
            "name": "PowerCore Supply Co.",
            "account_id": "e32175b4-24b2-4c9c-bda3-45d23f651ef1",
            "longitude": "-87.6298",
            "latitude": "41.8781"
          },
          "location_code": "PWRCORE_CHI",
          "quantity": 23,
          "location_cost": "28.00"
        }
      ],
      "created_at": "2024-01-13T11:52:18.000000Z",
      "updated_at": "2024-01-13T11:52:18.000000Z",
      "deleted_at": null
    },
    {
      "id": 102,
      "company_id": 202,
      "company": {
        "name": "Nexgen Mobility",
        "account_id": "b65dcd90-4c72-47ee-b4e0-92d6c5f014e0"
      },
      "title": "Nexgen USB-C Rechargeable Power Cell – 3200mAh",
      "description": "Rechargeable USB-C battery cell optimized for compact electronic devices.",
      "upc": "098765432109",
      "sku": "NGN-3200",
      "model_number": "NG-USB3200",
      "msrp_price": "39.99",
      "map_price": "35.99",
      "current_map_price": "33.99",
      "upp_price": "32.99",
      "mtp_price": "30.99",
      "map_promotions": [
        {
          "id": 203,
          "title": "Tech Bundle Sale",
          "description": "20% off Nexgen mobile accessories",
          "promotion_type": "PERCENTAGE_BELOW_MAP",
          "promotion_value": null
        }
      ],
      "inventories": [],
      "created_at": "2024-01-13T11:52:23.000000Z",
      "updated_at": "2024-01-13T11:52:23.000000Z",
      "deleted_at": null
    }
  ],
  "links": {
    "first": "http://127.0.0.1:8000/api/products?page=1",
    "last": "http://127.0.0.1:8000/api/products?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "« Previous",
        "active": false
      },
      {
        "url": "http://127.0.0.1:8000/api/products?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next »",
        "active": false
      }
    ],
    "path": "http://127.0.0.1:8000/api/products",
    "per_page": 10,
    "to": 2,
    "total": 2
  }
}

Note: For best results, ensure that your integration supports pagination, filtering, and optional includes (like categories, tags, or inventories) when calling the List products API.

Get a product

Use this endpoint to retrieve full details for a specific product, including its media assets, pricing, inventory, and metadata.

Endpoint: GET /api/products/{product_id}

URL parameters

product_id: Required. The unique identifier of the product.

Example request

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

Example response

{
  "data": {
    "id": 42,
    "company_id": 301,
    "company": {
      "name": "Skyline Dynamics",
      "account_id": "ae9c12f3-9b4e-41a0-8f02-3d5b9e41cb44"
    },
    "title": "Skyline UltraFlash 2000 Rechargeable Flashlight",
    "description": "A compact, high-lumen flashlight with durable housing and USB-C fast charging.",
    "upc": "098761234509",
    "sku": "SKY-UF2000",
    "model_number": "UF-2000-X",
    "msrp_price": "59.99",
    "map_price": "54.99",
    "current_map_price": null,
    "upp_price": "52.99",
    "mtp_price": "49.99",
    "manufacturer_part_number": null,
    "gtin": null,
    "ein": null,
    "series": null,
    "long_description": null,
    "is_serialized": false,
    "requires_ffl": false,
    "discontinued_date": null,
    "published_date": null,
    "medias": [
      {
        "id": 78,
        "product_id": 42,
        "sort": 0,
        "path": "products/medias/1743069999-ultraflash-front.jpg",
        "filename": "ultraflash-front",
        "size": 44512,
        "extension": "jpg",
        "type": "image",
        "media_url": "https://bfg-atlas-dev.s3.amazonaws.com/products/medias/1743069999-ultraflash-front.jpg"
      },
      {
        "id": 79,
        "product_id": 42,
        "sort": 1,
        "path": "products/medias/1743070000-ultraflash-demo.webm",
        "filename": "ultraflash-demo",
        "size": 7853210,
        "extension": "webm",
        "type": "video",
        "media_url": "https://bfg-atlas-dev.s3.amazonaws.com/products/medias/1743070000-ultraflash-demo.webm"
      }
    ],
    "map_promotions": [
      {
        "id": 3001,
        "title": "Spring Lighting Deal",
        "description": "MAP Holiday for Skyline Flashlights",
        "promotion_type": "MAP_HOLIDAY",
        "promotion_value": null
      }
    ],
    "total_quantity": null,
    "tags": [
      {
        "id": 12,
        "name": "Flashlight",
        "description": null,
        "created_at": "2025-04-28T08:54:17.000000Z",
        "updated_at": "2025-04-28T08:56:18.000000Z",
        "deleted_at": null
      }
    ],
    "categories": [
      {
        "id": 24,
        "name": "Outdoor Gear",
        "description": null,
        "created_at": "2025-04-28T06:33:21.000000Z",
        "updated_at": "2025-04-28T08:55:53.000000Z",
        "deleted_at": null
      }
    ],
    "manufacturerCategories": [
      {
        "id": 30,
        "name": "Lighting Equipment",
        "description": null,
        "created_at": "2025-04-28T09:57:52.000000Z",
        "updated_at": "2025-04-28T09:57:52.000000Z",
        "deleted_at": null
      }
    ],
    "created_at": "2024-01-13T11:52:18.000000Z",
    "updated_at": "2024-01-13T11:52:18.000000Z",
    "deleted_at": null
  }
}

Updated 3 months ago