Product inventories

Product inventories are records that link a specific product (identified by its UPC code) to a quantity available for sale or use. These records are tied to a specific account in BFG and are used to determine real-time stock status for each product.

Note: Make sure you know the UPCs of the products you want to update.

Product stock statuses

Based on the specified low stock threshold of a product in BFG and your updates, a product can have the following stock statuses:

In Stock: The product quantity is above the low stock threshold.
Low Stock: The product quantity meets or is below the low stock threshold.
Out of Stock: The product quantity is zero.
Call for Availability: Inventory data is unavailable.

These statuses are then displayed in a Product type store locator. For details, go to Real-time store locator.

Get a product inventory

Use this endpoint to retrieve the inventory details for a specific product, including optional retailer metadata.

Endpoint: GET /api/product-inventories/{upc_code}

URL parameters

upc_code: Required. The UPC of the product for retrieving inventory information.

Body parameters

Name	Required	Description
`include_product`	No	If true, returns full product data in the response.
`class`	No	Specifies the classification or category type to filter inventory results.

Example request

curl --request GET \
  --get "https://api-sandbox.buyingfreedom.app/api/product-inventories/031234567890" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "include_product": true,
    "class": "lighting"
}'

Note: Replace the product-inventories/{upc} path parameter with the correct UPC for the product you want to query.

Example response

{
  "data": {
    "retailer_id": 14,
    "location_code": "BRIGHTLITE_RETAIL_OUTLET",
    "retailer": {
      "id": 14,
      "account_id": "6e3f89c2-3bc1-4988-92f3-cd304c6f92ba",
      "name": "BrightLite Distributors",
      "logo_url": "https://bfg-atlas-dev.s3.amazonaws.com/companies/files/brightlite-logo.png",
      "phone": "555-908-4321",
      "email": "[email protected]",
      "website": "https://www.brightlite.io/",
      "address_1": "2487 Beacon Trail",
      "address_2": "Suite 5B",
      "address_3": null,
      "city": "Clearwater",
      "state": "FL",
      "postal_code": "33755",
      "country": "US",
      "latitude": "27.965853",
      "longitude": "-82.800102",
      "self_verified": true,
      "bfg_verified": true,
      "manufacturer": false,
      "retailer": true,
      "distributor": true,
      "uses_corestore": true,
      "uses_store_locator": false,
      "ffl_license_number": null,
      "ffl_expiration_date": null,
      "created_at": "2025-01-03T05:12:53.000000Z",
      "updated_at": "2025-01-03T05:12:53.000000Z",
      "deleted_at": null
    },
    "quantity": 87,
    "location_cost": "129.50"
  }
}

Update a product inventory

Use this endpoint to update the quantity of a single product in your inventory.

Endpoint: PUT /api/product-inventories/{upc_code}

URL parameters

upc_code: Required. The UPC code of the product.

Body parameters

Name	Required	Description
`quantity`	Yes	The new quantity to set.
`account_id`	Yes	The store account_id retrieved from the `POST api/store-locator/register` endpoint.

Example request

curl --request PUT \
  "https://api-sandbox.buyingfreedom.app/api/product-inventories/038472915084" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "quantity": 20,
    "account_id": "a4f1b8de-81d7-4d25-91ce-7c6d5e892e7b"
}'

Note: In this example, the product inventory being updated has a UPC of 038472915084. Replace this value with the correct identifier in your environment.

Example response

{
  "message": "Product inventory updated successfully."
}

Bulk update product inventories

Use this endpoint to update multiple product inventories of a store in a single request. This is helpful for syncing large datasets or doing bulk corrections.

Endpoint: PUT /api/product-inventories

Body parameters

Name	Required	Description
`product_inventories`	Yes	An array of objects containing `upc` and `quantity`.
`account_id`	Yes	`account_id` retrieved from the `Register a Store` API.

Each item in the product_inventories array must include the following:

Field	Required	Description
`upc`	Yes	The product UPC.
`quantity`	Yes	The new quantity value.

Example request

curl --request PUT \
  "https://api-sandbox.buyingfreedom.app/api/product-inventories" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "product_inventories": [
      {
        "upc": "017398807050",
        "quantity": 50
      },
      {
        "upc": "017398805056",
        "quantity": 35
      }
    ],
    "account_id": "ed7f4700-c85b-4813-b864-9dae807438b0"
}'

Note: Use this endpoint to update multiple inventory records in a single request. Each UPC must be valid and associated with the given account.

Example response

{
  "data": {
    "skipped_records": [
      {
        "upc": "095783204918",
        "reason": "Product not found."
      }
    ]
  },
  "message": "Product inventories updated successfully."
}