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

# Updating a Listing

## Update Listing Information

Need to change the price? Update photos? Add new details? Same endpoint, same process.

<Info>
  **Same Endpoint:** Updating uses the exact same endpoint as creating. Just use the same `externalListingId` you used before.
</Info>

## How It Works

`PUT /partner/v1/listings/{externalListingId}`

When you send a PUT request with an `externalListingId` that already exists, we update that listing.

<Steps>
  <Step title="Use the Same External ID">
    Use the exact same `externalListingId` from when you created the listing.

    Created with: `/listings/LISTING-123`\
    Update with: `/listings/LISTING-123`
  </Step>

  <Step title="Send Updated Data">
    Include the fields you want to update. We recommend sending **all fields** to keep everything in sync.
  </Step>

  <Step title="Get Confirmation">
    You'll receive a `200 OK` response:

    ```json theme={null}
    {
      "status": "success",
      "message": "Listing updated successfully",
      "venturuListingId": 98765,
      "venturuListingUrl": "https://www.venturu.com/business/..."
    }
    ```
  </Step>
</Steps>

## Common Updates

### Change Price

```json theme={null}
{
  "brokerExternalId": "BROKER-789",
  "status": "FOR_SALE",
  "businessType": "Restaurant",
  "location": {...},
  "financials": {
    "askingPrice": 495000,  // Reduced from $550k
    "revenue": 800000,
    "sde": 220000
  }
}
```

### Update Photos

```json theme={null}
{
  "brokerExternalId": "BROKER-789",
  "status": "FOR_SALE",
  "businessType": "Restaurant",
  "location": {...},
  "photos": [
    {
      "url": "https://example.com/new-photo1.jpg",
      "sortKey": 1
    },
    {
      "url": "https://example.com/new-photo2.jpg",
      "sortKey": 2
    }
  ]
}
```

<Warning>
  **Important:** The `photos` array replaces ALL existing photos. Include all photos you want to display.
</Warning>

### Change Description

```json theme={null}
{
  "brokerExternalId": "BROKER-789",
  "status": "FOR_SALE",
  "title": "Profitable Downtown Pizzeria - Price Reduced!",
  "description": "Updated description with new details...",
  "businessType": "Restaurant",
  "location": {...}
}
```

### Update Financials

```json theme={null}
{
  "brokerExternalId": "BROKER-789",
  "status": "FOR_SALE",
  "businessType": "Restaurant",
  "location": {...},
  "financials": {
    "askingPrice": 550000,
    "revenue": 850000,  // Updated numbers
    "sde": 240000,
    "inventory": 30000,
    "ffande": 150000
  }
}
```

### Change Location Visibility

```json theme={null}
{
  "brokerExternalId": "BROKER-789",
  "status": "FOR_SALE",
  "businessType": "Restaurant",
  "location": {
    "streetAddress1": "123 Main St",
    "city": "Miami",
    "state": "Florida",
    "country": "US",
    "visibility": "SHOW_FULL_ADDRESS"  // Now showing full address
  }
}
```

### Update Property Info

```json theme={null}
{
  "brokerExternalId": "BROKER-789",
  "status": "FOR_SALE",
  "businessType": "Restaurant",
  "location": {...},
  "property": {
    "propertyKind": "RENTED",
    "areaSqft": 2500,
    "rentData": {
      "amount": 5500,  // Rent increased
      "frequency": "MONTHLY",
      "leaseExpiration": "2029-12-31T00:00:00.000Z"  // Lease renewed
    }
  }
}
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Send Complete Data" icon="database">
    Always send all fields, not just what changed. Ensures perfect sync.
  </Card>

  <Card title="Update Regularly" icon="calendar-check">
    Keep listings current - update when prices or details change.
  </Card>

  <Card title="Test Changes" icon="flask">
    After updating, visit the listing URL to verify changes appear correctly.
  </Card>

  <Card title="Track Updates" icon="chart-line">
    Monitor `200 OK` responses. If you get `201`, you might have the wrong ID.
  </Card>
</CardGroup>

## Common Questions

<AccordionGroup>
  <Accordion title="What if I use a new externalListingId?" icon="circle-question">
    You'll create a **new listing** instead of updating. Always use the same ID for the same listing.
  </Accordion>

  <Accordion title="Can I update just the price?" icon="circle-question">
    Yes, but you still need required fields (`brokerExternalId`, `status`, `businessType`, `location`). Other fields keep their existing values.
  </Accordion>

  <Accordion title="Do updates appear instantly?" icon="circle-question">
    Yes! Changes are live immediately. Photos may take a minute to process.
  </Accordion>

  <Accordion title="Can I change the broker?" icon="circle-question">
    Yes! Just change the `brokerExternalId` to a different broker.
  </Accordion>
</AccordionGroup>

## Field-Specific Tips

### Updating Arrays (Photos, etc.)

Arrays like `photos` **replace** the entire list. Always include all items:

```json Good - All photos included (use fully qualified URLs) theme={null}
{
  "photos": [
    {"url": "https://cdn.yoursite.com/photo1.jpg", "sortKey": 1},
    {"url": "https://cdn.yoursite.com/photo2.jpg", "sortKey": 2},
    {"url": "https://cdn.yoursite.com/photo3.jpg", "sortKey": 3}
  ]
}
```

```json Bad - Missing photos will be removed theme={null}
{
  "photos": [
    {"url": "https://cdn.yoursite.com/photo3.jpg", "sortKey": 3}  // Only this photo will remain!
  ]
}
```

### Updating Nested Objects

For nested objects like `financials` or `property`, you **don't** need to include the entire object:

```json theme={null}
"financials": {
  "askingPrice": 550000,  // Only include changed fields
  "revenue": 800000,
  "sde": 220000
}
```

## Troubleshooting

### Getting 404 Listing Not Found?

The `externalListingId` doesn't exist. Check:

1. Correct ID spelling/format
2. Listing was created successfully
3. Using same API key

### Changes Not Appearing?

* Wait \~1 minute for search index
* Clear browser cache
* Check the returned `venturuListingUrl`

### Getting 201 Instead of 200?

You're creating a new listing, not updating. The `externalListingId` doesn't match any existing listing.

## Next Steps

<CardGroup cols={2}>
  <Card title="Manage Status" icon="toggle-on" href="./managing-listing-status">
    Change listing visibility
  </Card>

  <Card title="Create Listing" icon="circle-plus" href="./creating-a-listing">
    Create a new listing
  </Card>

  <Card title="Update Broker" icon="pen" href="./updating-a-broker">
    Update broker information
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Full API documentation
  </Card>
</CardGroup>