# Crop Supply Plans

The Crop Supply Plans `GET` endpoint is paginated, so please refer to the [Pagination](https://docs.claret.app/apis/pagination) documentation prior to usage.

As with all Claret API endpoints, the Crop Supply Plan APIs require token authentication. For instructions on how to retrieve and pass through the authentication token, please refer to the [Authentication](https://docs.claret.app/apis/authentication) documentation.

{% hint style="warning" %}
Important note on Pagination: **PLEASE READ**

As Crop Supply Plan data is based on the output of the Crop Supply Plan module, the data for the API call is structured and stored in a table that will need a `request_id` as an index.

How it works:

1. Follow all instructions in the [Pagination](https://docs.claret.app/apis/pagination) documentation
2. Along with the `current_index` argument (in consecutive calls after the 1st call), the `request_id` argument will also need to be passed through.
   1. **NOTE:** This value will appear in the response from your initial request

Pagination arguments for Crop Supply Planning:

1st call: no arguments required:

2nd (and each additional) call(s): `current_index` (set to the `next_index` value from the previous response, `request_id` (set to the `request_id` from the previous response)
{% endhint %}

{% hint style="info" %}
All API documentation herein contains a `{tenant}` section of the URL path. These should always be replaced with the name of the actual tenant making the API call (i.e., `demo`, `zymoeno`, etc.)
{% endhint %}

## GET Supply Plans

<mark style="color:blue;">`GET`</mark> `https://plan.claret.app/{tenant}/api/v1/crop-supply-plans`

Retrieves data from the Crop Supply Planning module as Item\@Location records with all connected Supply and Demand records.

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**

<table><thead><tr><th width="300.6796875">Name</th><th width="106.6875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>include_flattened_hierarchy</code></td><td>boolean</td><td><p>Optional argument (true/false or 1/0).</p><p>Selecting true will include the names of the Items and Locations that are the parent hierarchical records of the Item@Location records that the demand and supply are attached to.</p></td></tr><tr><td><code>crop_supply_planning_view_name</code></td><td>string</td><td><p>The name of a Workspace view that is currently set up for the Crop Supply Planning module.</p><p>This is optional, but - if it is not provided - all arguments below will be required.</p></td></tr><tr><td><code>raw_material_hierarchy_type</code></td><td>string</td><td><p>The name of the Raw Material Hierarchy Type that should be used to retrieve the crop Items.</p><p>This is optional unless <code>crop_supply_planning_view_name</code> is not provided.</p></td></tr><tr><td><code>crop_location_hierarchy_type</code></td><td>string</td><td><p>The name of the Crop Location Hierarchy Type that should be used to retrieve the crop Locations.</p><p>This is optional unless <code>crop_supply_planning_view_name</code> is not provided.</p></td></tr><tr><td><code>selected_uom</code></td><td>string</td><td><p>The name or abbreviation of the Unit of Measure that the quantities should be converted to in the payload.</p><p>This is optional unless <code>crop_supply_planning_view_name</code> is not provided.</p></td></tr><tr><td><code>include_allocations</code></td><td>boolean</td><td><p>true/false or 1/0 indicating whether to include Contract Allocations in the response.</p><p>When true, each calendar year will include an <code>allocations</code> object alongside <code>supply</code> and <code>demand</code>.</p><p>This is optional unless <code>crop_supply_planning_view_name</code> is not provided.</p></td></tr><tr><td><code>calendars</code></td><td>array of strings</td><td><p>Array of Calendar names that should be included in the response (i.e., "FY24", "FY25", etc.).</p><p>This is optional unless <code>crop_supply_planning_view_name</code> is not provided.</p></td></tr><tr><td><code>supply_types</code></td><td>array of strings</td><td><p>Array of Supply Type names that will represent the Crop Supply Supply Plan values.</p><p>This is optional unless <code>crop_supply_planning_view_name</code> is not provided.</p></td></tr><tr><td><code>supply_statuses</code></td><td>array of strings</td><td><p>Array of Supply Plan Status names that the Supply Plans in the response should belong to.</p><p>This is optional unless <code>crop_supply_planning_view_name</code> is not provided.</p></td></tr><tr><td><code>dependent_demand_supply_types</code></td><td>array of strings</td><td><p>Array of Supply Type names that will represent the Dependent Demand Supply Types.</p><p>This is optional unless <code>crop_supply_planning_view_name</code> is not provided.</p></td></tr><tr><td><code>last_updated</code></td><td>string</td><td><p>Optional date filter in YYYY-MM-DD format.</p><p>When provided, only records updated on or after this date will be included.</p></td></tr><tr><td><code>duration</code></td><td>integer</td><td><p>Optional number of days after <code>last_updated</code> to include.</p><p>Used in conjunction with <code>last_updated</code> to define a date range for filtering records.</p></td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
// If include_flattened_hierarchy is set to false:
{
    "success_message": "Successfully retrieved 1000 Crop Supply Plan records matching `crop_supply_planning_view_name`='API Test'",
    "crop_supply_plans": [
        {
            "id": 1,
            "item_id": 47,
            "location_id": 10,
            "item_name": "CAS-A",
            "location_name": "A1D-R1",
            "calendars": {
                "2019": {
                    "demand": {
                        "total": 511.2775,
                        "records": [
                            {
                                "uom": "ton",
                                "name": "Make Plan",
                                "quantity": 83.1313
                            },
                            {
                                "uom": "ton",
                                "name": "Make Plan",
                                "quantity": 428.1462
                            }
                        ]
                    },
                    "supply": {
                        "total": 154,
                        "records": [
                            {
                                "uom": "Ton",
                                "name": "Crop Supply Plan",
                                "quantity": 77
                            },
                            {
                                "uom": "Ton",
                                "name": "Crop Supply Plan",
                                "quantity": 77
                            }
                        ]
                    }
                },
                "2020": {
                    "demand": {
                        "total": 500.6752,
                        "records": [
                            {
                                "uom": "Ton",
                                "name": "Make Plan",
                                "quantity": 500.6752
                            }
                        ]
                    },
                    "supply": {
                        "total": 0,
                        "records": []
                    }
                },
                "2021": {
                    "demand": {
                        "total": 761.7777,
                        "records": [
                            {
                                "uom": "Ton",
                                "name": "Make Plan",
                                "quantity": 761.7777
                            }
                        ]
                    },
                    "supply": {
                        "total": 99,
                        "records": [
                            {
                                "uom": "Ton",
                                "name": "Crop Supply Plan",
                                "quantity": 99
                            }
                        ]
                    }
                }
            },
        },
        {
            "id": 12,
            "item_id": 49,
            "location_id": 21,
            "item_name": "CAS-C",
            "location_name": "A1D-R12",
            "calendars": [],
        }
        ... (etc.)
    ],
    "total": 2976,
    "from": 1,
    "to": 1000,
    "per_page": 1000,
    "previous_data_count": 0,
    "data_count_remaining": 1976,
    "current_index": 0,
    "next_index": 37650,
    "request_id": 392,
    "success_count": 1000
}


// If include_flattened_hierarchy is set to true:
{
    "success_message": "Successfully retrieved 1000 Crop Supply Plan records matching `crop_supply_planning_view_name`='API Test'",
    "crop_supply_plans": [
        {
            "id": 1,
            "item_id": 47,
            "location_id": 10,
            "item_name": "CAS-A",
            "location_name": "A1D-R1",
            "calendars": {
                "2019": {
                    "demand": {
                        "total": 511.2775,
                        "records": [
                            {
                                "uom": "ton",
                                "name": "Make Plan",
                                "quantity": 83.1313
                            },
                            {
                                "uom": "ton",
                                "name": "Make Plan",
                                "quantity": 428.1462
                            }
                        ]
                    },
                    "supply": {
                        "total": 154,
                        "records": [
                            {
                                "uom": "Ton",
                                "name": "Crop Supply Plan",
                                "quantity": 77
                            },
                            {
                                "uom": "Ton",
                                "name": "Crop Supply Plan",
                                "quantity": 77
                            }
                        ]
                    }
                },
                "2020": {
                    "demand": {
                        "total": 500.6752,
                        "records": [
                            {
                                "uom": "Ton",
                                "name": "Make Plan",
                                "quantity": 500.6752
                            }
                        ]
                    },
                    "supply": {
                        "total": 0,
                        "records": []
                    }
                },
                "2021": {
                    "demand": {
                        "total": 761.7777,
                        "records": [
                            {
                                "uom": "Ton",
                                "name": "Make Plan",
                                "quantity": 761.7777
                            }
                        ]
                    },
                    "supply": {
                        "total": 99,
                        "records": [
                            {
                                "uom": "Ton",
                                "name": "Crop Supply Plan",
                                "quantity": 99
                            }
                        ]
                    }
                }
            },
            "row": "A1D-R1",
            "row_description": "A1D - Row 1",
            "block": "A1D - Block 328",
            "vineyard": "Jorge 9",
            "appellation": "St Helena",
            "region": "Napa County",
            "state": "California",
            "crop": "CAS-A",
            "crop_description": "Cabernet Sauvignon - A Grade",
            "varietal_group": "Cabernet Sauvignon",
        },
        {
            "id": 12,
            "item_id": 49,
            "location_id": 21,
            "item_name": "CAS-C",
            "location_name": "A1D-R12",
            "calendars": [],
            "row": "A1D-R12",
            "row_description": "A1D - Row 12",
            "block": "A1D - Block 328",
            "vineyard": "Jorge 9",
            "appellation": "St Helena",
            "region": "Napa County",
            "state": "California",
            "crop": "CAS-C",
            "crop_description": "Cabernet Sauvignon - C Grade",
            "varietal_group": "Cabernet Sauvignon",
        }
        ... (etc.)
    ],
    "total": 2976,
    "from": 1,
    "to": 1000,
    "per_page": 1000,
    "previous_data_count": 0,
    "data_count_remaining": 1976,
    "current_index": 0,
    "next_index": 37650,
    "request_id": 392,
    "success_count": 1000
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}
Name	Type	Description
`include_flattened_hierarchy`	boolean	Optional argument (true/false or 1/0). Selecting true will include the names of the Items and Locations that are the parent hierarchical records of the Item@Location records that the demand and supply are attached to.
`crop_supply_planning_view_name`	string	The name of a Workspace view that is currently set up for the Crop Supply Planning module. This is optional, but - if it is not provided - all arguments below will be required.
`raw_material_hierarchy_type`	string	The name of the Raw Material Hierarchy Type that should be used to retrieve the crop Items. This is optional unless `crop_supply_planning_view_name` is not provided.
`crop_location_hierarchy_type`	string	The name of the Crop Location Hierarchy Type that should be used to retrieve the crop Locations. This is optional unless `crop_supply_planning_view_name` is not provided.
`selected_uom`	string	The name or abbreviation of the Unit of Measure that the quantities should be converted to in the payload. This is optional unless `crop_supply_planning_view_name` is not provided.
`include_allocations`	boolean	true/false or 1/0 indicating whether to include Contract Allocations in the response. When true, each calendar year will include an `allocations` object alongside `supply` and `demand`. This is optional unless `crop_supply_planning_view_name` is not provided.
`calendars`	array of strings	Array of Calendar names that should be included in the response (i.e., "FY24", "FY25", etc.). This is optional unless `crop_supply_planning_view_name` is not provided.
`supply_types`	array of strings	Array of Supply Type names that will represent the Crop Supply Supply Plan values. This is optional unless `crop_supply_planning_view_name` is not provided.
`supply_statuses`	array of strings	Array of Supply Plan Status names that the Supply Plans in the response should belong to. This is optional unless `crop_supply_planning_view_name` is not provided.
`dependent_demand_supply_types`	array of strings	Array of Supply Type names that will represent the Dependent Demand Supply Types. This is optional unless `crop_supply_planning_view_name` is not provided.
`last_updated`	string	Optional date filter in YYYY-MM-DD format. When provided, only records updated on or after this date will be included.
`duration`	integer	Optional number of days after `last_updated` to include. Used in conjunction with `last_updated` to define a date range for filtering records.