# Products (/docs/api-reference/products)

## List products [#list-products]

<EndpointHeader method="GET" path="/api/v5/merchant/products" />

Scope: **`commerce.read`**

Returns your products, newest first.

### Query parameters [#query-parameters]

| Parameter | Type | Default | Notes |
|---|---|---|---|
| `page` | integer | `1` | |
| `limit` | integer | `50` | 1 to 200 |
| `status` | string | live products | `archived` to list archived products instead |
| `productType` | string | all | Filter by type, e.g. `physical` or `digital` |

{/* TODO(review): confirm the accepted productType values (nftTypeForProduct mapping) before listing them exhaustively. */}

```bash tab="curl"
curl "https://apps.apiswop.co/api/v5/merchant/products?limit=20" \
  -H "Authorization: Bearer $SWOP_MERCHANT_KEY"
```

```js tab="Node"
const res = await fetch('https://apps.apiswop.co/api/v5/merchant/products?limit=20', {
  headers: { Authorization: `Bearer ${process.env.SWOP_MERCHANT_KEY}` },
});
const { data } = await res.json();
```

```python tab="Python"
import os, requests

r = requests.get(
    "https://apps.apiswop.co/api/v5/merchant/products",
    params={"limit": 20},
    headers={"Authorization": f"Bearer {os.environ['SWOP_MERCHANT_KEY']}"},
)
data = r.json()["data"]
```

### Response [#response]

```json
{
  "state": "success",
  "success": true,
  "message": "Products fetched",
  "data": {
    "items": [
      {
        "_id": "66a1b2c3d4e5f6a7b8c9d0e1",
        "status": "live",
        "productType": "physical",
        "title": "Swop Classic Card",
        "description": "An NFC card that opens your Swop page.",
        "images": [{ "url": "https://…", "alt": "Swop Classic Card" }],
        "primaryImage": "https://…",
        "price": { "amount": 25, "currency": "USDC" },
        "payoutToken": "USDC",
        "royaltyPercentage": 0,
        "inventory": { "track": true, "available": null, "sold": 0, "sku": "66a1b2c3d4e5f6a7b8c9d0e1" },
        "variants": [],
        "fulfillment": { "requiresShipping": true, "shippingCost": 5, "trackingEnabled": true },
        "tags": [],
        "keywords": [],
        "createdAt": "2026-09-01T12:00:00.000Z",
        "updatedAt": "2026-10-01T12:00:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}
```

### The product object [#the-product-object]

| Field | Type | Meaning |
|---|---|---|
| `_id` | string | The product ID. Send it as `productId` in a checkout. |
| `status` | string | `live` or `archived` |
| `productType` | string | e.g. `physical`, `digital` |
| `title`, `description` | string | |
| `images[]`, `primaryImage` | | Image URLs |
| `price.amount` | number | List price in USDC. The buyer pays this. |
| `price.currency` | string | `USDC` |
| `royaltyPercentage` | number | Royalty paid on this product, if any |
| `inventory.available` | number \| null | Remaining stock, or `null` for unlimited |
| `inventory.sku` | string | Same as `_id` |
| `variants[]` | array | Option groups (for example Color, Size). Send a choice for each in `selectedOptions`. |
| `fulfillment.requiresShipping` | boolean | Whether the buyer's address is required |
| `fulfillment.shippingCost` | number | Shipping per unit, in USDC |
| `createdAt`, `updatedAt` | ISO 8601 | |

{/* TODO(review): the response also includes merchant.email and merchant.wallet (marketplace.js mapTemplateToMarketplaceProduct). It's the merchant's own data; deliberately not documented. */}
