# Verkkokauppa — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and browse products from Verkkokauppa.com to find items across categories, check real-time prices and availability, read customer reviews, and discover deals in outlet and clearance sections. Filter products by your preferences and get detailed product information including specifications and store stock levels.

**Category:** E-commerce | **Website:** [verkkokauppa.com/](https://verkkokauppa.com/) | **Docs:** [parse.bot/marketplace/cf3419c6-c416-4204-8f37-31ca36a7cc5a/verkkokauppa-com-api](https://parse.bot/marketplace/cf3419c6-c416-4204-8f37-31ca36a7cc5a/verkkokauppa-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-verkkokauppa-com-api-cf3419c6/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_category_list

Get the full category tree for Verkkokauppa.com. Returns top-level categories with children linked via relationship data. Useful for obtaining category slugs for use with get_category_products. Includes product counts per category.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-verkkokauppa-com-api-cf3419c6/get_category_list \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_category_products

Browse products by category slug ID. Category IDs can be obtained from the get_category_list endpoint. Returns paginated results with up to 48 products per page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | Category slug ID (e.g. laptops, windows_laptops, gaming_laptops). Obtain from get_category_list endpoint. |
| `page` | integer | No | Page number (1-indexed). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-verkkokauppa-com-api-cf3419c6/get_category_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","page":"<integer>"}'
```

### get_clearance_products

Get clearance/surplus products with active discounts that are immediately shippable. Returns paginated results sorted by relevance with up to 48 products per page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (1-indexed). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-verkkokauppa-com-api-cf3419c6/get_clearance_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>"}'
```

### get_outlet_products

Get products in the Outlet section (customer returns). Returns a different response schema than search endpoints with full product details including customerReturnsInfo, condition, and pricing. Paginated with 48 items per page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (1-indexed). Internally converted to 0-indexed for the API. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-verkkokauppa-com-api-cf3419c6/get_outlet_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>"}'
```

### get_product_details

Get full details of a product by its numeric ID, including specifications, price, availability across warehouses and stores, and rating statistics. Combines data from the product API, availability API, and reviews stats API in a single call.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | Numeric product ID (e.g. 1031078). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-verkkokauppa-com-api-cf3419c6/get_product_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"<string>"}'
```

### get_product_price_and_availability

Lightweight endpoint to get price and basic availability info for a product. Returns taxless and tax-inclusive prices, discount details if active, and availability status across warehouses.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | Numeric product ID (e.g. 1031078). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-verkkokauppa-com-api-cf3419c6/get_product_price_and_availability \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"<string>"}'
```

### get_product_reviews

Get customer reviews for a specific product. Products with no reviews return an empty reviews array with totalItems 0. Reviews include rating, reviewText, userNickname, submissionTime, and secondaryRatings.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (1-indexed). Internally converted to 0-indexed for the API. |
| `product_id` | string | Yes | Numeric product ID (e.g. 1031078). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-verkkokauppa-com-api-cf3419c6/get_product_reviews \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","product_id":"<string>"}'
```

### get_store_availability

Get stock availability across different store locations and warehouses for a product. Returns shipment, pickup, and in-store stock counts with availability flags and timestamps.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | Numeric product ID (e.g. 1031078). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-verkkokauppa-com-api-cf3419c6/get_store_availability \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"<string>"}'
```

### search_products

Full-text search over all Verkkokauppa.com products. Returns paginated results with product data (name, price, images, rating), included category/campaign details, and pagination metadata. Sorted by relevance (-score) by default. Each page returns up to 48 products.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (1-indexed). |
| `query` | string | Yes | Search keyword. |
| `sort` | string | No | Sort order. Accepted values: -score, -popularity, price, -price. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-verkkokauppa-com-api-cf3419c6/search_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>","sort":"<string>"}'
```

### search_products_on_sale

Search for products currently on sale (with active discounts). Returns paginated results sorted by relevance. Each page returns up to 48 products with discount pricing and campaign info.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (1-indexed). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-verkkokauppa-com-api-cf3419c6/search_products_on_sale \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>"}'
```

### search_with_filters

Advanced search with custom filters. Allows combining keyword search with attribute-based filters such as brand. At least one of query or filters should be provided for meaningful results. Returns paginated results with up to 48 products per page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `filters` | string | No | JSON string of filter key-value pairs (e.g. {"base+brand": "Samsung"}). Filter keys use the format 'base+attribute_name'. |
| `page` | integer | No | Page number (1-indexed). |
| `query` | string | No | Search keyword. Omitting returns all products matching filters. |
| `sort` | string | No | Sort order. Accepted values: -score, -popularity, price, -price. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-verkkokauppa-com-api-cf3419c6/search_with_filters \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters":"<string>","page":"<integer>","query":"<string>","sort":"<string>"}'
```