Before you start
Ticks are kept in this browser only.
Follow the path that matches your account. Provider screenshots come from the linked official documentation and may show a different theme or older navigation. Configuration examples are labelled separately.
Permissions to choose
Use these exact permission names. Conditional permissions are needed only for the features described.
| Permission / scope | When needed | What it allows |
|---|---|---|
Bearer token for GET endpoints | Required | Authorises health, bounded order listing and order-detail reads.Your system issues and enforces this permission. There is no universal OAuth scope string. |
Refund, fulfilment and dispute reads | Conditional | Supply these optional resources when the source system has the corresponding facts.Unavailable resources remain unknown. An actual empty refund array means no refunds. |
Routing identity resource | Conditional | The contract defines selected identity enrichment separately.Evidence-testing restrictions continue to block external delivery and release. |
Separate inbound signing secret | Optional | Authenticates change notifications that queue a read of the source system.Use a different secret from the API bearer token. |
Source-system write access | Not requested | Revient's Custom API connector performs GET reads. |
The credential is issued by your organisation. Ask the developer to enforce read-only access at the source; a token label alone does not restrict permissions.
Connect an endpoint your developer has prepared
Ask your developer for the contract base URL and its dedicated read token. Keep credentials in the connection form rather than chat or screenshots.
Confirm the endpoint is ready
Your organisation's source-system developer
- Share the downloadable API contract with the developer responsible for your order data.
- Obtain the final HTTPS base URL and a dedicated read-only bearer token. Confirm which optional evidence resources the system supplies.
You should seeThe developer confirms that the endpoint implements oweflow-read-v1 and provides a known order to check.Enter the URL and token
Revient → Integrations → Custom API → Connect Custom API
- Paste the HTTPS base URL and Bearer token into their matching fields.
- Use the contract root, without /health or /orders. Select Connect Custom API.
You should seeThe connection is saved if its health read succeeds, or Revient shows the connection error. A health response alone does not verify order or dispute data.Sync and compare the source facts
Revient → Custom API → Manage Custom API
- Select Check connection, then Sync now for the correct endpoint.
- Open View draft intake and import history and follow the job to completion.
- Compare the known order's ID, date, currency and total against the source. Also inspect refund, fulfilment and dispute facts where available.
You should seeImported facts match the source system. Only confirmed LOST disputes enter recovery intake; incomplete confirmed losses show Needs information. New non-lost and order-only records are skipped.Manage access and optional notifications
Revient → Custom API → selected connection
- Use Pause to stop reads temporarily or Reconnect to replace the token for the same endpoint.
- For change notifications, open Set up webhooks for this store. Enter the separate Signing secret and select Set up inbound webhooks. Give the developer the displayed Destination and the signing contract.
- Use Disconnect when the connection is no longer needed. Revoke the dedicated token in your source system as well.
You should seeThe selected connection has the intended access state. Previously selected testing evidence remains until you explicitly remove or replace it.
Developer: implement and verify the contract
The downloadable contract is the complete reference. The steps below highlight the authentication, data and pagination requirements that cause most setup failures.
Expose a bounded authenticated HTTPS service
Your source system → public HTTPS service
- Implement the contract under a stable base URL with a valid certificate and public DNS addresses. Use port 443; do not include URL credentials, query parameters or a fragment.
- Validate the merchant-issued bearer token and X-Oweflow-Contract: oweflow-read-v1 on reads. Issue a credential with read-only source permissions.
- Return uncompressed JSON without redirects. Keep each response at or below 2 MiB and respond within Revient's 15-second request deadline.
You should seeAn authenticated GET /health returns HTTP 200 with a JSON object, optionally containing a name.Implement the bounded order index
GET /orders
- Accept limit=25, updatedAfter, updatedBefore and an optional cursor. Filter by each order's actual modification timestamp, including the boundary timestamps.
- Return at most 25 unique order IDs and an opaque nextCursor string or null. Keep a stable order such as updatedAt plus id across the same window.
- Return IDs as strings and keep them at most 500 characters. Cursor strings are limited to 2,048 characters; do not return a next-page URL.
You should seeThe first page and each cursor page cover the same time window without repeating a cursor or omitting source changes.Return source dates and currency-aware money
GET /orders/{id}
- Return the order shape from the contract, keeping its original ID, number, timestamps and currency.
- For fields ending Minor, send non-negative integer minor units. For example, GBP 125.00 is totalMinor: 12500; this is different from the CSV import's decimal major-unit format.
- Use ISO timestamps with an explicit timezone. Return null or omit unavailable facts instead of inventing zero totals, dates, customer details or a dispute.
You should seeA known source order can be matched exactly after normalisation, including its currency and original timestamps.Expose genuine optional evidence
Refund, fulfilment and dispute endpoints
- Implement /orders/{id}/refunds and /orders/{id}/fulfilments where those records exist. An empty refunds array confirms none; an unavailable resource leaves the total unknown.
- If your system holds disputes, provide /disputes?status=LOST with at most 1,000 records and unique original dispute IDs. Use OPEN, WON or LOST only when established by the source.
- Update an affected order's modification timestamp when its dispute changes, so the order appears in the next incremental window. A shipment or tracking number does not by itself establish delivery.
You should seeEvidence has the correct source meaning. Refunded or cancelled orders do not automatically become disputes.Optionally send signed change notifications
Your service → the selected Revient store's Destination
- Use the separate Signing secret saved in that store's Inbound webhooks screen. POST a small JSON notification with a unique eventId, type and orderId to the displayed Destination.
- Set X-Oweflow-Timestamp to Unix seconds and X-Oweflow-Signature to the lowercase hex HMAC-SHA256 of timestamp + '.' + the exact raw body, using that secret.
- Keep the body within 256 KiB and its timestamp within five minutes of receipt. Preserve the exact signed bytes.
You should seeA valid notification receives HTTP 202 with accepted: true and queues an authorised source read. The posted notification is not treated as order evidence.Verify failure handling as well as a successful read
Your test endpoint and Revient → Manage Custom API
- Test an order with a known total, a refund, an optional-resource absence and a genuine dispute if available. Compare each imported source fact in Revient.
- Verify invalid credentials return 401 or 403, absent optional resources return 404, and throttling/transient failures use 429 or 5xx. Required-read failures must not look like empty success.
- Verify stable pagination, retries, pause and reconnect against your endpoint. Current retries use exponential backoff with five attempts by default and do not interpret Retry-After.
You should seeThe endpoint's behaviour and source facts have been verified with this Revient connection. A health response or successful example request alone is not full acceptance.
Review the collected evidence
Check the source facts and processing result after completing the provider-specific connection steps.
Check the case and automatic evidence results
Revient → Integrations → Intake, then Cases → Evidence
- Compare the contract's customer, billing/shipping, transaction and dispute fields, including explicit unknowns. Provide stable order and separate dispute identities.
- Shopify intake accepts only CHARGEBACK disputes with final status LOST and a verified remaining disputed balance. Inquiries, won and open outcomes are excluded before customer enrichment, tracking, scoring and AI.
- Confirmed lost chargebacks with missing facts appear in Cases as Needs information. Missing facts remain unknown until supported by evidence.
- Historical non-qualifying records remain in internal audit history, outside merchant intake and active Cases.
- Cases combines retained Test and ordinary records. A small Test badge identifies records that cannot be routed, sold or counted in live financial totals. AI still requires its approved configuration and valid permissions.
- For each outbound, replacement or return parcel, check the tracking number, event dates and item coverage. Registration requires a confirmed lost dispute and verified notification-disabled settings. Delivery photos and signatures are separate private assets; unavailable assets are labelled, and a recipient postcode does not prove the delivery address.
- Use the row menu for one case. Select at least two checkboxes to show bulk actions. Refresh evidence requests current connected-source data and then checks it; Recheck stored evidence uses the facts already retained. Follow each row's progress and refusal reason.
- Archive retains history and may be blocked by active obligations. Use the Archived filter to restore a case. Reimporting its source does not restore it.
You should seeYou can identify the current evidence, unknown fields, processing state and next merchant action without losing historical assessments.
Match these fields in Revient
Enter your own account’s values. Example values are for orientation; do not paste them as credentials.
| Revient field | Where to find it | Example / guidance |
|---|---|---|
| HTTPS base URL | Your developer's deployed contract root. Revient appends /health, /orders and the other contract paths. | https://api.example.com/revient |
| Bearer tokenKeep private | A dedicated credential issued for Revient by your source system. | Paste the complete read-only token |
| Signing secret (optional)Keep private | A separately generated random secret shared with the developer for inbound notifications. | 32-256 non-whitespace characters; not the API token |
If something goes wrong
Base URL rejected
Use a public HTTPS contract root on port 443 with a valid certificate. Remove query parameters, fragments and credentials from the URL. Private DNS/IP destinations and redirects are not supported.
Health succeeds, sync fails
Check the required /orders index and /orders/{id} response shapes and permissions. The health probe does not validate those endpoints.
Amounts are 100 times too large or small
Check the currency's minor-unit scale. API totalMinor and amountMinor are integer minor units; CSV amounts are decimal major units. Do not apply one format to the other.
Dispute changes are not imported
Make the affected order eligible for the current modification-time window when its dispute facts change. The optional dispute list is bounded and only matches orders in the current window.
Webhook signature is rejected
Use the selected store's separate secret, a fresh timestamp and the exact body bytes. Sign timestamp + '.' + raw body before sending; do not reformat the JSON afterwards.
Common questions
Which evidence fields should the endpoint return?
Lost dispute, order total and currency, payment authorisation when you have it, refunds, returns, and tracking numbers. Leave a field out when you do not have it. Revient does not invent the missing fact, and only a confirmed lost dispute becomes a case.
Can I paste a URL that returns any JSON?
No. Your developer must implement the versioned order, authentication and pagination contract. A successful health request is only the first check.
Is an API token the same as the webhook signing secret?
No. The bearer token authorises Revient's reads from your system. A separate signing secret authenticates notifications sent to Revient.
Can CSV imports use the same orders as this API?
Yes. Use the same provider, original store identity and source order IDs so Revient can recognise the records. Keep distinct original dispute IDs for separate legitimate disputes against one order.
What is the difference between Refresh evidence and Recheck stored evidence?
Refresh evidence queues new reads from available connected sources and already selected mailbox messages, then tracking and reassessment. Recheck stored evidence reassesses the retained facts without claiming a new provider read. Existing findings stay visible until the work finishes; unavailable sources and partial refusals are reported for each case.
Which disputes receive recovery scoring?
Shopify intake accepts only CHARGEBACK disputes with final status LOST and a verified remaining disputed balance. Inquiries, won and open outcomes are excluded before customer enrichment, tracking, scoring and AI. Historical non-qualifying records remain in internal audit history, outside merchant intake and active Cases. An order or tracking number alone does not establish a lost dispute. Supply the actual confirmed loss and preserve its original order and dispute identities.
Will testing send messages or release a case?
Evidence-testing mode blocks customer, agency and buyer delivery. Importing records or reviewing an assessment does not release a case.
What happens when I disconnect?
New reads stop and the Revient connection is disabled. Evidence already retained remains subject to the workspace retention and removal controls. Revoke the application or key in the provider account as well if you want to remove its access there.
Source documentation
Use these provider pages if a menu name has moved or your plan shows different options.