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.
GEThttps://plan.claret.app/{tenant}/api/v1/sales
Retrieve paginated historical, forecast or transactional sales data.
Query Parameters
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}
If the arguments provided fail internal validation, a 422 response will be returned
Here, we have included a non-existent Sale Type as an argument. However, the same structured response will be sent back if required arguments are missing.
- Actual request from zymoeno tenant:-- https://plan.claret.app/zymoeno/api/v1/sales?start_date=2022-06-01&duration=600&sale_type_name=NotARealSaleType{"message":"The arguments provided have failed validation. Please check your request and try again.","content": {"errors": [ {"error_message":"The selected sale type name is invalid.","row": {"start_date":"2022-06-01","duration":"600","sale_type_name":"NotARealSaleType" } } ],"error_count":1,"valid": [],"valid_count":0 }}
POST Sales
Sales data can be posted to Claret using the RESTful POST endpoint outlined below.
Please Note: This endpoint is currently in beta, and may not behave as expected.
POSThttps://plan.claret.app/{tenant}/api/v1/sales
The POST endpoint for Sales records receives an arguments object and a content array of Sales objects to be processed.
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.
⚠️
🚧
🚧
arguments*
Object
The object containing key/value pairs for arguments pertaining to each of the objects within the "content" section - the "global" parameters for the request, as it were.
content*
Array
An array containing each of the Sales records objects that will be processed as part of the request.
(arguments) sale_type_name*
string
As part of the arguments object, the sale_type_name should correspond to the name of the Sale Type that each of the Sale objects in the content array should be associated with.
(arguments) create_missing_item_customer_group
tiny integer (1 or 0)
As part of the arguments object, this boolean value informs us whether to generate new Item@CustomerGroup records during the processing of each Sale object in the content array if the combination of values does not already exist.
(content) item_name*
string
As part of each object contained in the content array, the name of the Item in the Item@Customer Group that the Sale will be associated with must be provided. This Item must exist already within the data.
(content) customer_group_name*
string
As part of each object contained in the content array, the name of the Customer Group in the Item@Customer Group that the Sale will be associated with must be provided. This Customer Group must exist already within the data.
(content) sell_date*
date string
As part of each object contained in the content array, the sell_date for the Sale must be provided in the YYYY-MM-DD format.
(content) timing_interval_name*
string
As part of each object contained in the content array, the span of the Timing Interval that should be used for the Sale record must be provided (i.e., "day", "week", "month", "year")
(content) quantity*
integer
As part of each object contained in the content array, the quantity for the Sale record must be provided. 0 is ok, but no negative numbers will pass validations.
