# LiquiDonate

> LiquiDonate is a San Francisco based reverse-logistics and donation-disposition platform that turns retail returns, excess inventory and unsellable goods into local nonprofit donations instead of landfill or liquidation. Its matching engine pairs items with nearby nonprofits, buys the shipping label, routes the parcel and generates the donation receipt. Two public developer APIs: MagicMatch (donation-as-a-service, GA) and ReturnsDirect (returns-management integration, Beta).

LiquiDonate publishes no llms.txt. This file was generated by the API Evangelist enrichment pipeline on 2026-07-19 from apis.yml and the artifacts in this repository. Every URL below was verified reachable on that date.

## APIs

- [MagicMatch by LiquiDonate](https://docs-magicmatch.liquidonate.com): Send parcel and item details, receive a matched nearby nonprofit plus a purchased donation shipping label. Base URL `https://api.liquidonate.com`. Auth: `X-LiquiDonate-Key` + `X-LiquiDonate-Secret` headers. RPC-style, POST-only, `/v1/` path prefix.
- [ReturnsDirect by LiquiDonate (Beta)](https://docs-returns.liquidonate.com): Push order data to LiquiDonate and receive HMAC-signed return and refund webhooks. Base URL `https://returns.liquidonate.com`, sandbox `https://returns-sandbox.liquidonate.com`. Auth: HMAC-SHA256 over the raw body in `X-Signature` plus `X-Shop-Domain`.

## Operations

MagicMatch:
- `setupRetailer` — POST /v1/setupRetailer — register a retailer and issue its API key and secret
- `getRetailer` — POST /v1/getRetailer — read the retailer profile for the current credentials
- `estimateMatchAndShip` — POST /v1/matchAndShip/estimate — preview the nonprofit match and shipping rate, no shipment created
- `matchAndShip` — POST /v1/matchAndShip — match and buy the donation label in one call
- `match` — POST /v1/match — match only, no rate, no shipment
- `attachLabelsToMatch` — POST /v1/match/ship — register your own labels against an existing match
- `ship` — POST /v1/ship — buy a label between two fixed addresses, no matching, no donation receipt
- `donate` — POST /v1/donate — bulky, oversized, multi-package or pickup-scheduled donations

ReturnsDirect:
- `pushExternalOrder` — POST /webhooks/external-order — push an order into the return portal cache
- Outbound events: `return.pending`, `return.pending_approval`, `return.approved`, `return.rejected`, `return.cancelled`, `refund.completed`, `refund.flagged`

## Specs

- [MagicMatch OpenAPI 3.1](https://raw.githubusercontent.com/api-evangelist/liquidonate/refs/heads/main/openapi/liquidonate-magicmatch-openapi.yml): API Evangelist reconstruction from the published Postman collection. LiquiDonate publishes no OpenAPI.
- [ReturnsDirect OpenAPI 3.1](https://raw.githubusercontent.com/api-evangelist/liquidonate/refs/heads/main/openapi/liquidonate-returnsdirect-openapi.yml): reconstruction, includes the webhooks block.
- [ReturnsDirect AsyncAPI 3.0](https://raw.githubusercontent.com/api-evangelist/liquidonate/refs/heads/main/asyncapi/liquidonate-returnsdirect-asyncapi.yml): generated from the published 7-event webhook catalog.
- [APIs.json](https://raw.githubusercontent.com/api-evangelist/liquidonate/refs/heads/main/apis.yml)

## Artifacts

- [Authentication profile](https://raw.githubusercontent.com/api-evangelist/liquidonate/refs/heads/main/authentication/liquidonate-authentication.yml)
- [API conventions](https://raw.githubusercontent.com/api-evangelist/liquidonate/refs/heads/main/conventions/liquidonate-conventions.yml)
- [Error catalog](https://raw.githubusercontent.com/api-evangelist/liquidonate/refs/heads/main/errors/liquidonate-problem-types.yml)
- [Lifecycle and status](https://raw.githubusercontent.com/api-evangelist/liquidonate/refs/heads/main/lifecycle/liquidonate-lifecycle.yml)
- [Data model](https://raw.githubusercontent.com/api-evangelist/liquidonate/refs/heads/main/data-model/liquidonate-data-model.yml)
- [Sandbox and credentials](https://raw.githubusercontent.com/api-evangelist/liquidonate/refs/heads/main/sandbox/liquidonate-sandbox.yml)
- [Item category vocabulary, 171 terms](https://raw.githubusercontent.com/api-evangelist/liquidonate/refs/heads/main/vocabulary/liquidonate-category-types.yml)
- [Agent Skills index](https://raw.githubusercontent.com/api-evangelist/liquidonate/refs/heads/main/skills/_index.yml)
- [Conformance](https://raw.githubusercontent.com/api-evangelist/liquidonate/refs/heads/main/conformance/liquidonate-conformance.yml)
- [Domain security probe](https://raw.githubusercontent.com/api-evangelist/liquidonate/refs/heads/main/security/liquidonate-domain-security.yml)

## Docs

- [Developer hub](https://docs.liquidonate.com)
- [MagicMatch Postman collection](https://documenter.getpostman.com/view/21205794/2sA3QteBZu)
- [ReturnsDirect Postman collection](https://documenter.getpostman.com/view/28612413/2sBXierZMP)
- [Integrations and partners](https://www.liquidonate.com/integrations)
- [Shopify application](https://apps.shopify.com/liquidonate)
- [Pricing](https://www.liquidonate.com/pricing)
- [Help center](https://help.liquidonate.com)
- [Status page](https://status.liquidonate.com/)
- [Blog](https://www.liquidonate.com/blog)
- [Terms of service](https://www.liquidonate.com/terms-of-service)
- [Privacy policy](https://www.liquidonate.com/privacy-policy)

## Things an agent must know

- Neither API supports idempotency keys. `matchAndShip`, `ship` and `donate` commit real logistics and purchase real postage. Never blind-retry them; reconcile on `trackingNumber` and escalate ambiguous outcomes to a human.
- `estimateMatchAndShip` is the only reversible preview operation. Always pass the returned `match_uuid` into `matchAndShip` or the match and rate may change.
- After `match`, calling `attachLabelsToMatch` is mandatory when you buy your own label, otherwise the nonprofit is never notified and no donation receipt is generated.
- `ship` performs no matching and generates no donation receipt. Do not pair it with `match`.
- Excluded from the matching flow: furniture, mattresses, drug paraphernalia, anything over 50 kg, and anything with a Damaged return reason. Route those to `donate`.
- `categoryTypes` values must come from the published 171-term vocabulary.
- ReturnsDirect signatures must be computed over the exact raw request bytes; re-serializing parsed JSON before hashing is the usual cause of `401 Invalid signature`.
- `refund.flagged` means a refund was held for review, not that money moved.
- LiquiDonate publishes no MCP server, no SDKs in any package registry, no OpenAPI, no changelog, no security.txt and no SLA.