# Morrisons — 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 Morrisons grocery products, view detailed information like reviews and pricing, discover active promotions, and get personalized product recommendations. Find exactly what you're looking for with category browsing, search suggestions, and similar product recommendations.

**Category:** E-commerce | **Website:** [morrisons.com/](https://morrisons.com/) | **Docs:** [parse.bot/marketplace/d894b565-7ba7-45e0-8f58-f24122e779bf/morrisons-com-api](https://parse.bot/marketplace/d894b565-7ba7-45e0-8f58-f24122e779bf/morrisons-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/morrisons/`
**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 category list

Returns the full category hierarchy for browsing products. The tree has up to 4 levels of nesting via childCategories arrays. Each category includes a name, categoryId, retailerCategoryId, and productCount.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/morrisons/get-category-list \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get product detail

Returns full details for a single product by its numeric retailerProductId. Includes product info, detailed description, nutritional fields, breadcrumbs, promotions, and lists of similar/related product IDs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `retailer_product_id` | string | Yes | Numeric product ID from search or category results (e.g. '113240422') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/morrisons/get-product-detail \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"retailer_product_id":"<string>"}'
```

### Get product reviews

Returns customer reviews for a product by its UUID productId. Includes reviews with ratings, comments, verified buyer status, and a rating histogram showing distribution of 1-star through 5-star ratings. Results can be sorted by recency, rating, or helpfulness.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | UUID productId of the product (from search_products or get_product_detail results, e.g. '721a6e29-4bab-43e1-a241-a34296dd606e') |
| `sort` | string | No | Sort order for reviews. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/morrisons/get-product-reviews \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"<string>","sort":"<string>"}'
```

### Get products by category

Returns paginated product listings for a specific category. Includes product groups with decorated products, pagination metadata, and additional page info with breadcrumbs, filters, and sort options.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | Numeric retailerCategoryId from get_category_list (e.g. '176738') |
| `limit` | integer | No | Maximum number of products to return per page. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/morrisons/get-products-by-category \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","limit":"<integer>"}'
```

### Get promotions

Returns currently active promotions and offers across the site. Includes product groups with promoted items and additional category/filter info for the promotions page.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/morrisons/get-promotions \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get search suggestions

Returns search suggestions/autocomplete for a partial query. Useful for building typeahead search interfaces.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Partial search term (e.g. 'mil', 'bre') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/morrisons/get-search-suggestions \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

### Get similar products

Returns similar or related product IDs for a given retailerProductId. The returned UUIDs are productId values that can be used with get_product_reviews.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `retailer_product_id` | string | Yes | Numeric product ID (e.g. '113240422') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/morrisons/get-similar-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"retailer_product_id":"<string>"}'
```

### Search products

Full-text search over the Morrisons product catalog. Returns paginated product groups containing decorated product objects with names, prices, images, ratings, and promotions. Each product group has a type (featured, personalized) and contains a decoratedProducts array.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of products to return per page. |
| `query` | string | Yes | Search keyword (e.g. 'milk', 'bread', 'chicken') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/morrisons/search-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","query":"<string>"}'
```

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