Sales Data

Claret Sales data APIs

The Sales GET endpoint is paginated, so please refer to the Pagination documentation prior to usage.

As with all Claret API endpoints, the Sales APIs require token authentication. For instructions on how to retrieve and pass through the authentication token, please refer to the Authentication documentation.

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.)

GET Sales

Sales data is available to retrieve at our RESTful GET endpoint, and the structure of that data is somewhat customizable via the arguments described below.

GET https://plan.claret.app/{tenant}/api/v1/sales

Retrieve paginated historical, forecast or transactional sales data.

Query Parameters

Name	Type	Description
sale_type_name*	string	The name of the Sale Type for the Sale records being retrieved (i.e., "History", "Forecast", etc.)
start_date*	date string	The start date of the query pull. Based on the sell_date. Format: YYYY-MM-DD
duration*	integer	Integer value representing the number of days from the start date that the query should pull data for.
include_flattened_hierarchy	tiny integer (1 or 0)	When set to 1 (true), the flattened hierarchy levels for each of the Items and CustomerGroups will be provided in the payload.
current_index*	integer	For data loads larger than 1000 records, this parameter will not be required on the initial request, but must be included for each additional request. Please see the Pagination documentation for details.
pagination_count	integer	For use with paginated data. This optional parameter can be set to a numeric value denoting how many records to retrieve in each paginated batch. Please see the Pagination documentation for details.

200: OK Successful Response

The following examples contain the data structure for responses with and without the include_flattened_hierarchy flag

-- include_flattened_hierarchy was NOT included in the request for this response:
- Actual request from zymoeno tenant: 
-- https://plan.claret.app/zymoeno/api/v1/sales?start_date=2022-06-01&duration=600&sale_type_name=Forecast
 
{
    "success_message": "Successfully retrieved 298 Sales records matching `sale_type_id`='3' and `sell_date`>='2022-06-01' and `sell_date`<='2024-01-22'",
    "sales": [
        {
            "id": 12310,
            "sell_date": "2022-06-01",
            "quantity": 0,
            "created_at": "2021-09-28T16:51:44.000000Z",
            "updated_at": "2022-04-15T16:03:35.000000Z",
            "item_name": "117",
            "customer_group_name": "Palm Tree Distribution",
            "timing_interval_span": "month",
            "sale_type_name": "Forecast",
            "uom_abbr": "9LE"
        },
        {
            "id": 12334,
            "sell_date": "2022-06-01",
            "quantity": 196.195,
            "created_at": "2021-09-28T16:51:44.000000Z",
            "updated_at": "2022-04-15T16:03:35.000000Z",
            "item_name": "118",
            "customer_group_name": "Palm Tree Distribution",
            "timing_interval_span": "month",
            "sale_type_name": "Forecast",
            "uom_abbr": "9LE"
        },
       ... [additional records] ...
        {
            "id": 23274,
            "sell_date": "2022-12-01",
            "quantity": 135,
            "created_at": "2022-12-21T00:35:13.000000Z",
            "updated_at": "2022-12-21T00:35:13.000000Z",
            "item_name": "124",
            "customer_group_name": "Alamo Wholesalers",
            "timing_interval_span": "month",
            "sale_type_name": "Forecast",
            "uom_abbr": "9LE"
        }
    ],
    "total": 298,
    "from": 1,
    "to": 298,
    "per_page": 1000,
    "previous_data_count": 0,
    "data_count_remaining": 0,
    "current_index": 0,
    "next_index": null,
    "success_count": 298
}

-- include_flattened_hierarchy=1 WAS included in the request for this response:
- Actual request from zymoeno tenant:
-- https://plan.claret.app/zymoeno/api/v1/sales?start_date=2022-06-01&duration=600&sale_type_name=Forecast&include_flattened_hierarchy=1

{
    "success_message": "Successfully retrieved 298 Sales records matching `sale_type_id`='3' and `sell_date`>='2022-06-01' and `sell_date`<='2024-01-22'",
    "sales": [
        {
            "id": 12310,
            "item_name": "117",
            "customer_group_name": "Palm Tree Distribution",
            "timing_interval_span": "month",
            "uom": "9LE Case",
            "uom_abbr": "9LE",
            "sale_type_name": "Forecast",
            "sell_date": "2022-06-01",
            "quantity": 0,
            "created_at": "2021-09-28T16:51:44.000000Z",
            "updated_at": "2022-04-15T16:03:35.000000Z",
            "brand_group": "Premium group",
            "brand": "Clairemont brand",
            "item": "117",
            "item_description": "CLM Central Coast Sangiovese 12 x 750ml",
            "division": "East div",
            "state": "Florida",
            "distributor": "Palm Tree Distribution",
            "distributor_description": "PTD"
        },
        {
            "id": 12334,
            "item_name": "118",
            "customer_group_name": "Palm Tree Distribution",
            "timing_interval_span": "month",
            "uom": "9LE Case",
            "uom_abbr": "9LE",
            "sale_type_name": "Forecast",
            "sell_date": "2022-06-01",
            "quantity": 196.195,
            "created_at": "2021-09-28T16:51:44.000000Z",
            "updated_at": "2022-04-15T16:03:35.000000Z",
            "brand_group": "Premium group",
            "brand": "Clairemont brand",
            "item": "118",
            "item_description": "CLM Central Coast White Blend 12 x 750ml",
            "division": "East div",
            "state": "Florida",
            "distributor": "Palm Tree Distribution",
            "distributor_description": "PTD"
        },
     ... [additional records] ...
        {
            "id": 23274,
            "item_name": "124",
            "customer_group_name": "Alamo Wholesalers",
            "timing_interval_span": "month",
            "uom": "9LE Case",
            "uom_abbr": "9LE",
            "sale_type_name": "Forecast",
            "sell_date": "2022-12-01",
            "quantity": 135,
            "created_at": "2022-12-21T00:35:13.000000Z",
            "updated_at": "2022-12-21T00:35:13.000000Z",
            "brand_group": "Premium group",
            "brand": "ZAM brand",
            "item": "124",
            "item_description": "ZAM Lodi Zinfandel 12 x 750ml",
            "division": "West div",
            "state": "Texas",
            "distributor": "Alamo Wholesalers",
            "distributor_description": "AW"
        }
    ],
    "total": 298,
    "from": 1,
    "to": 298,
    "per_page": 1000,
    "previous_data_count": 0,
    "data_count_remaining": 0,
    "current_index": 0,
    "next_index": null,
    "success_count": 298
}

422: Unprocessable Entity Failed Validation

POST Sales

Sales data can be posted to Claret using the POST endpoint outlined below. This endpoint supports both JSON payloads and CSV file uploads, and processes data asynchronously via the Imports2 pipeline.

POST https://plan.claret.app/{tenant}/api/v1/sales

The POST endpoint accepts an arguments object and a payload array of Sales records (JSON) or a CSV file upload.

All responses are asynchronous. The endpoint returns a job_log_id that can be used with the Job Status endpoint to monitor progress and retrieve results.

Arguments

Name	Type	Description
allow_record_creation*	boolean	When true, missing Item@CustomerGroup combinations will be automatically created during import.
allow_record_update*	boolean	When true, existing sales records matching the composite key will be updated (upsert). When false, matching records are treated as errors.
should_continue_on_error*	boolean	When true, valid rows will be imported and invalid rows reported as errors. When false, the entire import fails if any row is invalid.

Payload Fields (per row)

Name	Type	Description
sale_type_name*	string	The name of the Sale Type (e.g., "History", "Forecast").
item_name*	string	The name of the Item. Must exist in the system.
customer_group_name*	string	The name of the Customer Group. Must exist in the system.
sell_date*	date string	The sell date in YYYY-MM-DD format.
timing_interval*	string	The timing interval span (e.g., "day", "week", "month", "year").
quantity*	numeric	The quantity value. 0 is accepted; negative numbers will fail validation.
uom*	string	The unit of measure name or abbreviation (e.g., "9LE Case", "Ton").

Upsert Composite Key

When allow_record_update is true, existing records are matched on:

• item_customer_group_id (resolved from item_name + customer_group_name)

• sell_date

• timing_interval_id (resolved from timing_interval)

• sale_type_id (resolved from sale_type_name)

If a match is found, quantity and uom are updated. If no match is found, a new record is created.

Option 1: JSON Payload

Send sales data as a JSON array in the payload field.

curl -X POST "https://plan.claret.app/{tenant}/api/v1/sales" \
  -H "Authorization: Bearer {your-token}" \
  -H "X-Requested-With: XMLHttpRequest" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "allow_record_creation": true,
      "allow_record_update": true,
      "should_continue_on_error": true
    },
    "payload": [
      {
        "sale_type_name": "History",
        "item_name": "118",
        "customer_group_name": "Palm Tree Distribution",
        "sell_date": "2025-01-15",
        "timing_interval": "month",
        "quantity": 150,
        "uom": "9LE Case"
      }
    ]
  }'

Option 2: CSV File Upload

Upload a CSV file via multipart/form-data. The CSV must include headers matching the required payload fields.

curl -X POST "https://plan.claret.app/{tenant}/api/v1/sales" \
  -H "Authorization: Bearer {your-token}" \
  -H "X-Requested-With: XMLHttpRequest" \
  -F "file=@sales_data.csv" \
  -F 'arguments={"allow_record_creation": true, "allow_record_update": true, "should_continue_on_error": true}'

CSV format:

sale_type_name,item_name,customer_group_name,sell_date,timing_interval,quantity,uom
History,118,Palm Tree Distribution,2025-01-15,month,150,9LE Case
History,119,Alamo Wholesalers,2025-01-15,month,200,9LE Case

202: Accepted (CSV) / 200: OK (JSON)

{
  "message": "Data import process started successfully. Check job status for updates.",
  "job_log_id": 12345,
  "job_status_link": "https://plan.claret.app/{tenant}/settings/application-maintenance/job-management/imports/logs/12345"
}

Use the job_log_id with the Job Status endpoint to monitor progress:

curl -X GET "https://plan.claret.app/{tenant}/api/v1/imports/status/12345" \
  -H "Authorization: Bearer {your-token}"

422: Unprocessable Entity

401: Unauthorized