# Costco Product

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/costco/product` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/costco-product |

## Description

Costco Product API: fetch full product page data from a product ID or URL across regional Costco sites. Returns pricing, availability, ratings, images and breadcrumbs via browser rendering.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/costco/product' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Product 4000266385 on costco.com

```json
{
  "url": "https://www.costco.com/p/-/mohawk-home-6mm-thick-94in-x-478in-22-mil-waterproof-luxury-vinyl-plank-flooring-1565-sq-ftctn/4000266385",
  "name": "Mohawk Home 6MM Thick 9.4in X 47.8in 22 MIL Waterproof Luxury Vinyl Plank Flooring (15.65 sq ft/ctn)",
  "brand": "Mohawk Home",
  "price": 47.99,
  "images": [
    "https://bfasset.costco-static.com/U447IH35/as/44xhpxq9ttr6nhpr4trsx53/4000266385-847_bloomingtonoak_1?auto=webp&format=jpg",
    "https://bfasset.costco-static.com/U447IH35/as/6wxn2893r8g35r5p98jnkw2v/4000266385-847_tudoroak_1?auto=webp&format=jpg&width=727&height=727&fit=bounds&canvas=727%2C727"
  ],
  "rating": 3.68,
  "region": "www.costco.com",
  "currency": "USD",
  "image_url": "https://bfasset.costco-static.com/U447IH35/as/44xhpxq9ttr6nhpr4trsx53/4000266385-847_bloomingtonoak_1?auto=webp&format=jpg",
  "product_id": "4000266385",
  "breadcrumbs": [
    "Home Improvement",
    "Flooring",
    "Vinyl Flooring"
  ],
  "description": "SplashDefense® 100% Waterproof and Water-tight Joints;CleanProtect® Technology with Antimicrobial Properties Built in to Protect the Floor;Wide Plank Vinyl Flooring, 5mm Thick Plank + 1mm Attached Pad for Fast, Easy Installation and No Underlayment Required",
  "item_number": "1806569",
  "availability": "in_stock",
  "review_count": 84
}
```

## Documentation

## Overview
The **Costco Product API** returns full product page data from [Costco](https://www.costco.com) regional sites. Pass a **numeric product ID**, a **full product URL**, or an ID with **`region`** and receive structured JSON with pricing, availability, ratings, images, and breadcrumbs.

Piloterr uses **browser rendering** (`wait_for=#costco-consent-manager`) and parses Next.js RSC `productDetailsData`, JSON-LD `Product`, and DOM stock status.

## Supported regions
| Code | Host | Search path | Page param |
|---|---|---|---|
| `us` / `com` | www.costco.com | `/s?keyword=` | `currentPage` |
| `fr` | www.costco.fr | `/s?keyword=` | `currentPage` |
| `es` | www.costco.es | `/s?keyword=` | `currentPage` |
| `mx` | www.costco.com.mx | `/s?keyword=` | `currentPage` |
| `kr` | www.costco.co.kr | `/s?keyword=` | `currentPage` |
| `tw` | www.costco.com.tw | `/s?keyword=` | `currentPage` |
| `jp` | www.costco.co.jp | `/s?keyword=` | `currentPage` |
| `au` | www.costco.com.au | `/s?keyword=` | `currentPage` |
| `is` | www.costco.is | `/s?keyword=` | `currentPage` |
| `nz` | www.costco.co.nz | `/s?keyword=` | `currentPage` |
| `se` | www.costco.se | `/s?keyword=` | `currentPage` |
| `ca` | www.costco.ca | `/CatalogSearch?keyword=` | `currentPage` |
| `uk` | www.costco.co.uk | `/search?text=` | `page` |

CA and UK use dedicated search URL formats; other regions follow the US-like `/s?keyword=` pattern.

## Quickstart
```
GET https://api.piloterr.com/v2/costco/product?query=4000266385
GET https://api.piloterr.com/v2/costco/product?query=4000268598&region=ca
GET https://api.piloterr.com/v2/costco/product?query=https://www.costco.com/p/-/mohawk-home-6mm-thick-94in-x-478in-22-mil-waterproof-luxury-vinyl-plank-flooring-1565-sq-ftctn/4000266385
```

Via POST:
```
POST https://api.piloterr.com/v2/costco/product
Content-Type: application/json

{"query": "4000266385", "region": "us", "return_page_source": false}
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Product ID or full regional product URL |
| `region` | string | no | Region code or host when `query` is a numeric ID only (default: US) |
| `return_page_source` | boolean | no | Raw HTML as `{"result": "..."}` (default: `false`) |

## Response fields
| Field | Type | Description |
|---|---|---|
| `product_id` | string | Catalog product ID |
| `item_number` | string \| null | Selected item / SKU number |
| `name` | string | Product title |
| `url` | string | Canonical product URL |
| `brand` | string \| null | Brand (JSON-LD) |
| `description` | string \| null | Long description / features (RSC, `;`-separated) |
| `image_url` | string \| null | First image (`images[0]`) |
| `images` | string[] \| null | All image URLs found |
| `price` | number \| null | Online display price |
| `currency` | string \| null | ISO 4217 code |
| `availability` | string \| null | e.g. `in_stock`, `out_of_stock` |
| `rating` | number \| null | Average rating / 5 |
| `review_count` | integer \| null | Review count |
| `breadcrumbs` | string[] \| null | Category breadcrumb trail |
| `region` | string | Regional host |

## Costco API workflow
1. **Costco Search**: discover listings and product URLs
2. **Costco Product**: fetch full PDP JSON (this endpoint)

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` |
| `404` | Product page not parseable |
| `500` | Rendering or parsing error |

## Notes
- Product parsing uses RSC + JSON-LD; search remains DOM-based.
- `images` may include multiple resolutions and color variants.
- Costs **2 credits** per call (browser rendering).

## Main use cases
- **PDP enrichment**: extract brand, specs, and all gallery images
- **Availability monitoring**: track stock status across regions
- **Price intelligence**: compare online prices on Costco regional stores