# Soriana — 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 Soriana's product catalog to find items, compare prices, explore departments, and discover available coupons. Get detailed product information and calculate your basket totals to plan your shopping efficiently.

**Category:** Food & Dining | **Website:** [soriana.com/](https://soriana.com/) | **Docs:** [parse.bot/marketplace/3fb9e8ef-e5e7-411a-bb13-0bf395a043ac/soriana-com-api](https://parse.bot/marketplace/3fb9e8ef-e5e7-411a-bb13-0bf395a043ac/soriana-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-soriana-com-api-3fb9e8ef/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_basket_prices

Get current prices and availability for multiple products simultaneously by fetching each product's detail page. Useful for checking a shopping basket's total. Each product ID is looked up individually.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_ids` | string | Yes | JSON array of Soriana product IDs as a string (e.g. '["11400966", "11758215"]'). Product IDs are available from search_products results[*].id. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-soriana-com-api-3fb9e8ef/get_basket_prices \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_ids":"<string>"}'
```

### get_coupons

Retrieve available coupons and promotions from Soriana's online store. Returns coupons organized by category (product discounts, order discounts, shipping discounts). Each coupon includes its code, validity dates, and discount details.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `postal_code` | string | No | Mexican postal code for local offers (e.g. '64619'). Currently returns the same results regardless of value. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-soriana-com-api-3fb9e8ef/get_coupons \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"postal_code":"<string>"}'
```

### get_departments

Retrieve the list of top-level departments and their category slug IDs. These IDs can be used as category_id in search_products to filter by department.

**Estimated cost:** Metered

_No parameters required._

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

### get_product_details

Get detailed information for a specific product by its Soriana product ID. Returns product name, brand, EAN, prices, availability, description, and image URL. The product ID is available from search_products results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | The Soriana product ID (e.g. '11400966'). Available from search_products results[*].id. |

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

### search_products

Search for products by keyword or category ID. Returns a paginated list of products with prices and images. Pagination is offset-based via the start parameter (multiples of limit). At least one of query or category_id should be provided for meaningful results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | No | Category slug to filter by (e.g. 'lacteos-y-huevo', 'despensa'). Use get_departments to discover valid values. |
| `limit` | integer | No | Max results to return per page. |
| `query` | string | No | Search keyword (e.g. 'leche', 'coca cola'). At least one of query or category_id should be provided. |
| `start` | integer | No | Offset for pagination. Use multiples of limit to paginate (0, 25, 50, ...). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-soriana-com-api-3fb9e8ef/search_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","limit":"<integer>","query":"<string>","start":"<integer>"}'
```