# SSENSE Search API Documentation

<p><strong>SSENSE Search API Documentation</strong> Search and browse SSENSE, the luxury fashion retailer. Filter by designer, category, sale or keyword, and sort by price, discount or newest. Every item has the final price and the regular price as numbers with currency, the discount percent, stock status, gender, category ids, the product url and a full size photo. Filters are always honoured: a designer, category or page that does not exist never returns the general catalogue. SSENSE has no size, colour or price range filter, so Scrappa rejects those with a 422 instead of returning items that ignore them. Use the product endpoint for per-size stock. Cost: 1 credit per request, only for successful requests. Failed requests are not billed.</p>

- **Documentation:** [https://scrappa.co/docs/ssense-api/ssense_search](https://scrappa.co/docs/ssense-api/ssense_search)
- **API group:** SSENSE API
- **Endpoint:** `GET https://scrappa.co/api/ssense/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 |
| --- | --- | --- | --- |
| `gender` | string | Yes | men or women. SSENSE lists each gender on its own pages. |
| `query` | string | No | Keyword. Every returned page holds at least one item whose name or brand matches a word of the keyword. A keyword without hits returns an empty list. |
| `designer` | string | No | SSENSE designer slug, for example saint-laurent. Cannot be combined with category or sale_only. An unknown slug returns 422. |
| `category` | string | No | SSENSE category path in lowercase, for example bags or clothing/dresses. Cannot be combined with designer or sale_only. An unknown path returns 422. |
| `sale_only` | boolean | No | Set to true to list sale items only. Works with query and sort. |
| `sort` | string | No | recommended (default), latest, price-asc, price-desc or discount-desc. |
| `page` | integer | No | Page number, 1 or higher. Pages hold up to 120 items. A page past the last page returns an empty list. |
| `country` | string | No | Storefront: US (USD, default), CA (CAD) or GB (GBP). |

## Example response

```json
{
    "data": {
        "items": [
            {
                "id": "18946621",
                "sku": "261451F004006",
                "url": "https://www.ssense.com/en-us/women/product/gucci/black-rectangular-glasses/18946621",
                "name": "Black Rectangular Glasses",
                "brand": "Gucci",
                "price": {
                    "amount": 177,
                    "currency": "USD"
                },
                "gender": "women",
                "images": [
                    "https://res.cloudinary.com/ssenseweb/image/upload/w_1280,c_limit,h_1920,f_jpg,q_auto:best/261451F004006_1.jpg"
                ],
                "on_sale": true,
                "in_stock": true,
                "category_ids": [
                    1,
                    7,
                    8
                ],
                "original_price": {
                    "amount": 385,
                    "currency": "USD"
                },
                "discount_percent": 54
            },
            {
                "id": "18946721",
                "sku": "261451F005007",
                "url": "https://www.ssense.com/en-us/women/product/gucci/brown-low-nose-bridge-fit-sunglasses/18946721",
                "name": "Brown Low Nose Bridge Fit Sunglasses",
                "brand": "Gucci",
                "price": {
                    "amount": 227,
                    "currency": "USD"
                },
                "gender": "women",
                "images": [
                    "https://res.cloudinary.com/ssenseweb/image/upload/w_1280,c_limit,h_1920,f_jpg,q_auto:best/261451F005007_1.jpg"
                ],
                "on_sale": true,
                "in_stock": true,
                "category_ids": [
                    1,
                    7,
                    9
                ],
                "original_price": {
                    "amount": 515,
                    "currency": "USD"
                },
                "discount_percent": 56
            }
        ],
        "country": "US",
        "filters": {
            "sort": "price-asc",
            "query": null,
            "gender": "women",
            "category": null,
            "designer": "gucci",
            "sale_only": false
        },
        "currency": "USD",
        "pagination": {
            "has_more": false,
            "per_page": 118,
            "total_pages": 1,
            "current_page": 1
        }
    },
    "meta": {
        "credits": 1,
        "billable": true,
        "endpoint_family": "search"
    },
    "success": true
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A query parameter is missing or invalid. This response is not billable. |
| 503 | Upstream Unavailable | The store did not answer or sent a page Scrappa cannot read. This response is not billable. Retry later. |
| 422 | Unsupported Filter | SSENSE ignores size, color and price filters, so they are rejected. This response is not billable. |

## 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)