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

​
query
string

Free-text search query to match against product names, descriptions, brands, or keywords

Example:

"organic coffee beans"

​
locationId
string

Specific location identifier to limit search scope. Can be a store ID, warehouse ID, etc.

​
locationType
enum<string>[]

List of location types to filter search results. Restricts search to specified location types only

​
category
string

Product category name or identifier to narrow search results to specific product categories

Example:

"beverages"

​
brand
string

Brand identifier or name to filter products by specific brand. Can accept either brand ID or brand name

Example:

"Nike"

​
minQuantity
integer

Minimum inventory quantity required. Products with quantity below this threshold will be excluded

Required range: x >= 0
Example:

5

​
upc
string

Universal Product Code (UPC) for precise product identification

​
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

​
size
integer
default:25

Maximum number of products to return in a single response. Used for pagination control

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

25

​
page
integer
default:1

Page number for paginated results, starting from 1. Used with 'size' parameter for pagination

Required range: x >= 1
Example:

1

​
latitude
number
required

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

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

37.7749

​
longitude
number
required

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

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)

Example:

"10mi"

Response

200 - application/json

OK

​
data
object[]
​
messages
object[]
⌘I