# LotsStore API Documentation

Base URL: `https://api.lotsstore.app`

## Overview

LotsCommerce: take your business online with a store that looks established and pays you directly into your own Stripe or Razorpay account, plus UPI and WhatsApp orders. 0% of your sales. These tools let an AI assistant manage products, stock, orders, discounts and payments for a store you own or manage.

## Authentication

AI agents: add `https://api.lotsstore.app/mcp` as a remote MCP server and sign in with OAuth; no key is needed.

For REST integrations, authenticate with an API key or an OAuth access token in the request header:

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/endpoint
```

Or using the `X-API-Key` header:

```bash
curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/endpoint
```

### Getting an API Key

1. Open https://www.lotstech.com/api and click "Manage API keys"
2. Sign in with your Lots account
3. Choose LotsStore, name the key and create it (keys for every Lots app are managed in the same place)
4. Copy and securely store your API key (it will only be shown once)

Keys can also be created at https://api.lotsstore.app/dashboard.

## Rate Limiting

API requests are rate-limited to prevent abuse. Default limits:

- **100 requests per minute** per API key
- Rate limit headers are included in all responses:
  - `X-RateLimit-Limit`: Maximum requests allowed
  - `X-RateLimit-Remaining`: Requests remaining in current window
  - `X-RateLimit-Reset`: Time when the rate limit resets

## Response Format

All API responses follow a consistent JSON format:

### Success Response

```json
{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "timestamp": "2026-10-22T09:30:00.000Z"
  }
}
```

### Error Response

```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  },
  "meta": {
    "timestamp": "2026-10-22T09:30:00.000Z"
  }
}
```

## Common Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `AUTHENTICATION_REQUIRED` | 401 | API key is missing or invalid |
| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests, slow down |
| `ENDPOINT_NOT_FOUND` | 404 | The requested endpoint does not exist |
| `VALIDATION_ERROR` | 400 | Request parameters are invalid |
| `INTERNAL_ERROR` | 500 | Server error, please try again |

## API Endpoints

Total endpoints: **67**

### analytics

#### GET /api/v1/lotsstore/stores/:id/analytics

Revenue, orders, average order value and the visit-to-order funnel for one store over a date range, with daily rows and the totals compared with the previous period of the same length.

**Tags:** analytics

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `to` (string, optional):
- `from` (string, optional):
- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/analytics
```

---

### billing

#### POST /api/v1/lotsstore/checkout

Create a checkout link. Pass plan (starter, pro or business) and cycle (monthly or annual) for a plan, or amount_usd (10 to 1000) to add LotsTech Credits. Give the link to the person to pay in their browser; never ask for card details in chat.

**Tags:** commerce, billing

**Rate Limit:** 20 requests/minute

**Request Parameters:**

- `plan` (string, optional):  One of: `starter`, `pro`, `business`.
- `cycle` (string, optional):  One of: `monthly`, `annual`.
- `amount_usd` (number, optional):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://api.lotsstore.app/api/v1/lotsstore/checkout
```

---

#### GET /api/v1/lotsstore/billing

Show how the caller's stores are paid for: the plan (if any), whether today is covered or paid from LotsTech Credits, the credit balance, and the plans to choose from. Each store needs room on a plan or credits; an unfunded store keeps its storefront and data but pauses new orders and becomes read-only until funded.

**Tags:** commerce, billing

**Rate Limit:** 60 requests/minute

**Request Parameters:**


**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/billing
```

---

### customers

#### GET /api/v1/lotsstore/stores/:id/customers/:customerId

Gets one store customer, addresses, and store-scoped order summary after customer-group ownership checks.

**Tags:** customers

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):
- `customer_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/customers/:customerId
```

---

#### GET /api/v1/lotsstore/stores/:id/customers

List a store's customers with search and paging.

**Tags:** customers

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `q` (string, optional):
- `limit` (integer, optional):
- `order` (string, optional): Sort by created_at, updated_at, email, first_name, or last_name. Prefix with - for descending.
- `offset` (integer, optional):
- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/customers
```

---

### discounts

#### POST /api/v1/lotsstore/stores/:id/promotions

Creates a standard fixed or percentage order discount scoped to the store sales channel.

**Tags:** discounts, promotions

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `code` (string, **required**):
- `limit` (integer,null, optional):
- `value` (number, **required**):
- `status` (string, optional):  One of: `draft`, `active`, `inactive`.
- `store_id` (string, **required**):
- `method_type` (string, **required**):  One of: `percentage`, `fixed`.
- `currency_code` (string, optional):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"example_code","value":0,"store_id":"00000000-0000-0000-0000-000000000000","method_type":"percentage"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/promotions
```

---

#### DELETE /api/v1/lotsstore/stores/:id/promotions/:promotionId

Deletes a store-owned discount code.

**Tags:** discounts, promotions

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):
- `promotion_id` (string, **required**):

**Example Request:**

```bash
curl -X DELETE \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/promotions/:promotionId
```

---

#### GET /api/v1/lotsstore/stores/:id/promotions

List a store's discount codes.

**Tags:** discounts, promotions

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `q` (string, optional):
- `limit` (integer, optional):
- `offset` (integer, optional):
- `status` (string, optional):  One of: `draft`, `active`, `inactive`.
- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/promotions
```

---

#### PATCH /api/v1/lotsstore/stores/:id/promotions/:promotionId

Changes the status of a store-owned discount code.

**Tags:** discounts, promotions

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `status` (string, **required**):  One of: `draft`, `active`, `inactive`.
- `store_id` (string, **required**):
- `promotion_id` (string, **required**):

**Example Request:**

```bash
curl -X PATCH \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"draft","store_id":"00000000-0000-0000-0000-000000000000","promotion_id":"example_promotion_id"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/promotions/:promotionId
```

---

### domains

#### POST /api/v1/lotsstore/stores/:id/domains

Connect the person's own domain (for example shop.example.com) to a store. Returns one CNAME record pointing to customers.mylots.store for the owner to add at their DNS provider; HTTPS is set up automatically.

**Tags:** domains

**Rate Limit:** 20 requests/minute

**Request Parameters:**

- `domain` (string, **required**):
- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example_domain","store_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/domains
```

---

#### DELETE /api/v1/lotsstore/domains/:id

Removes a custom domain from a store and its storefront deployment.

**Tags:** domains

**Rate Limit:** 20 requests/minute

**Request Parameters:**

- `domain_id` (string, **required**):

**Example Request:**

```bash
curl -X DELETE \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/domains/:id
```

---

#### GET /api/v1/lotsstore/stores/:id/domains

Lists custom domains configured for a store.

**Tags:** domains

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/domains
```

---

#### POST /api/v1/lotsstore/domains/:id/verify

Check a connected domain: reports whether DNS is in place, the security certificate is being issued, or the store is live on the domain.

**Tags:** domains

**Rate Limit:** 20 requests/minute

**Request Parameters:**

- `domain_id` (string, **required**):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/domains/:id/verify
```

---

### inventory

#### GET /api/v1/lotsstore/stores/:id/inventory

List stock per product variant: in stock, reserved by open orders, incoming and available.

**Tags:** inventory

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `q` (string, optional):
- `limit` (integer, optional):
- `order` (string, optional): Sort products by created_at, updated_at, or title. Prefix with - for descending.
- `offset` (integer, optional):
- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/inventory
```

---

#### PATCH /api/v1/lotsstore/stores/:id/inventory

Set the stock of a product variant.

**Tags:** inventory

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `sku` (string, optional):
- `quantity` (integer, **required**):
- `store_id` (string, **required**):
- `medusa_variant_id` (string, **required**):
- `medusa_inventory_item_id` (string, optional):

**Example Request:**

```bash
curl -X PATCH \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quantity":0,"store_id":"00000000-0000-0000-0000-000000000000","medusa_variant_id":"example_medusa_variant_id"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/inventory
```

---

### orders

#### GET /api/v1/lotsstore/stores/:id/orders/export

Export a store's orders as rows for a spreadsheet: one row per item, with the order number and date, status, customer, shipping address and phone, item, variant, SKU, quantity and price, order totals, payment, fulfilment, tracking and refunds. Order totals and refunds are on the first row of each order only, so adding up a column gives the real revenue. Store owners and admins only; every export is recorded in the store activity log. Default range is the last 30 days (at most 366 days and 50,000 orders per export). Expired, rejected and canceled orders are left out unless you name them in status. Returns up to 250 orders per call; pass next_cursor back as cursor to get the next page until it is null.

**Tags:** commerce, orders

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `to` (string, optional): Last day, YYYY-MM-DD (UTC), inclusive. Default: today.
- `from` (string, optional): First day, YYYY-MM-DD (UTC). Default: 30 days before to.
- `limit` (integer, optional): Orders per page, default 250.
- `cursor` (string, optional): next_cursor from the previous page. The export keeps the filters it started with.
- `status` (array, optional): Only these order statuses. Omit for every live or confirmed order, including requests awaiting confirmation.
- `store_id` (string, **required**):
- `payment_status` (array, optional):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/orders/export
```

---

#### GET /api/v1/lotsstore/stores/:id/checkout-orders/:checkoutOrderId

Gets a tenant-scoped checkout order request, payment attempts, and timeline.

**Tags:** orders, payments

**Rate Limit:** 90 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):
- `checkout_order_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/checkout-orders/:checkoutOrderId
```

---

#### GET /api/v1/lotsstore/stores/:id/orders/:orderId

Get one confirmed order: items, totals, customer, addresses, payment and fulfilment.

**Tags:** orders

**Rate Limit:** 90 requests/minute

**Request Parameters:**

- `order_id` (string, **required**):
- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/orders/:orderId
```

---

#### GET /api/v1/lotsstore/stores/:id/checkout-orders

Lists pre-fulfillment checkout order requests and their independent payment/acceptance states.

**Tags:** orders, payments

**Rate Limit:** 90 requests/minute

**Request Parameters:**

- `limit` (integer, optional):
- `offset` (integer, optional):
- `store_id` (string, **required**):
- `payment_status` (string, optional):
- `acceptance_status` (string, optional):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/checkout-orders
```

---

#### GET /api/v1/lotsstore/stores/:id/orders

List a store's confirmed orders with paging and filters.

**Tags:** orders

**Rate Limit:** 90 requests/minute

**Request Parameters:**

- `limit` (integer, optional):
- `order` (string, optional): Sort by created_at, updated_at, display_id, or total. Prefix with - for descending.
- `offset` (integer, optional):
- `status` (string, optional):
- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/orders
```

---

#### POST /api/v1/lotsstore/stores/:id/checkout-orders/:checkoutOrderId/operations

Applies fulfillment, shipment, cancellation, tracking, invoice, and manual refund actions.

**Tags:** orders, shipping, fulfillment

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `input` (object, optional):
- `action` (string, **required**):
- `store_id` (string, **required**):
- `idempotency_key` (string, **required**):
- `checkout_order_id` (string, **required**):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"example_action","store_id":"00000000-0000-0000-0000-000000000000","idempotency_key":"example_idempotency_key","checkout_order_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/checkout-orders/:checkoutOrderId/operations
```

---

#### PATCH /api/v1/lotsstore/stores/:id/checkout-orders/:checkoutOrderId

Applies an audited payment verification or seller acceptance action.

**Tags:** orders, payments

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `action` (string, **required**):
- `reason` (string, optional):
- `store_id` (string, **required**):
- `idempotency_key` (string, **required**):
- `checkout_order_id` (string, **required**):

**Example Request:**

```bash
curl -X PATCH \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"example_action","store_id":"00000000-0000-0000-0000-000000000000","idempotency_key":"example_idempotency_key","checkout_order_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/checkout-orders/:checkoutOrderId
```

---

### payments

#### POST /api/v1/lotsstore/stores/:id/payments/razorpay/connect

Record the store's own Razorpay account after the owner connects it. Prefer start_payment_oauth, which gives the owner a Razorpay sign-in link.

**Tags:** payments, razorpay

**Rate Limit:** 20 requests/minute

**Request Parameters:**

- `mode` (string, optional):  One of: `test`, `live`.
- `country` (string, optional):
- `currency` (string, optional):
- `metadata` (object, optional):
- `store_id` (string, **required**):
- `provider_account_id` (string, optional):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/payments/razorpay/connect
```

---

#### POST /api/v1/lotsstore/stores/:id/payments/stripe/connect

Connect the store owner's own Stripe account. Returns the store's Payments page, where the owner pastes one Stripe restricted key, and the steps page for creating that key. Never ask for or accept a Stripe key in chat. Charges run on the owner's Stripe account and settle to their Stripe balance; LotsStore takes 0% of sales. Stripe works in the countries Stripe supports.

**Tags:** payments, stripe

**Rate Limit:** 20 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/payments/stripe/connect
```

---

#### GET /api/v1/lotsstore/stores/:id/payment-settings

Gets safe payment method and order acceptance settings for a store.

**Tags:** payments

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/payment-settings
```

---

#### POST /api/v1/lotsstore/stores/:id/payment-connections/:provider/start

Start connecting the store's own Razorpay account: returns a Razorpay sign-in and consent link for the store owner to open in their browser. Payments settle straight to the merchant's Razorpay account.

**Tags:** payments, oauth

**Rate Limit:** 20 requests/minute

**Request Parameters:**

- `mode` (string, optional):  One of: `test`, `live`.
- `provider` (string, **required**):  One of: `razorpay`.
- `store_id` (string, **required**):
- `return_url` (string, **required**):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"razorpay","store_id":"00000000-0000-0000-0000-000000000000","return_url":"example_return_url"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/payment-connections/:provider/start
```

---

#### POST /api/v1/lotsstore/stores/:id/payment-connections/razorpay/onboarding/start

Get a link for the store owner to open in their browser to sign in to Razorpay, or create a Razorpay account, and connect it to the store. For businesses registered in India. Money from online payments then settles to the owner's own Razorpay account.

**Tags:** payments, razorpay, onboarding

**Rate Limit:** 20 requests/minute

**Request Parameters:**

- `mode` (string, optional):  One of: `test`, `live`.
- `store_id` (string, **required**):
- `return_url` (string, **required**):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"00000000-0000-0000-0000-000000000000","return_url":"example_return_url"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/payment-connections/razorpay/onboarding/start
```

---

#### PATCH /api/v1/lotsstore/stores/:id/payment-settings

Turn checkout on or off, choose test or live mode, and set which payment methods the store offers (Stripe, Razorpay, UPI to a UPI ID, WhatsApp orders) and whether verified payments are accepted automatically. A Stripe key is pasted by the owner on the Payments page, never sent here from a chat.

**Tags:** payments

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `methods` (array, optional):
- `store_id` (string, **required**):
- `test_mode` (boolean, optional):
- `checkout_enabled` (boolean, optional):
- `default_acceptance_mode` (string, optional):

**Example Request:**

```bash
curl -X PATCH \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/payment-settings
```

---

### products

#### POST /api/v1/lotsstore/stores/:id/products

Add a product to a store with its variants (for example sizes or colours), prices in minor units of the store currency, stock, images and category. Products start as drafts unless status is published.

**Tags:** products, medusa

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `slug` (string, optional):
- `title` (string, **required**):
- `images` (array, optional):
- `status` (string, optional):  One of: `draft`, `proposed`, `published`, `rejected`.
- `options` (array, optional):
- `metadata` (object, optional):
- `store_id` (string, **required**):
- `subtitle` (string, optional):
- `variants` (array, optional):
- `description` (string, optional):
- `thumbnail_url` (string, optional):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"example_title","store_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/products
```

---

#### POST /api/v1/lotsstore/stores/:id/products/:productId/variants

Creates a variant with options, pricing, identifiers, dimensions, and inventory behavior on an owned product.

**Tags:** products, variants, pricing

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `sku` (string, optional):
- `title` (string, **required**):
- `width` (number,null, optional):
- `height` (number,null, optional):
- `length` (number,null, optional):
- `prices` (array, optional):
- `weight` (number,null, optional):
- `barcode` (string, optional):
- `options` (object, optional):
- `metadata` (object, optional):
- `store_id` (string, **required**):
- `product_id` (string, **required**):
- `allow_backorder` (boolean, optional):
- `compare_at_price` (object,null, optional):
- `manage_inventory` (boolean, optional):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"example_title","store_id":"00000000-0000-0000-0000-000000000000","product_id":"example_product_id"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/products/:productId/variants
```

---

#### POST /api/v1/lotsstore/stores/:id/products/bulk

Add up to 100 products to a store in one call, each with the same fields as add_product.

**Tags:** products, medusa, migration

**Rate Limit:** 10 requests/minute

**Request Parameters:**

- `products` (array, **required**):
- `store_id` (string, **required**):
- `idempotency_key` (string, optional): Optional retry key. Reusing the same key and payload returns the original import result without creating duplicate products.

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"products":[],"store_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/products/bulk
```

---

#### POST /api/v1/lotsstore/stores/:id/categories

Create a product category, optionally under a parent category.

**Tags:** products, categories

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `name` (string, **required**):
- `handle` (string, optional):
- `store_id` (string, **required**):
- `is_active` (boolean, optional):
- `category_id` (string, optional):
- `description` (string, optional):
- `is_internal` (boolean, optional):
- `parent_category_id` (string,null, optional):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"example_name","store_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/categories
```

---

#### POST /api/v1/lotsstore/stores/:id/collections

Create a product collection, such as Summer or Best sellers.

**Tags:** products, collections

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `title` (string, **required**):
- `handle` (string, optional):
- `store_id` (string, **required**):
- `collection_id` (string, optional):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"example_title","store_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/collections
```

---

#### DELETE /api/v1/lotsstore/stores/:id/categories/:categoryId

Delete a product category. Products in it are kept.

**Tags:** products, categories

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):
- `category_id` (string, **required**):

**Example Request:**

```bash
curl -X DELETE \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/categories/:categoryId
```

---

#### DELETE /api/v1/lotsstore/stores/:id/collections/:collectionId

Delete a product collection. Its products are kept.

**Tags:** products, collections

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):
- `collection_id` (string, **required**):

**Example Request:**

```bash
curl -X DELETE \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/collections/:collectionId
```

---

#### DELETE /api/v1/lotsstore/stores/:id/products/:productId

Deletes a product and its derived Lots snapshot after validating store ownership.

**Tags:** products

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):
- `product_id` (string, **required**):

**Example Request:**

```bash
curl -X DELETE \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/products/:productId
```

---

#### DELETE /api/v1/lotsstore/stores/:id/products/:productId/variants/:variantId

Deletes a variant after validating store and product ownership.

**Tags:** products, variants

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):
- `product_id` (string, **required**):
- `variant_id` (string, **required**):

**Example Request:**

```bash
curl -X DELETE \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/products/:productId/variants/:variantId
```

---

#### GET /api/v1/lotsstore/stores/:id/products/:productId

Get one product with its variants, prices, stock settings, images and categories.

**Tags:** products

**Rate Limit:** 90 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):
- `product_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/products/:productId
```

---

#### GET /api/v1/lotsstore/stores/:id/categories

List a store's product categories, including parent and subcategories and their order.

**Tags:** products, categories

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `q` (string, optional):
- `limit` (integer, optional):
- `offset` (integer, optional):
- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/categories
```

---

#### GET /api/v1/lotsstore/stores/:id/collections

List a store's product collections.

**Tags:** products, collections

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `q` (string, optional):
- `limit` (integer, optional):
- `offset` (integer, optional):
- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/collections
```

---

#### GET /api/v1/lotsstore/stores/:id/products

List a store's products with search, status filter and paging.

**Tags:** products

**Rate Limit:** 90 requests/minute

**Request Parameters:**

- `q` (string, optional):
- `limit` (integer, optional):
- `order` (string, optional): Sort by created_at, updated_at, or title. Prefix with - for descending.
- `offset` (integer, optional):
- `status` (string, optional):
- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/products
```

---

#### PATCH /api/v1/lotsstore/stores/:id/categories/:categoryId

Rename, move or reorder a product category.

**Tags:** products, categories

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `name` (string, optional):
- `handle` (string, optional):
- `store_id` (string, **required**):
- `is_active` (boolean, optional):
- `category_id` (string, **required**):
- `description` (string, optional):
- `is_internal` (boolean, optional):
- `parent_category_id` (string,null, optional):

**Example Request:**

```bash
curl -X PATCH \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"00000000-0000-0000-0000-000000000000","category_id":"example_category_id"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/categories/:categoryId
```

---

#### PATCH /api/v1/lotsstore/stores/:id/collections/:collectionId

Rename a product collection or change its handle.

**Tags:** products, collections

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `title` (string, optional):
- `handle` (string, optional):
- `store_id` (string, **required**):
- `collection_id` (string, **required**):

**Example Request:**

```bash
curl -X PATCH \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"00000000-0000-0000-0000-000000000000","collection_id":"example_collection_id"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/collections/:collectionId
```

---

#### PATCH /api/v1/lotsstore/stores/:id/products/:productId

Change a product: title, description, status, prices, variants, images, categories, SEO and more.

**Tags:** products

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `seo` (object, optional):
- `slug` (string, optional):
- `tags` (array, optional):
- `title` (string, optional):
- `width` (number,null, optional):
- `height` (number,null, optional):
- `images` (array, optional):
- `length` (number,null, optional):
- `status` (string, optional):
- `weight` (number,null, optional):
- `hs_code` (string,null, optional):
- `options` (array, optional):
- `material` (string,null, optional):
- `metadata` (object, optional):
- `store_id` (string, **required**):
- `subtitle` (string, optional):
- `product_id` (string, **required**):
- `description` (string, optional):
- `category_ids` (array, optional):
- `discountable` (boolean, optional):
- `product_type` (string,null, optional):
- `collection_id` (string,null, optional):
- `thumbnail_url` (string, optional):
- `origin_country` (string,null, optional):
- `specifications` (array, optional):
- `storefront_visible` (boolean, optional):

**Example Request:**

```bash
curl -X PATCH \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"00000000-0000-0000-0000-000000000000","product_id":"example_product_id"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/products/:productId
```

---

#### PATCH /api/v1/lotsstore/stores/:id/products/:productId/variants/:variantId

Updates a variant and its prices after validating store and product ownership.

**Tags:** products, variants, pricing

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `sku` (string, optional):
- `title` (string, optional):
- `width` (number,null, optional):
- `height` (number,null, optional):
- `length` (number,null, optional):
- `prices` (array, optional):
- `weight` (number,null, optional):
- `barcode` (string, optional):
- `options` (object, optional):
- `metadata` (object, optional):
- `store_id` (string, **required**):
- `product_id` (string, **required**):
- `variant_id` (string, **required**):
- `allow_backorder` (boolean, optional):
- `compare_at_price` (object,null, optional):
- `manage_inventory` (boolean, optional):

**Example Request:**

```bash
curl -X PATCH \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"00000000-0000-0000-0000-000000000000","product_id":"example_product_id","variant_id":"example_variant_id"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/products/:productId/variants/:variantId
```

---

### reviews

#### GET /api/v1/lotsstore/stores/:id/reviews

Lists tenant-scoped product reviews for merchant moderation.

**Tags:** reviews, moderation

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `q` (string, optional):
- `limit` (integer, optional):
- `offset` (integer, optional):
- `status` (string, optional):  One of: `pending`, `published`, `rejected`.
- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/reviews
```

---

#### PATCH /api/v1/lotsstore/stores/:id/reviews/:reviewId

Publishes or rejects a tenant-owned product review.

**Tags:** reviews, moderation

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `status` (string, **required**):  One of: `published`, `rejected`.
- `store_id` (string, **required**):
- `review_id` (string, **required**):
- `moderation_note` (string, optional):

**Example Request:**

```bash
curl -X PATCH \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"published","store_id":"00000000-0000-0000-0000-000000000000","review_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/reviews/:reviewId
```

---

#### POST /api/v1/lotsstore/stores/:id/reviews/:reviewId/reply

Adds or updates the merchant reply on a tenant-owned review.

**Tags:** reviews, replies

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `reply` (string, **required**):
- `store_id` (string, **required**):
- `review_id` (string, **required**):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reply":"example_reply","store_id":"00000000-0000-0000-0000-000000000000","review_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/reviews/:reviewId/reply
```

---

### shipping

#### GET /api/v1/lotsstore/stores/:id/shipping-settings

Gets tenant-safe business origin, zones, methods, and provider connection summaries.

**Tags:** shipping

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/shipping-settings
```

---

#### PATCH /api/v1/lotsstore/stores/:id/shipping-settings

Updates business origin, zones, and manual shipping methods.

**Tags:** shipping

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `zones` (array, optional):
- `methods` (array, optional):
- `business` (object, optional):
- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X PATCH \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/shipping-settings
```

---

### stores

#### POST /api/v1/lotsstore/stores/:id/archive

Archive a store: owner only, confirmed by typing the store name in confirm_name. The storefront goes offline and billing for the store stops; nothing is deleted. The owner can restore it for 30 days. Show the person what this does and get their go-ahead first.

**Tags:** commerce, stores

**Rate Limit:** 10 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):
- `confirm_name` (string, **required**):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"00000000-0000-0000-0000-000000000000","confirm_name":"example_confirm_name"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/archive
```

---

#### POST /api/v1/lotsstore/stores

Create a store with a free name.mylots.store address. Needs room on the person's LotsStore plan or LotsTech Credits (check get_billing). The country decides the store currency (for example US sells in USD, IN in INR) and cannot change later. The store starts as a draft; publish_store puts it live.

**Tags:** stores, tenancy, commerce

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `name` (string, **required**): Required store display name.
- `country` (string, optional): Optional ISO country code. Defaults to IN.
- `subdomain` (string, optional): Optional requested subdomain under lots.store.
- `description` (string, optional):
- `template_key` (string, optional): Optional storefront template key.
- `default_currency` (string, optional): Optional ISO currency code. Defaults to INR.

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"example_name"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores
```

---

#### GET /api/v1/lotsstore/stores/:id

Gets one LotsStore tenant, storefront settings, user role, and public URL.

**Tags:** stores

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id
```

---

#### GET /api/v1/lotsstore/stores/:id/activity

Lists recent merchant and commerce activity for an accessible store.

**Tags:** stores, activity, audit

**Rate Limit:** 90 requests/minute

**Request Parameters:**

- `limit` (integer, optional):
- `offset` (integer, optional):
- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/activity
```

---

#### GET /api/v1/lotsstore/stores

Lists LotsStore tenants where the authenticated user is an active member.

**Tags:** stores

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `status` (string, optional): Optional status filter.

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores
```

---

#### POST /api/v1/lotsstore/stores/:id/publish

Put a store's storefront live at its address so shoppers can browse and buy.

**Tags:** stores, publishing

**Rate Limit:** 20 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/publish
```

---

#### POST /api/v1/lotsstore/stores/:id/restore

Restore a store archived in the last 30 days: owner only. It needs room on the person's plan or LotsTech Credits; the storefront comes back online.

**Tags:** commerce, stores

**Rate Limit:** 10 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/restore
```

---

#### PATCH /api/v1/lotsstore/stores/:id

Update a store's name, description, settings or status. Set status to archived to stop billing for the store and take its storefront offline (nothing is deleted); set it back to draft or active to restore it, which needs room on your plan or LotsTech Credits.

**Tags:** stores

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `name` (string, optional):
- `status` (string, optional):  One of: `draft`, `active`, `paused`, `suspended`, `archived`.
- `settings` (object, optional):
- `store_id` (string, **required**):
- `description` (string, optional):

**Example Request:**

```bash
curl -X PATCH \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id
```

---

#### PATCH /api/v1/lotsstore/stores/:id/storefront

Saves, publishes, or resets versioned storefront appearance, content, navigation, policies, and SEO settings.

**Tags:** stores, storefront, settings

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `seo` (object, optional):
- `theme` (object, optional):
- `content` (object, optional):
- `policies` (object, optional):
- `store_id` (string, **required**):
- `operation` (string, optional):  One of: `save_draft`, `publish`, `reset_draft`.
- `navigation` (array, optional):
- `template_key` (string, optional):  One of: `minimal`, `editorial`, `catalog`, `boutique`, `marketplace`.

**Example Request:**

```bash
curl -X PATCH \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/storefront
```

---

### taxes

#### GET /api/v1/lotsstore/stores/:id/tax-settings

Gets tenant-safe GST/tax, invoice, and category configuration.

**Tags:** taxes, gst

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/tax-settings
```

---

#### PATCH /api/v1/lotsstore/stores/:id/tax-settings

Updates GST registration, pricing, shipping tax, invoice, and tax categories.

**Tags:** taxes, gst

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `settings` (object, optional):
- `store_id` (string, **required**):
- `categories` (array, optional):

**Example Request:**

```bash
curl -X PATCH \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/tax-settings
```

---

### team

#### POST /api/v1/lotsstore/invitations/accept

Accept an invitation to a store's team with the token from the invitation link. The signed-in account's email must match the invitation.

**Tags:** commerce, team

**Rate Limit:** 20 requests/minute

**Request Parameters:**

- `token` (string, **required**):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"example_token"}' \
  https://api.lotsstore.app/api/v1/lotsstore/invitations/accept
```

---

#### POST /api/v1/lotsstore/stores/:id/team

Invite a teammate to a store by email with a role (admin, manager, staff or viewer). They get an email with a link and have access only after they accept it, signed in with that email. Returns invite_url to share if the email does not arrive. Inviting someone again sends a fresh link.

**Tags:** team, members

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `role` (string, **required**):  One of: `admin`, `manager`, `staff`, `viewer`.
- `email` (string, **required**):
- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role":"admin","email":"user@example.com","store_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/team
```

---

#### POST /api/v1/lotsstore/stores/:id/leave

Leave a store's team. Anyone except the owner can leave; the owner archives the store instead. Rejoining needs a new invitation.

**Tags:** commerce, team

**Rate Limit:** 20 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/leave
```

---

#### GET /api/v1/lotsstore/stores/:id/team

Lists a store's team: active members, pending invitations (with when they expire) and removed members.

**Tags:** team, members

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/team
```

---

#### DELETE /api/v1/lotsstore/stores/:id/team/:memberId

Deactivates a store team member without deleting audit history.

**Tags:** team, members

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `store_id` (string, **required**):
- `member_id` (string, **required**):

**Example Request:**

```bash
curl -X DELETE \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/team/:memberId
```

---

#### PATCH /api/v1/lotsstore/stores/:id/team/:memberId

Updates a store team member role or active status.

**Tags:** team, members

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `role` (string, optional):  One of: `admin`, `manager`, `staff`, `viewer`.
- `status` (string, optional):  One of: `active`, `inactive`.
- `store_id` (string, **required**):
- `member_id` (string, **required**):

**Example Request:**

```bash
curl -X PATCH \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"00000000-0000-0000-0000-000000000000","member_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lotsstore.app/api/v1/lotsstore/stores/:id/team/:memberId
```

---

## How LotsStore works with your agent

LotsStore is an online store run from your agent or the dashboard. Start with `list_stores` and work in one `store_id` at a time; `get_store` returns its address (`url`) and status. A new store (`create_store`) needs room on the person's plan or LotsTech Credits; check `get_billing` first and offer `create_checkout` when there is none. The country decides the store currency (for example IN sells in INR, US in USD) and cannot be changed later.

Catalog: `add_product` or `bulk_add_products` with variants, prices in minor units of the store currency, and stock; `update_inventory` sets stock per variant. Products are drafts until published; `publish_store` puts the storefront live. Never invent prices, stock or policies: ask.

Orders arrive as order requests (`list_checkout_orders`). The seller accepts or rejects each one (`operate_checkout_order`); show the person the order before acting. A UPI payment is a customer claim with a transaction reference: verify it only after the person confirms it in their own bank or UPI app. Rejecting a paid online order queues its refund. Accepting, fulfilling and refunding work even when the store is unfunded.

Payments settle to the merchant's own account; LotsStore never holds money and takes 0% of sales. Online payments use the merchant's own Stripe account (in the countries Stripe supports) or Razorpay account (India-registered businesses). Razorpay: `start_payment_oauth` returns a sign-in link for the owner. Stripe: the owner pastes one restricted key on the store's Payments page; `connect_stripe` returns that page and the steps (https://lotsstore.app/help/connect-stripe). Never ask for or accept a Stripe key in chat. UPI and WhatsApp orders need only a UPI ID or phone number (`update_payment_settings`).

Custom domains: `add_custom_domain` returns one CNAME record (to customers.mylots.store) for the owner to add at their DNS provider; `verify_custom_domain` reports when DNS and the certificate are live.

When a store is not funded, its storefront stays readable, new checkouts pause and changes return `FUNDING_REQUIRED` (402) with a link to billing; nothing is deleted. Archive a store with `update_store` status `archived` to stop billing for it.
## Support

- Questions and problems: https://support.lotsstore.app
- Feature requests: https://support.lotsstore.app/feedback
- Changelog (new tools and API changes): https://support.lotsstore.app/changelog
- Browsable API reference: https://api.lotsstore.app/docs

---

*Documentation generated on 2026-10-22T19:09:08.029Z*