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

> Access data from scuffers.com.

**Category:** E-commerce | **Website:** [scuffers.com/](https://scuffers.com/) | **Docs:** [parse.bot/marketplace/8e269c97-9d9f-4725-af74-1b6ad137bd21/scuffers-com-api](https://parse.bot/marketplace/8e269c97-9d9f-4725-af74-1b6ad137bd21/scuffers-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/scuffers/`
**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 categories

Retrieve the complete list of product collections/categories. Returns all non-geosort collections available on the store. Makes multiple paginated requests to enumerate the full set (typically ~239 collections). Each collection can be used as category_id in get_category_products.

**Estimated cost:** Metered

_No parameters required._

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

### Get category products

Get paginated products from a specific collection/category. Returns up to 30 products per page. Use the collection handle as category_id (available from get_categories results). An unknown handle returns an empty products array (upstream behavior).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | Collection handle identifying the category (e.g. 'accessories', 'new', 'all-sales', 'footwear'). Obtained from get_categories endpoint's handle field. |
| `page` | integer | No | Page number for pagination. Each page returns up to 30 products. |

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

### Get new arrivals

Get the latest new arrival products. Returns up to 30 products per page from the store's 'New Arrivals' collection, ordered by recency.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. Each page returns up to 30 products. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/scuffers/get-new-arrivals \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>"}'
```

### Get product

Get full product details by handle or URL. Returns complete information including description, all variant sizes/colors/SKUs, pricing, all images, and product options. Accepts either a product handle (e.g. 'japan-shirt') or full product URL.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | Product handle (e.g. 'japan-shirt') or full product URL (e.g. 'https://scuffers.com/products/japan-shirt'). Available from search_products, get_category_products, get_new_arrivals, or get_sale_items results. |

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

### Get sale items

Get discounted/sale products. Returns up to 30 products per page from the 'All Sales' collection. Each product includes a computed discount_percent showing the percentage off from the original compare_at_price.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. Each page returns up to 30 products. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/scuffers/get-sale-items \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>"}'
```

### Search products

Search products by keyword with optional category filter. Returns up to 10 matching products per query. Results come from the site's search suggest engine and are ranked by relevance.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Optional product type filter to narrow results (e.g. 'Man Shirt Longsleeved'). Matches the product_type field. |
| `page` | integer | No | Page number for pagination (currently limited to 10 results per query by the upstream search suggest API). |
| `query` | string | Yes | Search query text (e.g. 'shirt', 'hoodie', 'sneakers'). |

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

## Next steps

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