# Sales commands

> Record and manage coffee sales.

HTML version: https://www.purveyors.io/docs/cli/sales

Record roasted-coffee sales against roast profiles. Sales roll into the Profit page in the web app.

Access: Member. Requires member access on your account.

## purvey sales list

List your sales, sorted by sell date.

Usage: `purvey sales list [options]`

Access: Member. Requires member access on your account.

- --coffee-id filters by inventory ID.
- Every sale includes batch_id and roast_id. batch_id is null when the sale is not linked to one batch; roast_id is set only when the sale named a roast.
- --date-start and --date-end accept YYYY-MM-DD and compose into a range.
- --offset + --limit enables pagination through large result sets.

| Argument or flag | Details |
| --- | --- |
| `--coffee-id <id>` | Only sales of this inventory item (an inventory ID). |
| `--batch-id <uuid>` | Only sales recorded against this roast batch. |
| `--roast-id <id>` | Only sales that name this roast. |
| `--date-start <YYYY-MM-DD>` | Only sales on or after this date. |
| `--date-end <YYYY-MM-DD>` | Only sales on or before this date. |
| `--buyer <name>` | Only sales to buyers whose name contains this text (case-insensitive). |
| `--limit <n>` | Maximum number of sales to return. Default: 20. |
| `--offset <n>` | Number of sales to skip when paging. Default: 0. |

## purvey sales record

Record a new sale.

Usage: `purvey sales record [options]`

Access: Member. Requires member access on your account.

- Selector modes: --batch-id (with --coffee-id when the batch holds more than one coffee), --roast-id, or --coffee-id + --batch-name.
- --batch-id records the sale against the batch as a whole, for a bag that could have come from any of its roasts of that coffee. --roast-id also records which roast it came from.
- Batch names can repeat. When --coffee-id + --batch-name matches more than one batch, nothing is recorded and the error lists each batch ID with its date and roast IDs; run the command again with --batch-id.
- The recorded sale includes batch_id, and roast_id when --roast-id was used.

| Argument or flag | Details |
| --- | --- |
| `--batch-id <uuid>` | Batch the coffee came from, by batch ID; records the sale against the batch as a whole. Add --coffee-id when the batch holds more than one coffee. |
| `--roast-id <id>` | Roast the coffee came from; records the sale against that roast and its batch. The CLI looks up the inventory item and batch. |
| `--coffee-id <id>` | Inventory ID of the coffee sold; use with --batch-id or --batch-name, not with --roast-id. |
| `--batch-name <name>` | Exact batch name of the coffee sold; use with --coffee-id. Refused when the name matches more than one batch. |
| `--oz <amount>` | Roasted coffee sold, in ounces. Required unless you use --form. |
| `--price <dollars>` | Total sale price, in US dollars (not per ounce). Required unless you use --form. |
| `--buyer <name>` | Buyer name or identifier. |
| `--sell-date <YYYY-MM-DD>` | Date of the sale; defaults to today. |
| `--form` | Prompt for a roast, ounces sold, sale price, and buyer; the sale date is set to today. |

## purvey sales update

Update a sale record.

Usage: `purvey sales update <id> [options]`

Access: Member. Requires member access on your account.

| Argument or flag | Details |
| --- | --- |
| `<id>` | Required: Sale ID. |
| `--oz <amount>` | New amount sold, in ounces. |
| `--price <dollars>` | New total sale price, in US dollars. |
| `--buyer <name>` | New buyer name or identifier. |
| `--sell-date <YYYY-MM-DD>` | New sale date. |

## purvey sales delete

Delete a sale record.

Usage: `purvey sales delete <id> [options]`

Access: Member. Requires member access on your account.

| Argument or flag | Details |
| --- | --- |
| `<id>` | Required: Sale ID. |
| `--yes` | Delete without asking for confirmation; needed in scripts and agents. |

## Related

- [Profit page](https://www.purveyors.io/profit): See margins built from sales.
- [Roast commands](https://www.purveyors.io/docs/cli/roast): Find the roast IDs that sales reference.
- [CLI overview](https://www.purveyors.io/docs/cli/overview): Install, sign in, and see every command group.