Reference
WeRefund API
Verification, proof and follow-up above the merchant's existing PSP. The API lets your systems register orders, read the return window and the Policy Record of each order, follow return requests and observed refunds, and receive signed events.
Authentication
Every merchant route takes a secret API key with the Bearer scheme: Authorization: Bearer wr_live_…, or wr_test_… for test orders. Keys are created in your WeRefund dashboard and shown once. Public routes take none.
Platforms
Orders reach WeRefund through the connection to your store platform — Shopify Coming soon, WooCommerce, Magento, PrestaShop, BigCommerce, Wix — or through POST /v1/orders for a custom or headless store.
Errors
The one error envelope of /v1. Branch on code, never on message or on the HTTP status alone. Every refusal answers this one envelope.
The machine codes of /v1. Stable, snake_case.
One of authentication_required · bearer_not_accepted · csrf_failed · session_revoked · account_disabled · invalid_credentials · password_rejected · password_blank · reset_link_invalid · reset_link_expired · reset_link_already_used · invitation_invalid · invitation_expired · invitation_already_used · display_name_too_long · totp_enrollment_required · totp_required · totp_already_enrolled · totp_enrollment_not_started · invalid_totp · totp_throttled · owner_role_required · api_key_environment_invalid · api_key_scope_invalid · api_key_label_too_long · api_key_limit_reached · api_key_not_found · api_key_prefix_exhausted · store_not_found · invitation_email_invalid · invitation_role_invalid · email_already_registered · member_not_found · last_owner · rate_limited · forbidden · internal_token_not_configured · route_not_found · method_not_allowed · api_version_unknown · api_version_retired · internal_error · idempotency_conflict · return_items_required · draft_not_found · draft_incomplete · policy_check_not_found · policy_verify_not_found · draft_check_in_progress · terms_changed · order_not_found · buyer_email_required · delivery_already_recorded · country_not_supported · formula_not_allowed_for_country · public_slug_locked · public_slug_taken · store_closed · badge_not_found · certificate_not_found · alert_not_found · privacy_url_required · terms_url_required · fee_schedule_missing · option_required · return_window_not_open · return_request_exists · return_item_not_returnable · return_quantity_exceeds_ordered · review_not_eligible · endpoint_url_not_public · validation_failed · idempotency_key_required · cursor_invalid · return_address_required · return_request_state_conflict · tracking_url_invalid · body_unparsable · review_already_flagged · store_required · order_reference_ambiguous · subscribed_event_unknown · connect_state_invalid · ticket_read_only · email_change_link_invalid.
For a human reader, in English. Never branch on it.
Optional advice for the developer.
{
"error": {
"code": "order_not_found",
"message": "No order with that reference on this tenant.",
"hint": "Order references are case sensitive."
}
}Orders
List orders
Plannedhttps://api.werefund.com/v1/ordersAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Opaque cursor from next_cursor. Keyset pagination; there is no offset.
Page size.
Response fields · 200
The merchant's own order reference, exactly as supplied. Case sensitive.
The store handle: store.public_slug, the value of data-store in the banner snippet.
ISO 4217 code, upper case. USD, GBP or EUR for anything that carries a WeRefund fee.
Product lines, WeRefund fee line, shipping and tax excluded. In minor units of currency.
Shipping. In minor units of currency.
Tax. In minor units of currency.
As paid. In minor units of currency.
One of platform_fulfillment · merchant_declared · unknown.
One of pending · paid · partially_refunded · refunded · cancelled.
Public identifier of a policy version, pv_<n>_<version>.
Public identifier of a certificate, WR-<n>.
The attachment quality of the order's Policy Record (bis); no_applicable_version when no policy version applied, so no record exists; null while the order is not paid.
One of bracketed · read_before_purchase · read_after_purchase_unverified · read_after_purchase_changed · no_applicable_version.
Responses
- 200 — One page
- 400 — Codes:
cursor_invalid. - 401 — Codes:
authentication_required. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/orders \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Orders
Register an order
PlannedCustom / Headless. Idempotency-Key required, kept 24 h; the same key with another body answers 409. The store is the key's, or the one the body names.
https://api.werefund.com/v1/ordersAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Required. Kept 24 hours per key; the same key with another body answers 409 idempotency_conflict.
Request body
The public slug of the store. Required with a key that covers every store of the tenant (400 store_required); with a key bound to one store it may be left out, and naming another store answers 404 store_not_found.
The merchant's own order reference, exactly as supplied. Case sensitive.
ISO 4217 code, upper case. USD, GBP or EUR for anything that carries a WeRefund fee.
One of pending · paid · partially_refunded · refunded · cancelled.
Required when werefund_fee is present. Never logged in clear. An address WeRefund may not keep is recorded exactly like an order without one: 201, no option, no status and no code that tells why.
Unit price. In minor units of currency.
Tax of the whole line, when you know it. In minor units of currency.
As your platform gives it; never invented.
Shipping. In minor units of currency.
Tax of the whole order. In minor units of currency.
As paid, WeRefund fee line included. In minor units of currency.
The WeRefund option line of this order. In minor units of currency.
Response fields · 200
The merchant's own order reference, exactly as supplied. Case sensitive.
The store handle: store.public_slug, the value of data-store in the banner snippet.
ISO 4217 code, upper case. USD, GBP or EUR for anything that carries a WeRefund fee.
Product lines, WeRefund fee line, shipping and tax excluded. In minor units of currency.
Shipping. In minor units of currency.
Tax. In minor units of currency.
As paid. In minor units of currency.
One of platform_fulfillment · merchant_declared · unknown.
One of pending · paid · partially_refunded · refunded · cancelled.
Public identifier of a policy version, pv_<n>_<version>.
Public identifier of a certificate, WR-<n>.
The attachment quality of the order's Policy Record (bis); no_applicable_version when no policy version applied, so no record exists; null while the order is not paid.
One of bracketed · read_before_purchase · read_after_purchase_unverified · read_after_purchase_changed · no_applicable_version.
Public identifier of the line. Its public form is not written yet: never the internal id.
Unit price. In minor units of currency.
Tax of the whole line. In minor units of currency.
Set once, at recording; never rewritten.
As the platform gave it; null when there is none.
Responses
- 200 — The reference was already recorded in this store: the mutable fields are updated, the ones set once are untouched.
- 201 — OK
- 400 — Codes:
idempotency_key_required,store_required,buyer_email_required,body_unparsable. - 401 — Codes:
authentication_required. - 404 — Codes:
store_not_found. - 409 — Codes:
idempotency_conflict. - 422 — Codes:
validation_failed. - 429 — Codes:
rate_limited.
curl --request POST \ --url https://api.werefund.com/v1/orders \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
{
"external_order_id": "V-10482",
"order_number": "#V-10482",
"currency": "USD",
"placed_at": "2026-03-02T15:31:07Z",
"financial_status": "paid",
"buyer_email": "shopper@example.com",
"lines": [
{
"external_line_id": "1",
"sku": "VS-LIN-OS-M",
"title": "Linen overshirt, M",
"quantity": 1,
"unit_price_minor": 9800,
"tax_minor": null,
"image_url": "https://verso.example/wp-content/uploads/linen-overshirt.webp"
},
{
"external_line_id": "2",
"sku": "VS-CNV-TT",
"title": "Canvas tote",
"quantity": 1,
"unit_price_minor": 5000,
"tax_minor": null,
"image_url": null
}
],
"shipping_minor": 0,
"tax_minor": 0,
"total_minor": 14999,
"werefund_fee": {
"amount_minor": 199
}
}Orders
Retrieve an order
Plannedhttps://api.werefund.com/v1/orders/{order_id}Authorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Your own order reference, exactly as supplied when the order was registered. Case sensitive.
Response fields · 200
The merchant's own order reference, exactly as supplied. Case sensitive.
The store handle: store.public_slug, the value of data-store in the banner snippet.
ISO 4217 code, upper case. USD, GBP or EUR for anything that carries a WeRefund fee.
Product lines, WeRefund fee line, shipping and tax excluded. In minor units of currency.
Shipping. In minor units of currency.
Tax. In minor units of currency.
As paid. In minor units of currency.
One of platform_fulfillment · merchant_declared · unknown.
One of pending · paid · partially_refunded · refunded · cancelled.
Public identifier of a policy version, pv_<n>_<version>.
Public identifier of a certificate, WR-<n>.
The attachment quality of the order's Policy Record (bis); no_applicable_version when no policy version applied, so no record exists; null while the order is not paid.
One of bracketed · read_before_purchase · read_after_purchase_unverified · read_after_purchase_changed · no_applicable_version.
Public identifier of the line. Its public form is not written yet: never the internal id.
Unit price. In minor units of currency.
Tax of the whole line. In minor units of currency.
Set once, at recording; never rewritten.
As the platform gave it; null when there is none.
Responses
- 200 — OK
- 401 — Codes:
authentication_required. - 404 — Codes:
order_not_found. - 409 — Codes:
order_reference_ambiguous. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/orders/{order_id} \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Orders
Mark delivered
Plannedhttps://api.werefund.com/v1/orders/{order_id}Authorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Your own order reference, exactly as supplied when the order was registered. Case sensitive.
Request body
Mark delivered. Source merchant_declared; the first source wins.
Response fields · 200
The merchant's own order reference, exactly as supplied. Case sensitive.
The store handle: store.public_slug, the value of data-store in the banner snippet.
ISO 4217 code, upper case. USD, GBP or EUR for anything that carries a WeRefund fee.
Product lines, WeRefund fee line, shipping and tax excluded. In minor units of currency.
Shipping. In minor units of currency.
Tax. In minor units of currency.
As paid. In minor units of currency.
One of platform_fulfillment · merchant_declared · unknown.
One of pending · paid · partially_refunded · refunded · cancelled.
Public identifier of a policy version, pv_<n>_<version>.
Public identifier of a certificate, WR-<n>.
The attachment quality of the order's Policy Record (bis); no_applicable_version when no policy version applied, so no record exists; null while the order is not paid.
One of bracketed · read_before_purchase · read_after_purchase_unverified · read_after_purchase_changed · no_applicable_version.
Public identifier of the line. Its public form is not written yet: never the internal id.
Unit price. In minor units of currency.
Tax of the whole line. In minor units of currency.
Set once, at recording; never rewritten.
As the platform gave it; null when there is none.
Responses
- 200 — OK
- 400 — Codes:
body_unparsable. - 401 — Codes:
authentication_required. - 404 — Codes:
order_not_found. - 409 — Codes:
order_reference_ambiguous,delivery_already_recorded. - 422 — Codes:
validation_failed. - 429 — Codes:
rate_limited.
curl --request PATCH \ --url https://api.werefund.com/v1/orders/{order_id} \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Orders
Retrieve return window
PlannedReturn the remaining return window for an order, per line, as computed at delivery. The window is computed once, at delivery, and stored. This endpoint reads that stored value — it never recomputes it.
https://api.werefund.com/v1/orders/{order_id}/windowAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Your own order reference, exactly as supplied when the order was registered. Case sensitive.
Return the per-line breakdown as well as the order-level window. Defaults to true. Set it to false on high-volume polling to reduce the payload.
Response fields · 200
open, or closed once the window has closed (-1 is never returned).
Whole days remaining before the window closes. 0 on the final day; -1 is never returned — a closed window reports state: "closed".
The return deadline, in UTC. This value never changes once written.
The version of the merchant's return policy in force when the order was placed.
Responses
- 200 — OK
- 401 — Codes:
authentication_required. - 404 — Codes:
order_not_found. - 409 — Codes:
order_reference_ambiguous. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/orders/A-40917/window \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
{
"order_id": "A-40917",
"state": "open",
"days_left": 21,
"eligible_until": "2026-04-06T23:59:59Z",
"delivered_at": "2026-03-07T09:14:02Z",
"policy_version_id": "pv_8842_4",
"certificate_id": "WR-8842",
"lines": [
{
"sku": "LMP-CER-01",
"returnable": true,
"days_left": 21
}
]
}{
"error": {
"code": "order_not_found",
"message": "No order with that reference on this tenant.",
"hint": "Order references are case sensitive."
}
}Orders
Quote the option fee
Plannedhttps://api.werefund.com/v1/fee-quoteAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Product subtotal, in minor units.
Response fields · 200
Product subtotal. In minor units of currency.
ISO 4217 code, upper case. USD, GBP or EUR for anything that carries a WeRefund fee.
The WeRefund option fee for that basis. In minor units of currency.
Responses
- 200 — OK
- 401 — Codes:
authentication_required. - 409 — Codes:
fee_schedule_missing. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/fee-quote \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Policy Records
Retrieve the Policy Record
Plannedhttps://api.werefund.com/v1/orders/{order_id}/policy-recordAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Your own order reference, exactly as supplied when the order was registered. Case sensitive.
Response fields · 200
Public identifier of a Policy Record, its verify_token (22 base62 characters).
The merchant's own order reference, exactly as supplied. Case sensitive.
Public identifier of a certificate, WR-<n>.
Public identifier of a policy version, pv_<n>_<version>.
The store handle: store.public_slug, the value of data-store in the banner snippet.
One of delivery.
Joined from the order at delivery; not signed.
Joined from the PSP attribution; not signed.
Exactly what is signed. The deadline and the attachment quality are outside it.
Public identifier of a certificate, WR-<n>.
The store handle: store.public_slug, the value of data-store in the banner snippet.
Public identifier of a policy version, pv_<n>_<version>.
One of delivery.
Ed25519, base64, over canonical_body.
The signing key.
One of bracketed · read_before_purchase · read_after_purchase_unverified · read_after_purchase_changed.
Capture time minus purchase time, signed.
The PDF route of the surface that serves the record: GET /v1/policy-records/{verify_token}/pdf with an API key, GET /v1/shopper/orders/{purchase_id}/policy-record/pdf in the shopper session. Never a public route.
Short-lived link to the captured HTML.
Short-lived link to the capture.
Responses
- 200 — OK
- 401 — Codes:
authentication_required. - 404 — Codes:
order_not_found. - 409 — Codes:
order_reference_ambiguous. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/orders/{order_id}/policy-record \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
{
"verify_token": "fqqEKTNe4PMieB1EpMkeX1",
"order_id": "V-10482",
"certificate_id": "WR-8842",
"policy_version_id": "pv_8842_4",
"store": "verso",
"policy_url": "https://verso.example/returns",
"purchased_at": "2026-03-02T15:31:07Z",
"captured_at": "2026-03-02T15:33:40Z",
"return_window_days": 30,
"window_starts_from": "delivery",
"return_deadline": "2026-04-04T23:59:59Z",
"transaction_id": "pi_3Qa1b2C3d4E5f6G7h8I9j0K1",
"sha256": "8945e06946f858f9f2f0ce9893a32cf7946f89450f1e12e94a74eea6ddef30bf",
"canonical_body": {
"certificate_public_id": "WR-8842",
"store_public_slug": "verso",
"policy_url": "https://verso.example/returns",
"policy_version_public_id": "pv_8842_4",
"policy_version_sha256": "8945e06946f858f9f2f0ce9893a32cf7946f89450f1e12e94a74eea6ddef30bf",
"external_order_id": "V-10482",
"purchased_at": "2026-03-02T15:31:07Z",
"captured_at": "2026-03-02T15:33:40Z",
"return_window_days": 30,
"window_starts_from": "delivery"
},
"signature": "bJQXIxsajtSO3Gq2GdkDvrTSEGo5jdvWolzOr7OYjnlTJVCgqkV8znmxyPNbXIU2fMR7fJlEulNxOb7sP2IkDg==",
"kid": "wr-2026-01",
"attachment_quality": "read_after_purchase_unverified",
"attachment_offset_seconds": 153,
"pdf_url": "https://api.werefund.com/v1/policy-records/fqqEKTNe4PMieB1EpMkeX1/pdf",
"html_url": null,
"screenshot_url": null
}Policy Records
List Policy Records
Plannedhttps://api.werefund.com/v1/policy-recordsAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Keep the records of one attachment quality (bis).
One of bracketed · read_before_purchase · read_after_purchase_unverified · read_after_purchase_changed.
Opaque cursor from next_cursor. Keyset pagination; there is no offset.
Page size.
Response fields · 200
Public identifier of a Policy Record, its verify_token (22 base62 characters).
The merchant's own order reference, exactly as supplied. Case sensitive.
The store handle: store.public_slug, the value of data-store in the banner snippet.
Public identifier of a certificate, WR-<n>.
Public identifier of a policy version, pv_<n>_<version>.
One of bracketed · read_before_purchase · read_after_purchase_unverified · read_after_purchase_changed.
Responses
- 200 — One page
- 400 — Codes:
cursor_invalid. - 401 — Codes:
authentication_required. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/policy-records \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Policy Records
Count Policy Records
PlannedThe count by attachment quality, read_after_purchase_changed included (index (store_id, attachment_quality)).
https://api.werefund.com/v1/policy-records/summaryAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Response fields · 200
Responses
- 200 — OK
- 401 — Codes:
authentication_required. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/policy-records/summary \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Policy Records
Policy Record PDF
PlannedThe record is designated by its verify_token. The merchant's copy; no public route serves the PDF.
https://api.werefund.com/v1/policy-records/{verify_token}/pdfAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
The record's verify_token.
Responses
- 200 — The PDF
- 401 — Codes:
authentication_required. - 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/policy-records/{verify_token}/pdf \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Verification
List certificates
The certificates the key covers -- every store of the account for an account key, its own store for a key bound to a store. A closed store keeps its certificate, read as verification_unavailable.
https://api.werefund.com/v1/certificatesAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Response fields · 200
Responses
- 200 — The list
- 401 — Codes:
authentication_required. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/certificates \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Verification
Retrieve a certificate
https://api.werefund.com/v1/certificates/{certificate_id}Authorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
WR-<n>.
Response fields · 200
Public identifier of a certificate, WR-<n>.
The store handle: store.public_slug, the value of data-store in the banner snippet.
The only verification state served on any surface. Internal states never leave the server.
One of verified · reviewing_changes · verification_unavailable.
verification_reason_code.
Public identifier of a policy version, pv_<n>_<version>.
A checklist item of the standard.
The merchant's own text, quoted literally, never paraphrased, summarised or cut. null when the item has no passage to quote, or when a passage found by the injection check cannot be read back from the stored text with the same SHA-256.
Start of the passage in the normalised text of the policy, in characters.
End of the passage in the normalised text of the policy, in characters, excluded.
Invisible characters removed from the page, on the points of no_model_directed_instructions when there is at least one — they have no position to quote, and a page can fail on them alone. null on every other point.
The state changes, projected to the three served values. Merchant only.
The only verification state served on any surface. Internal states never leave the server.
One of verified · reviewing_changes · verification_unavailable.
Responses
- 200 — OK
- 401 — Codes:
authentication_required. - 404 — Codes:
certificate_not_found-- unknown, another merchant's, or, for a key bound to a store, another store's: the same body. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/certificates/{certificate_id} \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Verification
Request verification
An on-demand re-test. The request reads no page -- it queues a run, which reads the pages and applies its verdict to the certificate. A store still waiting for its first verification gets the sign-up run; any other gets the re-test run, which also reads the privacy page first. When a re-test of this store is already queued or running, none is added and its requested_at is served. One per hour and per store.
https://api.werefund.com/v1/certificates/{certificate_id}/verifyAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
WR-<n>.
Response fields · 202
Public identifier of a certificate, WR-<n>.
Responses
- 202 — Queued, or already queued
- 401 — Codes:
authentication_required. - 404 — Codes:
certificate_not_found-- unknown, another merchant's, or, for a key bound to a store, another store's: the same body. - 409 — Codes:
store_closed-- a closed store is never re-tested. - 429 — Codes:
rate_limited-- also the one re-test per hour and per store, with itsRetry-After.
curl --request POST \ --url https://api.werefund.com/v1/certificates/{certificate_id}/verify \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Verification
List policy versions
Plannedhttps://api.werefund.com/v1/policy-versionsAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Opaque cursor from next_cursor. Keyset pagination; there is no offset.
Page size.
Response fields · 200
Public identifier of a policy version, pv_<n>_<version>.
Public identifier of a policy version, pv_<n>_<version>.
Responses
- 200 — One page
- 400 — Codes:
cursor_invalid. - 401 — Codes:
authentication_required. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/policy-versions \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Verification
Retrieve a policy version
Plannedhttps://api.werefund.com/v1/policy-versions/{policy_version_id}Authorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
pv_<n>_<version>.
Response fields · 200
Public identifier of a policy version, pv_<n>_<version>.
Public identifier of a policy version, pv_<n>_<version>.
Responses
- 200 — OK
- 401 — Codes:
authentication_required. - 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/policy-versions/{policy_version_id} \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Verification
Read the standard in force
Plannedhttps://api.werefund.com/v1/standard/currentAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Response fields · 200
Responses
- 200 — OK
- 401 — Codes:
authentication_required. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/standard/current \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Return requests
List return requests
Plannedhttps://api.werefund.com/v1/returnsAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
One of sent · awaiting_store_response · accepted · in_transit · closed.
Whose turn it is in the conversation, derived from its last message.
One of merchant · shopper.
Opaque cursor from next_cursor. Keyset pagination; there is no offset.
Page size.
Response fields · 200
Public identifier of a return request, rr_<10 Crockford base32>.
The merchant's own order reference, exactly as supplied. Case sensitive.
One of sent · awaiting_store_response · accepted · in_transit · closed.
Why the item goes back.
One of changed_my_mind · not_as_expected · arrived_damaged.
The display name the shopper chose, or null: the screen then says "Shopper". Served in return requests and their conversation only; orders and Policy Records carry no name.
ISO 4217 code, upper case. USD, GBP or EUR for anything that carries a WeRefund fee.
How a closed return request ended. no_response is set by the server: 30 days after merchant_notified_at while the request awaits the store; once in transit, 30 days after the reception set by the carrier API (UPS, FedEx, DHL, Royal Mail) or after the tracking was submitted (USPS, Others); never while accepted, and never for a parcel read by API that is not delivered. Its public label is Rico's to write.
One of refund_issued · exchange · refused · no_response.
One of merchant · system.
Public identifier of a ticket (the conversation of a return request), tk_<10 Crockford base32>.
Responses
- 200 — One page
- 400 — Codes:
cursor_invalid. - 401 — Codes:
authentication_required. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/returns \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Return requests
Retrieve a return request
Plannedhttps://api.werefund.com/v1/returns/{return_request_id}Authorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
rr_….
Response fields · 200
Public identifier of a return request, rr_<10 Crockford base32>.
The merchant's own order reference, exactly as supplied. Case sensitive.
One of sent · awaiting_store_response · accepted · in_transit · closed.
Why the item goes back.
One of changed_my_mind · not_as_expected · arrived_damaged.
The display name the shopper chose, or null: the screen then says "Shopper". Served in return requests and their conversation only; orders and Policy Records carry no name.
ISO 4217 code, upper case. USD, GBP or EUR for anything that carries a WeRefund fee.
Its public form is not written yet: never the internal id.
ISO 4217 code, upper case. USD, GBP or EUR for anything that carries a WeRefund fee.
One of pending · issued · failed · reversed.
How a closed return request ended. no_response is set by the server: 30 days after merchant_notified_at while the request awaits the store; once in transit, 30 days after the reception set by the carrier API (UPS, FedEx, DHL, Royal Mail) or after the tracking was submitted (USPS, Others); never while accepted, and never for a parcel read by API that is not delivered. Its public label is Rico's to write.
One of refund_issued · exchange · refused · no_response.
One of merchant · system.
Public identifier of a ticket (the conversation of a return request), tk_<10 Crockford base32>.
Responses
- 200 — OK
- 401 — Codes:
authentication_required. - 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/returns/{return_request_id} \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Return requests
Accept a return and give the return address
Plannedhttps://api.werefund.com/v1/returns/{return_request_id}/acceptAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
rr_….
Request body
Response fields · 200
Public identifier of a return request, rr_<10 Crockford base32>.
The merchant's own order reference, exactly as supplied. Case sensitive.
One of sent · awaiting_store_response · accepted · in_transit · closed.
Why the item goes back.
One of changed_my_mind · not_as_expected · arrived_damaged.
The display name the shopper chose, or null: the screen then says "Shopper". Served in return requests and their conversation only; orders and Policy Records carry no name.
ISO 4217 code, upper case. USD, GBP or EUR for anything that carries a WeRefund fee.
Its public form is not written yet: never the internal id.
ISO 4217 code, upper case. USD, GBP or EUR for anything that carries a WeRefund fee.
One of pending · issued · failed · reversed.
How a closed return request ended. no_response is set by the server: 30 days after merchant_notified_at while the request awaits the store; once in transit, 30 days after the reception set by the carrier API (UPS, FedEx, DHL, Royal Mail) or after the tracking was submitted (USPS, Others); never while accepted, and never for a parcel read by API that is not delivered. Its public label is Rico's to write.
One of refund_issued · exchange · refused · no_response.
One of merchant · system.
Public identifier of a ticket (the conversation of a return request), tk_<10 Crockford base32>.
Responses
- 200 — OK
- 400 — Codes:
body_unparsable. - 401 — Codes:
authentication_required. - 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 409 — Codes:
return_address_required,return_request_state_conflict. - 422 — Codes:
validation_failed. - 429 — Codes:
rate_limited.
curl --request POST \ --url https://api.werefund.com/v1/returns/{return_request_id}/accept \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
{
"return_address": null
}{
"return_request_id": "rr_9ZB4K7M2QX",
"order_id": "V-10482",
"order_number": "#V-10482",
"state": "accepted",
"reason": "not_as_expected",
"reason_text": "The fabric is heavier than on the product page.",
"already_contacted_merchant": false,
"currency": "USD",
"requested_amount_minor": 9800,
"requested_amount_includes_tax": false,
"items": [
{
"line_id": "li_7K2M9Q4XRD",
"sku": "VS-LIN-OS-M",
"title": "Linen overshirt, M",
"quantity": 1,
"unit_price_minor": 9800,
"line_tax_minor": null,
"line_amount_minor": 9800,
"image_url": "https://verso.example/wp-content/uploads/linen-overshirt.webp"
}
],
"requested_at": "2026-03-12T18:20:05Z",
"merchant_notified_at": "2026-03-12T18:20:05Z",
"window_expires_at": "2026-04-04T23:59:59Z",
"return_address": {
"company_name": "Verso Studio LLC",
"address_line1": "1200 Harbor Way",
"address_line2": "Suite 4",
"city": "Oakland",
"region": "CA",
"postal_code": "94607",
"country_code": "US"
},
"shipment": null,
"refunds": [],
"outcome": null,
"outcome_message": null,
"decided_by": null,
"decided_at": null,
"closed_at": null,
"ticket_id": "tk_3HW8N6RJ2P"
}Return requests
Declare the parcel received (USPS, Others)
PlannedOnly for usps and other: for the four carriers read by API, Delivered sets the reception. Closes nothing.
https://api.werefund.com/v1/returns/{return_request_id}/mark-receivedAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
rr_….
Request body
Defaults to now.
Response fields · 200
Public identifier of a return request, rr_<10 Crockford base32>.
The merchant's own order reference, exactly as supplied. Case sensitive.
One of sent · awaiting_store_response · accepted · in_transit · closed.
Why the item goes back.
One of changed_my_mind · not_as_expected · arrived_damaged.
The display name the shopper chose, or null: the screen then says "Shopper". Served in return requests and their conversation only; orders and Policy Records carry no name.
ISO 4217 code, upper case. USD, GBP or EUR for anything that carries a WeRefund fee.
Its public form is not written yet: never the internal id.
ISO 4217 code, upper case. USD, GBP or EUR for anything that carries a WeRefund fee.
One of pending · issued · failed · reversed.
How a closed return request ended. no_response is set by the server: 30 days after merchant_notified_at while the request awaits the store; once in transit, 30 days after the reception set by the carrier API (UPS, FedEx, DHL, Royal Mail) or after the tracking was submitted (USPS, Others); never while accepted, and never for a parcel read by API that is not delivered. Its public label is Rico's to write.
One of refund_issued · exchange · refused · no_response.
One of merchant · system.
Public identifier of a ticket (the conversation of a return request), tk_<10 Crockford base32>.
Responses
- 200 — OK
- 400 — Codes:
body_unparsable. - 401 — Codes:
authentication_required. - 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 409 — Codes:
return_request_state_conflict. - 422 — Codes:
validation_failed. - 429 — Codes:
rate_limited.
curl --request POST \ --url https://api.werefund.com/v1/returns/{return_request_id}/mark-received \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Return requests
Close a return request
Plannedhttps://api.werefund.com/v1/returns/{return_request_id}/closeAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
rr_….
Request body
One of refund_issued · exchange · refused.
Optional message to the shopper, kept as outcome_message.
Response fields · 200
Public identifier of a return request, rr_<10 Crockford base32>.
The merchant's own order reference, exactly as supplied. Case sensitive.
One of sent · awaiting_store_response · accepted · in_transit · closed.
Why the item goes back.
One of changed_my_mind · not_as_expected · arrived_damaged.
The display name the shopper chose, or null: the screen then says "Shopper". Served in return requests and their conversation only; orders and Policy Records carry no name.
ISO 4217 code, upper case. USD, GBP or EUR for anything that carries a WeRefund fee.
Its public form is not written yet: never the internal id.
ISO 4217 code, upper case. USD, GBP or EUR for anything that carries a WeRefund fee.
One of pending · issued · failed · reversed.
How a closed return request ended. no_response is set by the server: 30 days after merchant_notified_at while the request awaits the store; once in transit, 30 days after the reception set by the carrier API (UPS, FedEx, DHL, Royal Mail) or after the tracking was submitted (USPS, Others); never while accepted, and never for a parcel read by API that is not delivered. Its public label is Rico's to write.
One of refund_issued · exchange · refused · no_response.
One of merchant · system.
Public identifier of a ticket (the conversation of a return request), tk_<10 Crockford base32>.
Responses
- 200 — OK
- 400 — Codes:
body_unparsable. - 401 — Codes:
authentication_required. - 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 409 — Codes:
return_request_state_conflict. - 422 — Codes:
validation_failed. - 429 — Codes:
rate_limited.
curl --request POST \ --url https://api.werefund.com/v1/returns/{return_request_id}/close \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
{
"outcome": "exchange",
"message": "We have sent you the size L instead."
}{
"return_request_id": "rr_4MX8Q2ZB7K",
"order_id": "V-10531",
"order_number": "#V-10531",
"state": "closed",
"reason": "changed_my_mind",
"reason_text": null,
"already_contacted_merchant": false,
"currency": "USD",
"requested_amount_minor": 9800,
"requested_amount_includes_tax": false,
"items": [
{
"line_id": "li_6WQ3N8TB5J",
"sku": "VS-LIN-OS-M",
"title": "Linen overshirt, M",
"quantity": 1,
"unit_price_minor": 9800,
"line_tax_minor": null,
"line_amount_minor": 9800,
"image_url": "https://verso.example/wp-content/uploads/linen-overshirt.webp"
}
],
"requested_at": "2026-03-20T08:11:42Z",
"merchant_notified_at": "2026-03-20T08:11:42Z",
"window_expires_at": "2026-04-16T23:59:59Z",
"return_address": null,
"shipment": null,
"refunds": [],
"outcome": "exchange",
"outcome_message": "We have sent you the size L instead.",
"decided_by": "merchant",
"decided_at": "2026-03-21T14:03:09Z",
"closed_at": "2026-03-21T14:03:09Z",
"ticket_id": "tk_8PQ2V5XMC7"
}Return requests
List conversations
PlannedRead only. « The merchant replies from their dashboard alone »: no route of this surface writes in a conversation.
https://api.werefund.com/v1/ticketsAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Whose turn it is in the conversation, derived from its last message.
One of merchant · shopper.
Opaque cursor from next_cursor. Keyset pagination; there is no offset.
Page size.
Response fields · 200
Public identifier of a ticket (the conversation of a return request), tk_<10 Crockford base32>.
Public identifier of a return request, rr_<10 Crockford base32>.
The merchant's own order reference, exactly as supplied. Case sensitive.
The display name the shopper chose, or null: the screen then says "Shopper".
One of sent · awaiting_store_response · accepted · in_transit · closed.
Whose turn it is, derived from the last message; null once the request is closed.
One of merchant · shopper.
true once the return request is closed (default). A message changes no state.
Responses
- 200 — One page
- 400 — Codes:
cursor_invalid. - 401 — Codes:
authentication_required. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/tickets \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Return requests
Read a conversation
PlannedThe conversation of a return request, with its messages and short-lived media links. Read only.
https://api.werefund.com/v1/tickets/{ticket_id}Authorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
tk_….
Response fields · 200
Public identifier of a ticket (the conversation of a return request), tk_<10 Crockford base32>.
Public identifier of a return request, rr_<10 Crockford base32>.
The merchant's own order reference, exactly as supplied. Case sensitive.
The display name the shopper chose, or null: the screen then says "Shopper".
One of sent · awaiting_store_response · accepted · in_transit · closed.
Whose turn it is, derived from the last message; null once the request is closed.
One of merchant · shopper.
true once the return request is closed (default). A message changes no state.
system is the server (the mention, a transmission). WeRefund staff can see the media but never writes in the conversation.
One of shopper · merchant · system.
Not set today: no route writes it. Always null.
Responses
- 200 — OK
- 401 — Codes:
authentication_required. - 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/tickets/{ticket_id} \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Refunds
List refund events
PlannedRead only. There is no refund declaration.
https://api.werefund.com/v1/refund-eventsAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Filter by order reference.
Opaque cursor from next_cursor. Keyset pagination; there is no offset.
Page size.
Response fields · 200
Its public form is not written yet: never the internal id.
The merchant's own order reference, exactly as supplied. Case sensitive.
Public identifier of a return request, rr_<10 Crockford base32>.
ISO 4217 code, upper case. USD, GBP or EUR for anything that carries a WeRefund fee.
One of pending · issued · failed · reversed.
One of declared · corroborated · psp_terminal.
One of merchant · psp_reversal · unknown.
Responses
- 200 — One page
- 400 — Codes:
cursor_invalid. - 401 — Codes:
authentication_required. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/refund-events \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Reviews and measures
List reviews
Plannedhttps://api.werefund.com/v1/reviewsAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Keep the reviews with (true) or without (false) a reply.
Keep the reviews you reported (true) or not (false).
Opaque cursor from next_cursor. Keyset pagination; there is no offset.
Page size.
Response fields · 200
Public identifier of a review, its share_slug (12 base62 characters).
How a closed return request ended. no_response is set by the server: 30 days after merchant_notified_at while the request awaits the store; once in transit, 30 days after the reception set by the carrier API (UPS, FedEx, DHL, Royal Mail) or after the tracking was submitted (USPS, Others); never while accepted, and never for a parcel read by API that is not delivered. Its public label is Rico's to write.
One of refund_issued · exchange · refused · no_response.
« Alison M. » or « A shopper », set at publication.
Declared by the shopper, set at publication.
« N recorded returns ».
The merchant's own order reference, exactly as supplied. Case sensitive.
Public identifier of a return request, rr_<10 Crockford base32>.
You reported this review; it stays visible while WeRefund moderation examines it.
Responses
- 200 — One page
- 400 — Codes:
cursor_invalid. - 401 — Codes:
authentication_required. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/reviews \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Reviews and measures
Rating summary
Plannedhttps://api.werefund.com/v1/reviews/summaryAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
The store's public slug. Required with a key that covers every store of the tenant (store_required); with a key bound to one store it may be left out, and naming another store answers 404.
Response fields · 200
Simple mean, one decimal. null below RATING_MIN_REVIEWS.
Responses
- 200 — OK
- 400 — Codes:
store_required. - 401 — Codes:
authentication_required. - 404 — Codes:
store_not_found. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/reviews/summary \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Reviews and measures
Retrieve a review
Plannedhttps://api.werefund.com/v1/reviews/{review_id}Authorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
The review's share_slug.
Response fields · 200
Public identifier of a review, its share_slug (12 base62 characters).
How a closed return request ended. no_response is set by the server: 30 days after merchant_notified_at while the request awaits the store; once in transit, 30 days after the reception set by the carrier API (UPS, FedEx, DHL, Royal Mail) or after the tracking was submitted (USPS, Others); never while accepted, and never for a parcel read by API that is not delivered. Its public label is Rico's to write.
One of refund_issued · exchange · refused · no_response.
« Alison M. » or « A shopper », set at publication.
Declared by the shopper, set at publication.
« N recorded returns ».
The merchant's own order reference, exactly as supplied. Case sensitive.
Public identifier of a return request, rr_<10 Crockford base32>.
You reported this review; it stays visible while WeRefund moderation examines it.
Responses
- 200 — OK
- 401 — Codes:
authentication_required. - 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/reviews/{review_id} \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Reviews and measures
Reply publicly to a review
PlannedA reply changes neither the rating nor the order of the reviews.
https://api.werefund.com/v1/reviews/{review_id}/replyAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
The review's share_slug.
Request body
Response fields · 201
Responses
- 201 — OK
- 400 — Codes:
body_unparsable. - 401 — Codes:
authentication_required. - 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 422 — Codes:
validation_failed. - 429 — Codes:
rate_limited.
curl --request POST \ --url https://api.werefund.com/v1/reviews/{review_id}/reply \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Reviews and measures
Edit the reply
Plannedhttps://api.werefund.com/v1/reviews/{review_id}/replyAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
The review's share_slug.
Request body
Response fields · 200
Responses
- 200 — OK
- 400 — Codes:
body_unparsable. - 401 — Codes:
authentication_required. - 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 422 — Codes:
validation_failed. - 429 — Codes:
rate_limited.
curl --request PATCH \ --url https://api.werefund.com/v1/reviews/{review_id}/reply \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Reviews and measures
Report a review of your store
PlannedThe report goes to WeRefund moderation, which decides alone. The review stays visible while it is examined, and a report never removes a review by itself (16 CFR 465).
https://api.werefund.com/v1/reviews/{review_id}/flagAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
The review's share_slug.
Request body
One of personal_data · abusive · spam · not_about_return · other.
Responses
- 201 — Reported; the review stays visible
- 400 — Codes:
body_unparsable. - 401 — Codes:
authentication_required. - 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 409 — Codes:
review_already_flagged. - 422 — Codes:
validation_failed. - 429 — Codes:
rate_limited.
curl --request POST \ --url https://api.werefund.com/v1/reviews/{review_id}/flag \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Reviews and measures
Read conduct measures
Plannedhttps://api.werefund.com/v1/measuresAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
The store's public slug. Required with a key that covers every store of the tenant (store_required); with a key bound to one store it may be left out, and naming another store answers 404.
Response fields · 200
Responses
- 200 — OK
- 400 — Codes:
store_required. - 401 — Codes:
authentication_required. - 404 — Codes:
store_not_found. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/measures \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Fees and statements
Fee journal
Plannedhttps://api.werefund.com/v1/feesAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
A settlement period, YYYY-MM-1 or YYYY-MM-2 (1st–15th, 16th–end).
Opaque cursor from next_cursor. Keyset pagination; there is no offset.
Page size.
Response fields · 200
Public identifier of a journal line. Its public form is not written yet: never the internal id.
One of fee_collected · fee_reversed_cancellation · partner_share · adjustment.
Signed, in minor units.
ISO 4217 code, upper case. USD, GBP or EUR for anything that carries a WeRefund fee.
The merchant's own order reference, exactly as supplied. Case sensitive.
Public identifier of a fee statement, FS-<CUR>-<YYYY>-<000123>.
Responses
- 200 — One page
- 400 — Codes:
cursor_invalid. - 401 — Codes:
authentication_required. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/fees \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Fees and statements
List statements
Plannedhttps://api.werefund.com/v1/statementsAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Opaque cursor from next_cursor. Keyset pagination; there is no offset.
Page size.
Response fields · 200
Public identifier of a fee statement, FS-<CUR>-<YYYY>-<000123>.
ISO 4217 code, upper case. USD, GBP or EUR for anything that carries a WeRefund fee.
One of open · issued · debit_pending · paid · debit_failed · link_sent · overdue · written_off · void.
Negative when reversals win (then void).
How it was paid (settlement_attempt.method).
One of direct_debit · payment_link · bank_transfer.
Responses
- 200 — One page
- 400 — Codes:
cursor_invalid. - 401 — Codes:
authentication_required. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/statements \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Fees and statements
Retrieve a statement
Plannedhttps://api.werefund.com/v1/statements/{statement_id}Authorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
The statement_number.
Response fields · 200
Public identifier of a fee statement, FS-<CUR>-<YYYY>-<000123>.
ISO 4217 code, upper case. USD, GBP or EUR for anything that carries a WeRefund fee.
One of open · issued · debit_pending · paid · debit_failed · link_sent · overdue · written_off · void.
Negative when reversals win (then void).
How it was paid (settlement_attempt.method).
One of direct_debit · payment_link · bank_transfer.
Responses
- 200 — OK
- 401 — Codes:
authentication_required. - 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/statements/{statement_id} \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Fees and statements
Statement PDF
Plannedhttps://api.werefund.com/v1/statements/{statement_id}/pdfAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
The statement_number.
Responses
- 200 — The PDF
- 401 — Codes:
authentication_required. - 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/statements/{statement_id}/pdf \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Fees and statements
Statement CSV
Plannedhttps://api.werefund.com/v1/statements/{statement_id}/csvAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
The statement_number.
Responses
- 200 — The CSV
- 401 — Codes:
authentication_required. - 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/statements/{statement_id}/csv \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Fees and statements
Get a payment link
Plannedhttps://api.werefund.com/v1/statements/{statement_id}/payment-linkAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
The statement_number.
Response fields · 200
Public identifier of a fee statement, FS-<CUR>-<YYYY>-<000123>.
Responses
- 200 — OK
- 401 — Codes:
authentication_required. - 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 429 — Codes:
rate_limited.
curl --request POST \ --url https://api.werefund.com/v1/statements/{statement_id}/payment-link \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Connections
List connections
Plannedhttps://api.werefund.com/v1/connectionsAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Response fields · 200
Responses
- 200 — The list
- 401 — Codes:
authentication_required. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/connections \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Connections
Recent connection events
Plannedhttps://api.werefund.com/v1/connections/{connection_id}/eventsAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Page size.
Response fields · 200
Responses
- 200 — The list
- 401 — Codes:
authentication_required. - 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/connections/{connection_id}/events \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Alerts and events
List alerts
The alerts within the key's scope, newest first (opened_at, then the alert): every alert of the merchant for a tenant key, its own store's only for a key bound to a store.
https://api.werefund.com/v1/alertsAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Opaque cursor from next_cursor. Keyset pagination; there is no offset.
Page size.
Response fields · 200
al_ followed by 10 Crockford base32 characters: never the internal id.
One of info · warning · critical.
Responses
- 200 — One page
- 400 — Codes:
cursor_invalid-- unreadable, altered, or replayed outside the scope it was issued for. - 401 — Codes:
authentication_required. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/alerts \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Alerts and events
Acknowledge an alert
https://api.werefund.com/v1/alerts/{alert_id}/acknowledgeAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Public identifier of an alert: al_ followed by 10 Crockford base32 characters.
Response fields · 200
al_ followed by 10 Crockford base32 characters: never the internal id.
One of info · warning · critical.
Responses
- 200 — OK
- 401 — Codes:
authentication_required. - 404 — Codes:
alert_not_found-- unknown, another merchant's, or, for a key bound to a store, another store's: the same response. - 429 — Codes:
rate_limited.
curl --request POST \ --url https://api.werefund.com/v1/alerts/{alert_id}/acknowledge \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Alerts and events
Event journal
Plannedhttps://api.werefund.com/v1/eventsAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Opaque cursor from next_cursor. Keyset pagination; there is no offset.
Page size.
Response fields · 200
One of order.recorded · order.delivered · order.cancelled · policy_record.created · refund.issued_observed · refund.reversed_observed · policy.change_detected · policy.version_created · verification.state_changed · return_request.created · return_request.accepted · return_shipment.declared · return_shipment.delivered · return_request.closed · review.published · review.replied · rating.updated · measures.updated · fee.collected · fee.reversed · fee_statement.issued · fee_statement.paid · fee_statement.payment_link_issued · fee_statement.overdue · ticket.opened · ticket.message_created · alert.opened · alert.resolved · standard.version_published · dsr.received.
Responses
- 200 — One page
- 400 — Codes:
cursor_invalid. - 401 — Codes:
authentication_required. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/events \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Alerts and events
Replay events to an endpoint
Plannedhttps://api.werefund.com/v1/events/replayAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Request body
Response fields · 202
Responses
- 202 — OK
- 400 — Codes:
body_unparsable. - 401 — Codes:
authentication_required. - 422 — Codes:
validation_failed. - 429 — Codes:
rate_limited.
curl --request POST \ --url https://api.werefund.com/v1/events/replay \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Webhook endpoints
List endpoints
Plannedhttps://api.werefund.com/v1/webhook-endpointsAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Response fields · 200
Responses
- 200 — The list
- 401 — Codes:
authentication_required. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/webhook-endpoints \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Webhook endpoints
Remove endpoint
Plannedhttps://api.werefund.com/v1/webhook-endpoints/{endpoint_id}Authorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Response fields · 200
Its public form is not written yet: never the internal id.
One of order.recorded · order.delivered · order.cancelled · policy_record.created · refund.issued_observed · refund.reversed_observed · policy.change_detected · policy.version_created · verification.state_changed · return_request.created · return_request.accepted · return_shipment.declared · return_shipment.delivered · return_request.closed · review.published · review.replied · rating.updated · measures.updated · fee.collected · fee.reversed · fee_statement.issued · fee_statement.paid · fee_statement.payment_link_issued · fee_statement.overdue · ticket.opened · ticket.message_created · alert.opened · alert.resolved · standard.version_published · dsr.received.
One of active · degraded · suspended.
Responses
- 200 — OK
- 401 — Codes:
authentication_required. - 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 429 — Codes:
rate_limited.
curl --request DELETE \ --url https://api.werefund.com/v1/webhook-endpoints/{endpoint_id} \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Webhook endpoints
List deliveries
Plannedhttps://api.werefund.com/v1/webhook-endpoints/{endpoint_id}/deliveriesAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Opaque cursor from next_cursor. Keyset pagination; there is no offset.
Page size.
Response fields · 200
One of pending · delivering · delivered · failed · dead.
Responses
- 200 — One page
- 400 — Codes:
cursor_invalid. - 401 — Codes:
authentication_required. - 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/webhook-endpoints/{endpoint_id}/deliveries \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Banners and badge
Banner formats and snippet
The banner kit of one store: the eight formats, the three defaults, whether the badge is served, and the tag to paste. A key bound to one store reads that store; a key that covers every store of the account names one with store. A closed store keeps its kit, with enabled false: its badge shows nothing.
https://api.werefund.com/v1/bannersAuthorization
A secret API key passed with the Bearer scheme: Authorization: Bearer wr_live_… (wr_test_… for test orders).
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
The store's public slug. Required with a key that covers every store of the tenant (store_required); with a key bound to one store it may be left out, and naming another store answers 404.
Response fields · 200
The store handle: store.public_slug, the value of data-store in the banner snippet.
One of lockup · inline · card · strip · badge · product · tile · metrics.
The eight banner formats. numbers is accepted by badge.js as a deprecated alias of metrics.
One of lockup · inline · card · strip · badge · product · tile · metrics.
One of light · dark.
One of s · m · l.
Whether the badge of the store is served. False when the merchant switched the kit off, and when the store is closed; the snippet then shows nothing.
The <script> tag to paste, written by WeRefund with the three defaults: data-store, data-format, data-theme, data-size, async. Its source carries ?v=, a short prefix of the SHA-256 of the published badge.js: it changes with a new script, and never names a release.
Responses
- 200 — OK
- 400 — Codes:
store_required. - 401 — Codes:
authentication_required. - 404 — Codes:
store_not_found. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/banners \ --header "Authorization: Bearer wr_live_…" \ --header "Accept: application/json"
Banners and badge
Badge JSON by state
Cache-Control: no-cache with a weak ETag built on badge_cache_version, W/"<public_slug>-<badge_cache_version>": every display revalidates, and a request whose If-None-Match names the current ETag (weak comparison, a list or * included) answers 304 without a body. Never verified after the certificate left it, whatever an intermediate cache holds: the version moves with every change of state. No stale-if-error, no max-age. Every response of /v1/public carries Access-Control-Allow-Origin: *, the 304 and the 404 included, without credentials: badge.js reads this body from the merchant's site. No cookie is read and no session is opened. A network error or any status other than 200: badge.js renders nothing (fail-closed).
https://api.werefund.com/v1/public/badge/{public_slug}.jsonAuthorization
None — this route is public.
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
The store handle (data-store).
Accepted and ignored: freshness comes from the ETag alone, and every display revalidates.
Response fields · 200
Responses
- 200 — OK
- 304 — Not modified: the
ETagsent inIf-None-Matchstill matches. No body; the sameETag,Cache-Control: no-cacheandAccess-Control-Allow-Origin: *as the200. - 404 — Codes:
badge_not_found-- an unknown store handle, a banner kit the merchant has switched off, or a closed store. The three answer the same body, withCache-Control: no-cache: a cached 404 would hide a kit switched back on. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/public/badge/{public_slug}.json \ --header "Accept: application/json"
{
"state": "verified",
"rating": {
"average": 4.7,
"count": 1284
},
"measures": {
"refund_issued_rate": 0.98,
"refund_delay_median_days": 3.2,
"first_response_median_hours": null
},
"cache_version": 57
}Banners and badge
Badge or banner as SVG
The <img> variant, without script, and the image badge.js places. By state: in verified, badge and product carry the logo, « WeRefund Verified » and the ✓, never a figure; outside verified, they carry the state label (« Reviewing changes », « Verification unavailable ») without ✓. The six score formats answer an empty SVG outside verified, showing nothing rather than an outdated figure, and in verified too while the store has no rating and no measure to show: they never show an invented figure. The drawing carries no script, no style sheet, no link and no external resource. ?theme= and ?size= fall back to their default when absent or unknown. numbers is served as metrics (a deprecated alias, logged). Same cache rule as the JSON: no-cache and a weak ETag, because an <img> keeps its URL; the ETag also tells the format, the theme, the size and the drawing apart. Every response carries Access-Control-Allow-Origin: *, the 304 and the 404 included, without credentials: badge.js loads the image in anonymous CORS mode. No cookie is read and no session is opened.
https://api.werefund.com/v1/public/badge/{public_slug}/{format}.svgAuthorization
None — this route is public.
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
The store handle (data-store).
The eight banner formats. numbers is accepted by badge.js and by the SVG route as a deprecated alias of metrics, and logged.
One of lockup · inline · card · strip · badge · product · tile · metrics.
An absent or unknown value falls back to light.
One of light · dark.
An absent or unknown value falls back to m.
One of s · m · l.
Accepted and ignored: freshness comes from the ETag alone, and every display revalidates.
Responses
- 200 — The SVG
- 304 — Not modified: the
ETagsent inIf-None-Matchstill matches. No body; the sameETag,Cache-Control: no-cacheandAccess-Control-Allow-Origin: *as the200. - 404 — Codes:
badge_not_found-- an unknown format (neither one of the eight nornumbers), an unknown store handle, a banner kit switched off, a closed store. The same body as the JSON's 404, withCache-Control: no-cache. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/public/badge/{public_slug}/{format}.svg \ --header "Accept: application/json"
Banners and badge
Badge impression beacon (off)
Answers 404 while BADGE_TELEMETRY_ENABLED is false, which is the launch state. Sent as text/plain, so no preflight.
https://api.werefund.com/v1/public/badge-impressionsAuthorization
None — this route is public.
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Responses
- 204 — Recorded
- 404 — Codes:
route_not_found-- whileBADGE_TELEMETRY_ENABLEDis false, the same answer as an address that serves no route. The body is not read, nothing is written, nothing of the visitor is logged. - 429 — Codes:
rate_limited.
curl --request POST \ --url https://api.werefund.com/v1/public/badge-impressions \ --header "Accept: application/json"
Banners and badge
The badge script
PlannedStatic, on js.werefund.com. Reads no cookie and no storage; calls api.werefund.com/v1/public/badge/… only. Outside verified it shows the state label without ✓, and shows nothing rather than an outdated figure.
https://js.werefund.com/badge.jsAuthorization
None — this route is public.
Responses
- 200 — The script
curl --request GET \ --url https://js.werefund.com/badge.js \ --header "Accept: application/json"
Public
Service status
https://api.werefund.com/v1/public/statusAuthorization
None — this route is public.
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Response fields · 200
Responses
- 200 — OK
- 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/public/status \ --header "Accept: application/json"
Public
Search stores by name
PlannedA plain list of stores whose name matches — no filter, no sort.
https://api.werefund.com/v1/public/storesAuthorization
None — this route is public.
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Store name.
Opaque cursor from next_cursor. Keyset pagination; there is no offset.
Page size.
Response fields · 200
The store handle: store.public_slug, the value of data-store in the banner snippet.
The only verification state served on any surface. Internal states never leave the server.
One of verified · reviewing_changes · verification_unavailable.
Responses
- 200 — One page
- 400 — Codes:
cursor_invalid. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/public/stores \ --header "Accept: application/json"
Public
Store public profile
Plannedhttps://api.werefund.com/v1/public/stores/{public_slug}Authorization
None — this route is public.
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
The store handle (data-store).
Response fields · 200
The store handle: store.public_slug, the value of data-store in the banner snippet.
Host, lower case, no scheme; null until the store platform is connected.
The address the store gives shoppers.
The only verification state served on any surface. Internal states never leave the server.
One of verified · reviewing_changes · verification_unavailable.
Responses
- 200 — OK
- 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/public/stores/{public_slug} \ --header "Accept: application/json"
Public
Store reviews
Plannedhttps://api.werefund.com/v1/public/stores/{public_slug}/reviewsAuthorization
None — this route is public.
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
The store handle (data-store).
Repeat it to keep several ratings, as the 5 → 1 checkboxes of the profile do: ?rating=5&rating=4.
Opaque cursor from next_cursor. Keyset pagination; there is no offset.
Page size.
Response fields · 200
Public identifier of a review, its share_slug (12 base62 characters).
How a closed return request ended. no_response is set by the server: 30 days after merchant_notified_at while the request awaits the store; once in transit, 30 days after the reception set by the carrier API (UPS, FedEx, DHL, Royal Mail) or after the tracking was submitted (USPS, Others); never while accepted, and never for a parcel read by API that is not delivered. Its public label is Rico's to write.
One of refund_issued · exchange · refused · no_response.
« Alison M. » or « A shopper », set at publication.
Declared by the shopper, set at publication.
« N recorded returns ».
Responses
- 200 — One page
- 400 — Codes:
cursor_invalid. - 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/public/stores/{public_slug}/reviews \ --header "Accept: application/json"
Public
A shared review
Plannedhttps://api.werefund.com/v1/public/reviews/{share_slug}Authorization
None — this route is public.
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Response fields · 200
Public identifier of a review, its share_slug (12 base62 characters).
How a closed return request ended. no_response is set by the server: 30 days after merchant_notified_at while the request awaits the store; once in transit, 30 days after the reception set by the carrier API (UPS, FedEx, DHL, Royal Mail) or after the tracking was submitted (USPS, Others); never while accepted, and never for a parcel read by API that is not delivered. Its public label is Rico's to write.
One of refund_issued · exchange · refused · no_response.
« Alison M. » or « A shopper », set at publication.
Declared by the shopper, set at publication.
« N recorded returns ».
Responses
- 200 — OK
- 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/public/reviews/{share_slug} \ --header "Accept: application/json"
Public
Verify a Policy Record
PlannedThe link the shopper can share (a bank, a dispute) proves the record without showing the text: the store, the dates, the SHA-256, the version number and the signature. Never the captured policy nor its PDF.
https://api.werefund.com/v1/public/verify/{verify_token}Authorization
None — this route is public.
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
The record's verify_token.
Response fields · 200
The store handle: store.public_slug, the value of data-store in the banner snippet.
Exactly what is signed. The deadline and the attachment quality are outside it.
Public identifier of a certificate, WR-<n>.
The store handle: store.public_slug, the value of data-store in the banner snippet.
Public identifier of a policy version, pv_<n>_<version>.
One of delivery.
States that this is what was published at the URL, not what the shopper saw.
Responses
- 200 — OK
- 404 — Not found here. Another merchant's object answers 404, never 403. A path that no route serves answers
404 route_not_found. - 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/public/verify/{verify_token} \ --header "Accept: application/json"
Public
The standard in force
Plannedhttps://api.werefund.com/v1/public/standard/currentAuthorization
None — this route is public.
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Response fields · 200
Responses
- 200 — OK
- 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/public/standard/current \ --header "Accept: application/json"
Public
The option fee grids
Plannedhttps://api.werefund.com/v1/public/fee-scheduleAuthorization
None — this route is public.
Parameters
The API version this request is written for. Absent, the current version (v1). A version still served but deprecated answers with Deprecation and Sunset headers; a retired version answers 410 api_version_retired; any other value 400 api_version_unknown. Distinct from WeRefundVersion, which outbound webhooks carry.
Response fields · 200
Responses
- 200 — The list
- 429 — Codes:
rate_limited.
curl --request GET \ --url https://api.werefund.com/v1/public/fee-schedule \ --header "Accept: application/json"
Webhooks
Outbound webhooks
PlannedWeRefund sends each event to your endpoint as a signed POST, at least once, and retries with backoff. Verify the signature before you trust the body, and use the event id to ignore a repeat.
Headers
t=<unix>,v1=<hex HMAC-SHA256 (endpoint secret, t + "." + raw body)>.
Stable across retries: deduplicate on it.
The API version the payload is written in.
Events · 30
order.recorded
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
order.delivered
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
order.cancelled
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
policy_record.created
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
refund.issued_observed
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
refund.reversed_observed
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
policy.change_detected
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
policy.version_created
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
verification.state_changed
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
return_request.created
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
return_request.accepted
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
return_shipment.declared
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
return_shipment.delivered
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
return_request.closed
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
review.published
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
review.replied
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
rating.updated
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
measures.updated
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
fee.collected
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
fee.reversed
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
fee_statement.issued
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
fee_statement.paid
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
fee_statement.payment_link_issued
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
fee_statement.overdue
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
ticket.opened
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
ticket.message_created
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
alert.opened
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
alert.resolved
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
standard.version_published
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
dsr.received
The envelope of every outbound webhook. Public identifiers only.
= WeRefund-Event-Id, stable across retries.
The store the fact belongs to; null for a fact of the tenant: the four fee_statement.* events, standard.version_published, dsr.received, and an alert opened on no store.
Banners
One script tag renders any of the eight formats and keeps itself current, from the store's public profile.
- data-store — your store handle, the one on your WeRefund profile.
- data-format — lockup · inline · card · strip · badge · product · tile · metrics. The former name
numbersis still accepted formetrics. - data-theme — light or dark. Defaults to light.
- data-size — s · m · l. Defaults to m.
- While verification is unavailable, the banner renders nothing rather than a stale figure.