Sales Data

Claret Sales data APIs

Legacy endpoint. This page documents the legacy GET /sales endpoint, which uses the older current_index pagination and email/password token flow. New integrations should use GET /sales-data (see the API Reference). See Migrating from Legacy Endpoints. The Pagination and Authentication links below describe the current API; for the legacy behavior these endpoints use, follow the Migration guide.

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.

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

{
  "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}"

Returned when required arguments are missing or validation fails.

{
  "message": "Payload arguments are invalid"
}

{
  "message": "Unauthenticated."
}

PreviousCrop Supply Plans

NextSupply Plans Data

Last updated 2 months ago

Was this helpful?