Documentation Index
Fetch the complete documentation index at: https://docs.tryhoard.com/llms.txt
Use this file to discover all available pages before exploring further.
Upload sales report
Upload a parsed sales report for a specific date range. Records are upserted
by (user_id, date) so re-uploading the same month is safe.
If all revenue fields are zero the month is still recorded as covered, so the
gaps endpoint stops requesting it.
POST /api/v1/sales_report
Content-Type: application/json
{
"date_from": "2026-03-01",
"date_to": "2026-03-27",
"report": {
"gross_sales": 1234.56,
"order_count": 42,
"product_amount": 1100.00,
"total_fees": 134.56,
"shipping_amount": 41.58,
"total_refund_amount": 0.00,
"refunded_orders": 0,
"refunded_fees": 0.00,
"adjustments": 0.00,
"net_sales_minus_fees": 965.44,
"net_sales": 1100.00
}
}
Top-level fields
| Field | Type | Required | Description |
|---|
date_from | string (date) | Yes | Start of the reporting period (first day of the month, e.g., "2026-03-01"). |
date_to | string (date) | Yes | End of the reporting period (e.g., "2026-03-31"). |
report | object | Yes | Sales metrics for the period. See report fields below. |
Report object fields
| Field | Type | Description |
|---|
gross_sales | number | Total gross sales in USD. |
order_count | integer | Number of orders in the period. |
product_amount | number | Product revenue in USD. |
total_fees | number | Total marketplace fees in USD. |
shipping_amount | number | Total shipping collected in USD. |
total_refund_amount | number | Total refund amount in USD. |
refunded_orders | integer | Number of refunded orders. |
refunded_fees | number | Fees refunded in USD. |
adjustments | number | Marketplace adjustments in USD. |
net_sales_minus_fees | number | Net sales after fees in USD. |
net_sales | number | Net sales in USD (before fees). |
{"status": "ok", "month": "Mar 2026"}
"empty": true.
curl example
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"date_from":"2026-03-01","date_to":"2026-03-31","report":{"gross_sales":1234.56,"order_count":42,"product_amount":1100.00,"total_fees":134.56,"shipping_amount":41.58,"total_refund_amount":0,"refunded_orders":0,"refunded_fees":0,"adjustments":0,"net_sales_minus_fees":965.44,"net_sales":1100.00}}' \
https://www.tryhoard.com/api/v1/sales_report
Error responses
| Code | Error code | Meaning |
|---|
| 422 | invalid_json | Request body is not valid JSON or contains an unparseable date |
| 422 | invalid_payload | The report field is missing or not an object |
Get sales gaps
Returns months that are missing sales report data so Hoard knows what to backfill.
GET /api/v1/sales_report/gaps
{
"gaps": ["2026-01-01", "2026-02-01"]
}
gaps is the first day of a month that needs sales report data (ISO 8601 date string).
curl example
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://www.tryhoard.com/api/v1/sales_report/gaps
