# Soriana — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/soriana/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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.beta.paywithlocus.com/api/wrapped/credits/soriana/get-basket-prices \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/soriana/get-coupons \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/soriana/get-departments \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/soriana/get-product-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/soriana/search-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","limit":"<integer>","query":"<string>","start":"<integer>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.