Skip to main content
GET
/
api
/
commerce
/
search
Search for products
curl --request GET \
  --url https://api-beta.pepay.io/api/commerce/search \
  --header 'x-commerce-api-key: <api-key>'
{
  "success": true,
  "data": {
    "products": [
      {
        "productId": "B000NPYY04",
        "title": "Nature's Bounty Fish Oil, 1200 mg Omega-3, 200 Rapid Release Softgels",
        "price": 12.48,
        "image": "https://images-na.ssl-images-amazon.com/images/I/51KGjV22PWL._AC_US218_.jpg",
        "rating": 4.5,
        "reviewCount": 395,
        "fresh": false,
        "retailer": "amazon",
        "url": "https://www.amazon.com/dp/B000NPYY04"
      }
    ],
    "pagination": {
      "page": 1,
      "totalPages": 8,
      "totalResults": 150,
      "hasNext": true
    },
    "query": "wireless headphones",
    "retailer": "amazon"
  },
  "meta": {
    "timestamp": "2025-01-30T12:34:56.789Z",
    "cacheStats": {}
  }
}

​
Overview

Use this endpoint to search Commerce inventory and build a product browsing experience.

​
Authentication

Commerce search requires a commerce-scoped API key (see Commerce API Keys).

​
Request

​
SDK

const results = await pepay.commerce.search({ q: 'wireless headphones', limit: 10 });

​
cURL

curl "https://api-beta.pepay.io/api/commerce/search?q=wireless%20headphones&limit=10" \
  -H "x-commerce-api-key: ck_..."

​
Response

{
  "success": true,
  "data": {
    "products": [
      {
        "productId": "B000NPYY04",
        "title": "Wireless Headphones",
        "price": 129.99,
        "image": "https://images.example.com/product.png"
      }
    ]
  }
}

​
Errors

  • 400 invalid search parameters
  • 401 missing/invalid commerce auth

​
Examples

  • Build “search → cart → checkout” flows using the adjacent Commerce endpoints in the sidebar. Next: Create a checkout invoice

Authorizations

​
x-commerce-api-key
string
header
required

Legacy alias for commerce-scoped API keys. Prefer x-api-key with scope=commerce.

Query Parameters

​
q
string
required

Search query (1-200 characters)

Required string length: 1 - 200
​
page
integer
default:1

Page number for pagination (1-100)

Required range: 1 <= x <= 100
​
retailer
enum<string>
default:amazon

Retailer to search (currently only Amazon supported)

Available options:
amazon,
walmart
​
minPrice
number<float>

Minimum price filter in USD

Required range: x >= 0
​
maxPrice
number<float>

Maximum price filter in USD

Required range: x >= 0

Response

Search results with pagination info

​
success
boolean
Example:

true

​
data
object
​
meta
object