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

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 `Item`s and `CustomerGroup`s 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.

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.

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.

⚠️ Do not use for production data.

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

🚧 UNDER CONSTRUCTION 🚧

The POST endpoint for Sales records receives an arguments object and a content array of Sales objects to be processed.

Request Body

Name Type Description

Name	Type	Description
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.

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.

PreviousPublic APIs

Last updated 6 months ago