Skip to main content
GET
/
product
Search Products
curl --request GET \
  --url https://api.satsuma.ai/product \
  --header 'Authorization: <api-key>'
{
  "data": [
    {
      "id": "<string>",
      "merchant_id": "<string>",
      "sku": "<string>",
      "name": "<string>",
      "description": "<string>",
      "brand": "<string>",
      "category": {
        "id": "<string>",
        "merchant_id": "<string>",
        "name": "<string>",
        "level": "Department",
        "depth": 123
      },
      "upc": "<string>",
      "image_url": "<string>",
      "discount_price": 123,
      "tags": [
        "<string>"
      ],
      "status": "Active",
      "currency": "<string>",
      "price": 123,
      "fulfillment_methods": [
        "Delivery"
      ],
      "location": {
        "id": "<string>",
        "merchant_id": "<string>",
        "name": "<string>",
        "type": "Store",
        "latitude": 123,
        "longitude": 123
      }
    }
  ],
  "messages": [
    {
      "context": "<string>",
      "level": "Information",
      "text": "<string>",
      "data": {}
    }
  ]
}

Authorizations

​
Authorization
string
header
required

API Key authentication

Query Parameters

​
merchantId
string

Unique identifier of the merchant to search within. If not provided, searches across all merchants api.product.search.field.merchantId.description

​
query
string

Free-text search query to match against product names, descriptions, brands, or keywords api.product.search.field.query.description

Example:

"organic coffee beans"

​
locationId
string

Specific location identifier to limit search scope. Can be a store ID, warehouse ID, etc. api.product.search.field.locationId.description

​
locationType
enum<string>[]

List of location types to filter search results. Restricts search to specified location types only api.product.search.field.locationType.description

api.product.search.field.locationType.description

Available options:
Store,
Warehouse
​
category
string

Product category name or identifier to narrow search results to specific product categories api.product.search.field.category.description

Example:

"beverages"

​
brand
string

Brand identifier or name to filter products by specific brand. Can accept either brand ID or brand name api.product.search.field.brand.description

Example:

"Nike"

​
minQuantity
integer<int32>

Minimum inventory quantity required. Products with quantity below this threshold will be excluded api.product.search.field.minQuantity.description

Required range: x >= 0
Example:

5

​
upc
string

Universal Product Code (UPC) for precise product identification api.product.search.field.upc.description

​
productId
string

Product ID filter - exact match for specific product

Example:

"product123"

​
fulfillmentMethod
enum<string>[]

List of acceptable fulfillment methods to filter products by availability and delivery options api.product.search.field.fulfillmentMethod.description

api.product.search.field.fulfillmentMethod.description

Available options:
Delivery,
Pickup,
Shipping
​
size
integer<int32>
default:25

Maximum number of products to return in a single response. Used for pagination control api.product.search.field.size.description

Required range: 1 <= x <= 100
Example:

25

​
page
integer<int32>
default:1

Page number for paginated results, starting from 1. Used with 'size' parameter for pagination api.product.search.field.page.description

Required range: x >= 1
Example:

1

​
latitude
number<double>
required

Geographic latitude coordinate for proximity search. Must be a valid latitude between -90 and 90 degrees api.search.field.latitude.description

Required range: -90 <= x <= 90
Example:

37.7749

​
longitude
number<double>
required

Geographic longitude coordinate for proximity search. Must be a valid longitude between -180 and 180 degrees api.search.field.longitude.description

Required range: -180 <= x <= 180
Example:

-122.4194

​
distance
string
default:10mi

Search radius distance from the provided coordinates. Format: number followed by unit (mi for miles, km for kilometers) api.search.field.distance.description

Example:

"10mi"

Response

200 - application/json

OK

​
data
object[]
​
messages
object[]