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

> Find HomeGoods store locations near you across the United States, view detailed store information, and browse available locations by state. Quickly locate nearby stores to check hours, addresses, and other store details.

**Category:** Maps & Geospatial | **Website:** [homegoods.com/](https://homegoods.com/) | **Docs:** [parse.bot/marketplace/a3278415-1a3d-414f-a126-4068a164790c/homegoods-com-api](https://parse.bot/marketplace/a3278415-1a3d-414f-a126-4068a164790c/homegoods-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/homegoods/`
**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 store details

Get detailed information for a specific HomeGoods store by its store ID. Returns brand, location name, current open/closed status, full address, phone number, daily hours breakdown, and available services. Store IDs are available from search_stores or list_stores results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `store_id` | string | Yes | Store ID (e.g., '0515', '0372', '0589'). Can be found from search_stores or list_stores results. |

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

### List stores

List all HomeGoods stores, optionally filtered by US state code. Returns store location, address, phone, hours, and services. Supports manual pagination via offset and limit. Without a state filter, returns all stores nationwide.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of stores to return per page. |
| `offset` | integer | No | Number of stores to skip for pagination. |
| `state` | string | No | Two-letter US state code to filter by. If omitted, returns all stores. |

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

### Search stores

Search for HomeGoods stores near a location. Accepts a location string (zip code, city, address) or latitude/longitude coordinates. Returns up to 25 nearby stores sorted by distance. Each store includes address, hours, and rank by proximity. Either location or latitude+longitude must be provided.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `latitude` | number | No | Latitude coordinate. Must be used with longitude. |
| `limit` | integer | No | Maximum number of stores to return. |
| `location` | string | No | Location to search near (e.g., '10001', 'Los Angeles, CA', '123 Main St, Chicago IL'). Either location or latitude+longitude must be provided. |
| `longitude` | number | No | Longitude coordinate. Must be used with latitude. |

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

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