> ## Documentation Index
> Fetch the complete documentation index at: https://help.eaglecart.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Eaglecart Products API: List, Create & Manage Products

> Full reference for the Eaglecart Products API — list, retrieve, create, update, and delete products and variants with request and response examples.

The Products API lets you manage your entire product catalog programmatically. Use it to sync products from a PIM, build bulk import tools, automate pricing updates, or publish new products to your storefront without touching the admin UI.

> [!TIP]
>
> Use the `expand` query parameter to include nested resources — `expand=variants,images` — and retrieve a full product object in a single request rather than making separate calls.

***

## The Product Object

**id** `string`

Unique identifier for the product (e.g. `prod_01HXYZ999`).

**title** `string`

The product name displayed on the storefront.

**description** `string`

Full product description. May contain plain text or Markdown.

**status** `string`

Publication status. One of `draft`, `active`, or `archived`.

**created\_at** `string`

ISO 8601 timestamp of when the product was created.

**variants** `array`

The purchasable variants of this product (e.g. size/color combinations).

**variant fields**

**id** `string`

Unique variant identifier.

**title** `string`

Variant display name (e.g. `Medium / Black`).

**sku** `string`

Stock keeping unit code.

**price** `number`

Current selling price as a decimal.

**compare\_at\_price** `number`

Original price shown as a strikethrough on the storefront.

**inventory\_quantity** `integer`

Current stock level across all locations.

**images** `array`

Product images attached to this product.

**image fields**

**id** `string`

Unique image identifier.

**url** `string`

Public URL of the image.

**alt** `string`

Alt text for accessibility.

**position** `integer`

Display order, starting at `1`.

***

## List Products

Retrieve a paginated list of products. Filter by status or collection to narrow results.

`GET /products`

**status** `string`

Filter by publication status. One of `draft`, `active`, `archived`.

**collection\_id** `string`

Return only products belonging to this collection ID.

**expand** `string`

Comma-separated list of resources to expand inline. Supported values: `variants`, `images`.

**limit** `integer`

Number of products per page. Defaults to `20`. Maximum is `100`.

**page** `integer`

Page number to retrieve. Defaults to `1`.

```bash cURL theme={null}
curl "https://api.eaglecart.com/v1/products?status=active&expand=variants&limit=5" \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxx"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.eaglecart.com/v1/products?status=active&expand=variants&limit=5',
  { headers: { 'Authorization': 'Bearer ec_live_xxxxxxxxxxxx' } }
);
const data = await response.json();
```

```json Response theme={null}
{
  "data": [
    {
      "id": "prod_01HXYZ999",
      "title": "Classic Tee",
      "description": "A lightweight everyday tee made from 100% organic cotton.",
      "status": "active",
      "created_at": "2024-05-01T08:00:00Z",
      "variants": [
        {
          "id": "var_01HDEF789",
          "title": "Medium / Black",
          "sku": "TEE-M-BLK",
          "price": 49.99,
          "compare_at_price": 59.99,
          "inventory_quantity": 34
        }
      ]
    }
  ],
  "meta": { "page": 1, "limit": 5, "total": 212 }
}
```

***

## Get a Product

Retrieve a single product by its ID. Expand variants and images to get the full product detail in one call.

`GET /products/:id`

**id** `string` *required*

The unique ID of the product to retrieve.

**expand** `string`

Comma-separated list of sub-resources to include: `variants`, `images`.

```bash cURL theme={null}
curl "https://api.eaglecart.com/v1/products/prod_01HXYZ999?expand=variants,images" \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxx"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.eaglecart.com/v1/products/prod_01HXYZ999?expand=variants,images',
  { headers: { 'Authorization': 'Bearer ec_live_xxxxxxxxxxxx' } }
);
const product = await response.json();
```

```json Response theme={null}
{
  "id": "prod_01HXYZ999",
  "title": "Classic Tee",
  "description": "A lightweight everyday tee made from 100% organic cotton.",
  "status": "active",
  "created_at": "2024-05-01T08:00:00Z",
  "variants": [
    {
      "id": "var_01HDEF789",
      "title": "Medium / Black",
      "sku": "TEE-M-BLK",
      "price": 49.99,
      "compare_at_price": 59.99,
      "inventory_quantity": 34
    }
  ],
  "images": [
    {
      "id": "img_01HIMG001",
      "url": "https://cdn.eaglecart.com/stores/mystore/tee-black.jpg",
      "alt": "Classic Tee in Black",
      "position": 1
    }
  ]
}
```

***

## Create a Product

Create a new product in your catalog. New products are created with `draft` status by default and are not visible on the storefront until you set them to `active`.

`POST /products`

**title** `string` *required*

The product name.

**description** `string`

Full product description. Plain text or Markdown is accepted.

**status** `string`

Initial publication status. One of `draft`, `active`. Defaults to `draft`.

**variants** `array`

One or more variant objects to create alongside the product. Each variant must include at least a `price`.

```bash cURL theme={null}
curl -X POST https://api.eaglecart.com/v1/products \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Canvas Tote Bag",
    "description": "Durable canvas tote, perfect for everyday carry.",
    "status": "draft",
    "variants": [
      { "title": "Natural", "sku": "TOTE-NAT", "price": 24.99 }
    ]
  }'
```

```javascript JavaScript theme={null}
const response = await fetch('https://api.eaglecart.com/v1/products', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ec_live_xxxxxxxxxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Canvas Tote Bag',
    description: 'Durable canvas tote, perfect for everyday carry.',
    status: 'draft',
    variants: [{ title: 'Natural', sku: 'TOTE-NAT', price: 24.99 }]
  })
});
const product = await response.json();
```

```json Response theme={null}
{
  "id": "prod_01HNEW001",
  "title": "Canvas Tote Bag",
  "description": "Durable canvas tote, perfect for everyday carry.",
  "status": "draft",
  "created_at": "2024-06-11T12:00:00Z",
  "variants": [
    {
      "id": "var_01HNEWV01",
      "title": "Natural",
      "sku": "TOTE-NAT",
      "price": 24.99,
      "compare_at_price": null,
      "inventory_quantity": 0
    }
  ],
  "images": []
}
```

***

## Update a Product

Update the fields of an existing product. Send only the fields you want to change — all others remain unchanged.

`PATCH /products/:id`

**id** `string` *required*

The unique ID of the product to update.

**title** `string`

New product title.

**description** `string`

Updated product description.

**status** `string`

New publication status. One of `draft`, `active`, `archived`.

```bash cURL theme={null}
curl -X PATCH https://api.eaglecart.com/v1/products/prod_01HNEW001 \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.eaglecart.com/v1/products/prod_01HNEW001',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer ec_live_xxxxxxxxxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ status: 'active' })
  }
);
const updated = await response.json();
```

```json Response theme={null}
{
  "id": "prod_01HNEW001",
  "title": "Canvas Tote Bag",
  "status": "active",
  "updated_at": "2024-06-11T13:30:00Z"
}
```

***

## Delete a Product

Permanently delete a product and all its variants. This action cannot be undone. Consider setting the product to `archived` status instead if you want to hide it without losing its data.

`DELETE /products/:id`

**id** `string` *required*

The unique ID of the product to delete.

```bash cURL theme={null}
curl -X DELETE https://api.eaglecart.com/v1/products/prod_01HNEW001 \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxx"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.eaglecart.com/v1/products/prod_01HNEW001',
  {
    method: 'DELETE',
    headers: { 'Authorization': 'Bearer ec_live_xxxxxxxxxxxx' }
  }
);
// 204 No Content on success
```

```json Response theme={null}
// HTTP 204 No Content
```

***

## Error Handling

The Products API uses standard HTTP status codes. All error responses include a JSON body with a `code` field and a human-readable `message`.

| Status | Code | What it means | How to fix it |
| - | - | - | - |
| `400 Bad Request` | `invalid_params` | A required field is missing or has an invalid value (e.g. no `price` on a variant). | Check the `message` field for the specific validation failure and correct your request. |
| `401 Unauthorized` | `missing_api_key` / `invalid_api_key` | No `Authorization` header was sent, or the key is revoked. | Add a valid `Authorization: Bearer <key>` header. |
| `403 Forbidden` | `insufficient_scope` | Your key does not have `read:products` or `write:products` as required. | Re-generate your key with the correct scopes in **Settings → Developer → API Keys**. |
| `404 Not Found` | `product_not_found` | No product with the given ID exists in your store. | Confirm the product ID is correct. |
| `409 Conflict` | `sku_already_exists` | A variant with the provided SKU already exists in your catalog. | Use a unique SKU value for the new variant. |
| `429 Too Many Requests` | `rate_limit_exceeded` | You have exceeded 1,000 requests per minute. | Wait until `X-RateLimit-Reset` and retry with exponential backoff. |
| `500 Internal Server Error` | `internal_error` | An unexpected server error occurred. | Retry after a short delay. If the problem persists, contact Eaglecart support. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.