# Costco Search API Documentation
Costco Search API searches products on costco.com and costco.ca. Each item has the warehouse price, the delivery price range, the original price, availability, the member-only flag, rating, categories and images. The answer lists facets (brands, categories, ratings, price ranges) for the query.
Prices and stock depend on the warehouse. Pass warehouse (a number from the warehouses route) to see one warehouse. The default is a New York warehouse for the US and a Toronto warehouse for Canada.
Some plain words, such as tv or mattress, lead to a category page on costco.com. For these words the search shows the products of that category and names it in browsed_category. Words that lead to other sites (tires, travel, pharmacy) return an empty free list.
Every item is checked against your filters. Rows that break a filter are dropped and counted in meta.filtered_out. A page past the end is an empty list with the total. Sort price_desc follows the delivery price, so neighbours can be slightly out of order. Costs 1 credit per successful request. Empty results and failed requests are free.
- **Documentation:** [https://scrappa.co/docs/costco-api/costco_search](https://scrappa.co/docs/costco-api/costco_search)
- **API group:** Costco API
- **Endpoint:** `GET https://scrappa.co/api/costco/search`
## Authentication
Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | Yes | Search text, 1 to 120 characters, for example laptop. |
| `country` | string | No | us (default) or ca. Selects costco.com or costco.ca. |
| `locale` | string | No | en-US, en-CA or fr-CA. Canadian French works with country ca. Default is the English locale of the country. |
| `page` | integer | No | One-based page number, 1 to 500 (default 1). |
| `per_page` | integer | No | Results per page, 1 to 100 (default 24). |
| `sort` | string | No | relevance (default), price_asc, price_desc or rating_desc. |
| `brand` | string | No | Brand name. Send a comma separated list for several brands. |
| `min_rating` | integer | No | Only items rated at least this many stars, 1 to 5. |
| `min_price` | number | No | Lowest warehouse price. Works alone or together with max_price. |
| `max_price` | number | No | Highest warehouse price. Works alone or together with min_price. |
| `category` | string | No | Category path as listed in item categories, for example Computers > Laptops. |
| `in_stock` | boolean | No | true (default) hides out-of-stock items. false shows them. |
| `warehouse` | string | No | Warehouse number whose price and stock to show, for example 243. |
## Example response
```json
{
"data": {
"page": 1,
"items": [
{
"id": "4201023303",
"url": "https://www.costco.com/p/-/hp-omnibook-3-14-next-gen-ai-laptop---qualcomm-snapdragon-x---copilot-pc---2k-oled-1920-x-1200---16gb-memory---512gb-ssd---windows-11-home/4201023303",
"brand": "HP",
"image": "https://gdx-assets.costco.com/adobe/assets/urn:aaid:aem:58667bdf-c724-4fc8-925b-a5d1b7f05e80/as/4201023303-847__1.avif?width=350&height=350&fit=contain",
"model": "14-hz0288cl",
"price": {
"currency": "USD",
"original": 799.99,
"warehouse": 799.99,
"delivery_max": 799.99,
"delivery_min": 799.99
},
"title": "HP OmniBook 3 14\" Next Gen AI Laptop - Qualcomm Snapdragon X - Copilot+ PC - 2K OLED (1920 x 1200) - 16GB Memory - 512GB SSD - Windows 11 Home.",
"rating": {
"count": 2,
"average": 5
},
"features": [
"Integrated Webcam"
],
"position": 1,
"categories": [
"Computers",
"Computers > Laptops"
],
"promotions": [],
"member_only": false,
"availability": {
"delivery": "LOW_STOCK",
"warehouse": "LOW_STOCK"
},
"delivery_type": "Warehouse Pick-up",
"program_types": [
"3rdPartyDelivery",
"SiteControlledInventory",
"InWarehouse",
"Standard",
"WarehouseDelivery",
"ShipIt"
],
"promotional_statement": null
},
{
"id": "4000061905",
"url": "https://www.costco.com/p/-/lenovo-legion-5-153-gaming-laptop----ryzen-ai-9-465---geforce-rtx-5070---wqxga-2560-x-1600---32gb-ram---1tb-ssd----windows-11-home/4000061905",
"brand": "Lenovo",
"image": "https://gdx-assets.costco.com/adobe/assets/urn:aaid:aem:8d07a4b0-c3c1-469f-98b4-8aa10eea3a8b/as/4000061905-847__1.avif?width=350&height=350&fit=contain",
"model": "83Q6003BUS",
"price": {
"currency": "USD",
"original": 2599.99,
"warehouse": 2599.99,
"delivery_max": 2599.99,
"delivery_min": 2599.99
},
"title": "Lenovo Legion 5 15.3\" Gaming Laptop - Ryzen AI 9 465 - GeForce RTX 5070 - WQXGA (2560 x 1600) - 32GB RAM - 1TB SSD - Windows 11 Home.",
"rating": {
"count": 4,
"average": 5
},
"features": [
"Integrated Webcam",
"Backlit Keyboard",
"Gaming"
],
"position": 2,
"categories": [
"Computers",
"Computers > PC Gaming",
"Computers > PC Gaming > Gaming Laptops"
],
"promotions": [],
"member_only": false,
"availability": {
"delivery": "LOW_STOCK",
"warehouse": "LOW_STOCK"
},
"delivery_type": "Warehouse Pick-up",
"program_types": [
"3rdPartyDelivery",
"GoogleGrocery",
"SiteControlledInventory",
"InWarehouse",
"Standard",
"WarehouseDelivery",
"ShipIt"
],
"promotional_statement": null
},
{
"id": "4000446283",
"url": "https://www.costco.com/p/-/lenovo-ideapad-slim-5i-16-touchscreen-laptop---intel-core-ultra-7-355---wuxga-1920-x-1200---16gb-ram----1tb-ssd---windows-11-home/4000446283",
"brand": "Lenovo",
"image": "https://gdx-assets.costco.com/adobe/assets/urn:aaid:aem:20f1ff9c-b1fe-4271-8df7-f8682521f3a1/as/4000446283-847__1.avif?width=350&height=350&fit=contain",
"model": "83S6000BUS",
"price": {
"currency": "USD",
"original": 1299.99,
"warehouse": 1299.99,
"delivery_max": 1299.99,
"delivery_min": 1299.99
},
"title": "Lenovo IdeaPad Slim 5i 16\" Touchscreen Laptop - Intel Core Ultra 7 355 - WUXGA 1920 x 1200 - 16GB RAM - 1TB SSD - Windows 11 Home.",
"rating": {
"count": 1,
"average": 5
},
"features": [
"Backlit Keyboard",
"Integrated Webcam",
"Numeric Keypad",
"Touchscreen"
],
"position": 3,
"categories": [
"Computers",
"Computers > Laptops",
"Computers > Laptops > Windows Laptops"
],
"promotions": [],
"member_only": false,
"availability": {
"delivery": "LOW_STOCK",
"warehouse": "LOW_STOCK"
},
"delivery_type": "Warehouse Pick-up",
"program_types": [
"3rdPartyDelivery",
"GoogleGrocery",
"SiteControlledInventory",
"InWarehouse",
"Standard",
"WarehouseDelivery",
"ShipIt"
],
"promotional_statement": null
}
],
"query": "laptop",
"facets": [
{
"key": "price",
"values": [
{
"max": 50,
"min": 25,
"count": 2
},
{
"max": 100,
"min": 50,
"count": 4
},
{
"max": 500,
"min": 200,
"count": 3
}
]
},
{
"key": "rating",
"values": [
{
"max": 5,
"min": 1,
"count": 32
},
{
"max": 5,
"min": 2,
"count": 29
},
{
"max": 5,
"min": 3,
"count": 21
}
]
},
{
"key": "brands",
"values": [
{
"count": 3,
"value": "Acer"
},
{
"count": 2,
"value": "Allstate"
},
{
"count": 1,
"value": "Anker"
}
]
},
{
"key": "categories",
"values": [
{
"count": 35,
"value": "Computers"
},
{
"count": 2,
"value": "Computers > Desktop Computers & PCs"
},
{
"count": 1,
"value": "Computers > Desktop Computers & PCs > Computer Towers"
}
]
}
],
"country": "us",
"per_page": 3,
"warehouse": "243",
"has_next_page": true,
"total_results": 39,
"corrected_query": null,
"browsed_category": null
},
"meta": {
"credits": 1,
"billable": true,
"filtered_out": 0,
"endpoint_family": "search"
},
"success": true
}
```
## Errors
| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A required parameter or a value is invalid. This response is not billable. |
| 503 | Upstream Unavailable | Costco could not be reached after several tries. This response is not billable. Retry shortly. |
## More Scrappa resources
- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)