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

# Update crop

> Update mutable fields on a crop. Only provided fields are touched.

```
PUT https://www.wiseyield.co/api/v1/crops/{id}
```

### Authentication

Requires a key with the `crops:write` scope.

### Path parameters

<ParamField path="id" type="string" required>
  Crop UUID.
</ParamField>

### Request body

All fields are optional. Only fields you include in the body are updated; omitted fields are left unchanged. To change `fieldId`, the new field must belong to the same farm as the crop's current field.

<ParamField body="fieldId" type="string">
  UUID. Must belong to the crop's current farm.
</ParamField>

<ParamField body="cropType" type="string">
  1–200 characters.
</ParamField>

<ParamField body="variety" type="string">
  Up to 200 characters. Pass `null` to clear.
</ParamField>

<ParamField body="adminCropId" type="string">
  UUID. Pass `null` to clear.
</ParamField>

<ParamField body="adminCropVarietyId" type="string">
  UUID. Pass `null` to clear.
</ParamField>

<ParamField body="plantedArea" type="number | string">
  In the farm's `areaUnit`.
</ParamField>

<ParamField body="plantingDate" type="string">
  ISO 8601 datetime. Pass `null` to clear.
</ParamField>

<ParamField body="expectedHarvestDate" type="string">
  ISO 8601 datetime. Pass `null` to clear.
</ParamField>

<ParamField body="season" type="string">
  One of `winter`, `summer`, `autumn`, `spring`, `year_round`. Pass `null` to clear.
</ParamField>

<ParamField body="seasonYear" type="integer">
  2000–2100. Pass `null` to clear.
</ParamField>

<ParamField body="expectedYield" type="number | string">
  Tons. Pass `null` to clear.
</ParamField>

<ParamField body="estimatedCost" type="number | string">
  In the farm's `currency`. Pass `null` to clear.
</ParamField>

<ParamField body="estimatedRevenue" type="number | string">
  In the farm's `currency`. Pass `null` to clear.
</ParamField>

<ParamField body="status" type="string">
  One of `planned`, `planted`, `growing`, `harvested`, `failed`. To set `harvested` and auto-populate `actualHarvestDate`, prefer the dedicated [status endpoint](/api-reference/crops/update-crop-status).
</ParamField>

<ParamField body="notes" type="string">
  Up to 5,000 characters. Pass `null` to clear.
</ParamField>

### Response

Returns the updated crop wrapped under `data`.

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT 'https://www.wiseyield.co/api/v1/crops/33333333-4444-5555-6666-777777777777' \
    -H "Authorization: Bearer $WISEYIELD_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "expectedYield": 195, "notes": "Bumped after spring leaf analysis" }'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    `https://www.wiseyield.co/api/v1/crops/${cropId}`,
    {
      method: 'PUT',
      headers: {
        Authorization: `Bearer ${process.env.WISEYIELD_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ expectedYield: 195 }),
    }
  );
  const { data: crop } = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.put(
      f'https://www.wiseyield.co/api/v1/crops/{crop_id}',
      headers={
          'Authorization': f"Bearer {os.environ['WISEYIELD_API_KEY']}",
          'Content-Type': 'application/json',
      },
      json={'expectedYield': 195},
  )
  crop = res.json()['data']
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": {
      "id": "33333333-4444-5555-6666-777777777777",
      "farmId": "11111111-2222-3333-4444-555555555555",
      "fieldId": "88888888-9999-aaaa-bbbb-cccccccccccc",
      "cropType": "date palm",
      "variety": "Medjool",
      "plantedArea": "4.2",
      "expectedYield": "195",
      "notes": "Bumped after spring leaf analysis",
      "status": "growing",
      "updatedAt": "2026-05-17T16:05:00.000Z"
    }
  }
  ```

  ```json 400 Field not on farm theme={null}
  {
    "error": "Validation failed",
    "code": "VALIDATION_ERROR",
    "message": "Field not found on this farm"
  }
  ```
</ResponseExample>

## Errors

| Status                    | When                                                                           |
| ------------------------- | ------------------------------------------------------------------------------ |
| `400 INVALID_ID`          | `{id}` is not a valid UUID                                                     |
| `400 VALIDATION_ERROR`    | Schema validation failed, OR new `fieldId` doesn't belong to the crop's farm   |
| `401`                     | Missing, malformed, expired, or revoked API key                                |
| `403 INSUFFICIENT_SCOPE`  | Key lacks `crops:write` scope                                                  |
| `404 NOT_FOUND`           | Crop doesn't exist, is soft-deleted, or belongs to a farm the user doesn't own |
| `429 RATE_LIMIT_EXCEEDED` | Per-user rate limit reached                                                    |
| `5xx`                     | Server error                                                                   |