# Billiger.de Offers API Documentation

Fetch current offers with prices, shipping, availability, condition, and merchant data. Use page/page_size for one page or all=true to exhaust the upstream offer total. Exhaustion is all-or-nothing: incomplete traversal returns a non-billable failure.

- **Documentation:** [https://staging.scrappa.co/docs/billiger-api/billiger_offers](https://staging.scrappa.co/docs/billiger-api/billiger_offers)
- **API group:** Billiger.de API
- **Endpoint:** `GET https://scrappa.co/api/billiger/offers`

## 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 |
| --- | --- | --- | --- |
| `product_id` | integer | Yes | Canonical Billiger product identifier. |
| `page` | integer | No | 1-based page number. Defaults to 1. |
| `page_size` | integer | No | Offers per page. Defaults to 20, maximum 50. |
| `all` | boolean | No | Set true to exhaust every expected offer page. |
| `sort` | string | No | relevance, price, total_price, shop_userreview_rating, shop_userreview_count, or shop_rating alias. |
| `direction` | string | No | Sort direction: asc or desc. |
| `group_by_shop` | boolean | No | Must remain false so offer pagination stays item-level and exhaustive. |
| `offer_conditions` | string | No | Numeric condition IDs such as 1 or 1,2,3. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/billiger/offers?product_id=5048620687&all=1&sort=total_price"
```

## Example response

```json
{
    "success": true,
    "data": {
        "total_hits": 25,
        "hits": []
    },
    "meta": {
        "pagination": {
            "total": 25,
            "exhausted": true
        }
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | Returned when required identifiers, query text, pagination, or numeric offer condition parameters are invalid. |
| 502 | Invalid Upstream Response | Returned as a non-billable failure when Billiger returns an unsuccessful, malformed, oversized, or incomplete response. No partial results are billed. Check the HTTP status before parsing the body because an intermediary may replace an error response. |
| 503 | Service Unavailable | The upstream service is temporarily unavailable. Please retry shortly. |

## More Scrappa resources

- [API documentation](https://staging.scrappa.co/docs)
- [Full LLM-readable API reference](https://staging.scrappa.co/llms-full.txt)
- [OpenAPI specification](https://staging.scrappa.co/docs/api.json)
- [Pricing](https://staging.scrappa.co/pricing)