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

# Write listing ideas

> Have LocalAds write a direction for each of up to nine listing image slots.

[← Listing images](/listing-images/overview)

**Endpoint:** `POST https://makelocalads.com/api/v1/amazon-listing-ideas`
**Permission:** `amazon_listings:generate`

LocalAds writes a fresh set of up to nine image ideas for a marketplace: the
main image first, then up to eight variants, each with its own direction. It
is free. The request answers once the ideas are saved, which can take up to a
minute.

## Usage notes

* Writing ideas again replaces the saved set for that marketplace. A slot
  that already has an image keeps it.
* The product must exist and be readable by your key; an unknown marketplace
  returns `400 invalid_request`.
* Ideas are directions, not images: nothing is rendered or charged. Render
  them with [Render listing images](/listing-images/render-images).

## Quick start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url https://makelocalads.com/api/v1/amazon-listing-ideas \
    --header "Authorization: Bearer $LOCALADS_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
      "marketplace": "us"
    }'
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    "https://makelocalads.com/api/v1/amazon-listing-ideas",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.LOCALADS_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        product_id: "a1516a75-9be5-461a-93af-c1896a0a3127",
        marketplace: "us",
      }),
    },
  );

  const ideas = await response.json();
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import requests

  response = requests.post(
      "https://makelocalads.com/api/v1/amazon-listing-ideas",
      headers={
          "Authorization": f"Bearer {os.environ['LOCALADS_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
          "marketplace": "us",
      },
  )

  ideas = response.json()
  ```
</CodeGroup>

The response is `201 Created` with the saved ideas:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [
    {
      "id": "4d6f8a1c-3e5b-4c7d-9f1a-2b4c6d8e0f1a",
      "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
      "marketplace": "us",
      "position": 0,
      "slot_type": "main",
      "title": "MAIN IMG",
      "summary": "The throw folded on pure white, full product in frame, soft shadow.",
      "creative_id": null,
      "status": "idea",
      "image_url": null,
      "updated_at": "2026-09-25T10:00:00.000Z"
    }
  ]
}
```

`position` 0 is the main image; 1 to 8 are variants. `status` is `idea` until
an image is started for the slot. `summary` is the direction the image will be
rendered from; edit it with [Edit an idea's direction](/listing-images/edit-direction).

## Input fields

<ParamField body="product_id" type="string" required>
  The product the listing images are for.
</ParamField>

<ParamField body="marketplace" type="string" required>
  An `id` from [Marketplaces](/listing-images/marketplaces), such as `us`.
</ParamField>

<Accordion title="Complete JSON schema">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "object",
    "additionalProperties": false,
    "required": ["product_id", "marketplace"],
    "properties": {
      "product_id": { "type": "string", "format": "uuid" },
      "marketplace": { "type": "string" }
    }
  }
  ```
</Accordion>

## List the saved ideas

`GET /amazon-listing-ideas?product_id=...&marketplace=us` (permission
`amazon_listings:read`) returns the saved slots for a product and marketplace,
each with its direction and current image:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://makelocalads.com/api/v1/amazon-listing-ideas?product_id=a1516a75-9be5-461a-93af-c1896a0a3127&marketplace=us" \
  --header "Authorization: Bearer $LOCALADS_API_KEY"
```

## Errors

| Status | Code | Meaning |
| - | - | - |
| `400` | `invalid_request` | An unknown marketplace or field |
| `404` | `product_not_found` | The product is not available to you |

See [Errors and retries](/concepts/errors) for the error format.