Sales Reports

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

Request body:

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

Response:

{"status": "ok", "month": "Mar 2026"}

If the report contained no revenue data, the response includes "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

Looks back to the earliest imported order date, or 24 months, whichever is further. Returns an empty array if no orders have been imported yet. Hoard backfills up to 2 months per sync cycle, oldest first. Response:

{
  "gaps": ["2026-01-01", "2026-02-01"]
}

Each entry in 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

​Upload sales report

​Top-level fields

​Report object fields

​curl example

​Error responses

​Get sales gaps

​curl example

Upload sales report

Top-level fields

Report object fields

curl example

Error responses

Get sales gaps

curl example