# Report outcomes

> Report whether the buyer picked up or refused a cash-on-delivery order with PUT /signals/{order_ref}, withdraw it with DELETE, or send up to 500 at once.

The reports of the connected shops are what TrustOrder works from. Report every order once its outcome is known: `delivered` when the buyer picked it up, `refused` when they did not.

## Report one order

```http
PUT /signals/{order_ref}
```

`order_ref` is your own order id, 1 to 128 characters without control characters, URL-encoded in the path (`/` as `%2F`).

```json
{
  "outcome": "refused",
  "email_hash": "8cd79ce2224abde026ddc67563fe5edb8b5eb41846c63cd550a76ea76cc2eddd",
  "phone_hash": "038e5821814169825ae568bfefdb18ca31d4d2e0a0f5941b6da27df45d50ddf4",
  "address_hash": null,
  "occurred_at": "2026-11-01T14:03:00Z"
}
```

| Field | |
|---|---|
| `outcome` | `delivered` or `refused`, required |
| `email_hash`, `phone_hash`, `address_hash` | at least one is required |
| `occurred_at` | RFC 3339; defaults to now; at most 5 minutes in the future and at most 1095 days old |

The call is idempotent: the same `order_ref` sent again stays one report, and the last one wins. The response says what happened:

| `result` | Meaning |
|---|---|
| `stored` | saved or changed |
| `unchanged` | the same report was already there |
| `voided` | the report was voided after a dispute; it no longer counts and cannot be changed |

## Withdraw a report

```http
DELETE /signals/{order_ref}
```

Use it when an order goes back, for example from completed to processing. The answer is `204`, `404` if there is no such report, and `409` for a voided one.

## Many orders at once

```http
POST /signals/batch
```

```json
{
  "signals": [
    { "order_ref": "1001", "outcome": "delivered", "email_hash": "8cd79ce2…" },
    { "order_ref": "1002", "outcome": "refused", "email_hash": "8cd79ce2…" }
  ]
}
```

1 to 500 rows, each with the fields above plus `order_ref`; the request may be at most 1 MiB. Every row is handled on its own, and the answer lists the rows in the order sent:

```json
{
  "results": [
    { "order_ref": "1001", "result": "stored" },
    { "order_ref": "1002", "error_code": "INVALID_REQUEST" }
  ]
}
```

An invalid row gets `INVALID_REQUEST` and does not stop the others. A row with `INTERNAL` was not saved; send the batch again, it is safe to repeat. Use the batch endpoint to load past orders when you start: reports up to 1095 days old count.

## Test and live

Reports go to the environment of the key. Reports sent with a test key never affect live verdicts. A new account's reports are stored at once and count from its approval.
