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

# Sales Reports

> Upload and query TCGplayer sales report data.

## 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:**

```json theme={null}
{
  "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:**

```json theme={null}
{"status": "ok", "month": "Mar 2026"}
```

If the report contained no revenue data, the response includes `"empty": true`.

### curl example

```bash theme={null}
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:**

```json theme={null}
{
  "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

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://www.tryhoard.com/api/v1/sales_report/gaps
```