# Costco Business Delivery — 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 Costco Business Delivery products by category or keyword to find pricing, specifications, and availability for bulk purchases. Locate nearby Costco Business warehouses and filter results by product attributes to compare options and make informed buying decisions.

**Category:** E-commerce | **Website:** [costcobusinessdelivery.com/](https://costcobusinessdelivery.com/) | **Docs:** [parse.bot/marketplace/8cdb4411-e87f-48a9-9285-0650c3bf7d9b/costcobusinessdelivery-com-api](https://parse.bot/marketplace/8cdb4411-e87f-48a9-9285-0650c3bf7d9b/costcobusinessdelivery-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/costco-business-delivery/`
**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

### Find warehouse

Find location information for a US ZIP code. Returns geocoded location data including city, state, timezone, and coordinates. Multiple entries may be returned for a single ZIP code representing different city name variants.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `zip_code` | string | Yes | US ZIP code to search for (e.g. 84101, 90210). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/costco-business-delivery/find-warehouse \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"zip_code":"<string>"}'
```

### Get category products

List products within a specific category using its URL path. Returns paginated results including products, total count, and subcategory facets. Category paths can be discovered from the facets in search_products results (e.g. /beverages.html, /disposables.html, /grocery.html). Pagination is offset-based via the start parameter.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_url` | string | Yes | The category URL path (e.g. /beverages.html, /disposables.html, /grocery.html, /restaurant.html). Available paths can be discovered from facets in search_products results. |
| `limit` | integer | No | Maximum number of results to return per page. |
| `loc` | string | No | Warehouse location ID for pricing and availability context. Defaults to 113 (Salt Lake City). |
| `start` | integer | No | Pagination offset (0-based index of first result). |

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

### Get product detail

Retrieve full product details for a specific item by its item number. Returns a single product object with all available fields including pricing, images, marketing features, and stock status. The item_number can be obtained from search_products or get_category_products results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `item_number` | string | Yes | The unique item number of the product (from search_products results item_number field). |
| `loc` | string | No | Warehouse location ID for pricing and availability context. Defaults to 113 (Salt Lake City). |

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

### Get restaurant supplies

Retrieve products in the Restaurant Supplies category. Convenience endpoint equivalent to calling get_category_products with category_url=/restaurant.html. Returns paginated results with the same structure as get_category_products.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of results to return per page. |
| `loc` | string | No | Warehouse location ID for pricing and availability context. Defaults to 113 (Salt Lake City). |
| `start` | integer | No | Pagination offset (0-based index of first result). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/costco-business-delivery/get-restaurant-supplies \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","loc":"<string>","start":"<integer>"}'
```

### Get search filters

Retrieve available filter facets (categories, price ranges, brands, certifications, dietary features) for a search query. Returns a list of facet objects each containing a key, label, and array of value/count buckets. Useful for discovering what filtering options are available before performing a filtered search.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `loc` | string | No | Warehouse location ID for pricing and availability context. Defaults to 113 (Salt Lake City). |
| `query` | string | No | Search keyword to get filters for. Use *:* for all available filters. |

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

### Search products

Full-text search over Costco Business Delivery products by keyword or item number. Returns paginated product results with pricing, availability, and faceted filters. Pagination is offset-based via the start parameter; each page returns up to limit products from a total of numFound. Facets in the response describe available category, brand, and price filters for the current query.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of results to return per page. |
| `loc` | string | No | Warehouse location ID for pricing and availability context. Defaults to 113 (Salt Lake City). |
| `query` | string | No | Search keyword or item number. Use *:* to browse all products. |
| `sort` | string | No | Sort order for results. |
| `start` | integer | No | Pagination offset (0-based index of first result). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/costco-business-delivery/search-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","loc":"<string>","query":"<string>","sort":"<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.