Signifyd’s Returns API supports every stage of the post-purchase journey — from intent capture to feedback and fraud labeling. Merchants can choose a decisioned or non-decisioned path and flexibly log data depending on their operational setup. The API is built around four endpoints:

Create Post-Sale Requested Action

Use this to log the initiation of a return, refund, exchange, or appeasement request.

This call captures the buyer's intent, allows for Signifyd evaluation (when desired), and anchors all downstream updates and feedback. Merchants can call this endpoint when:

• A buyer initiates a return from a self-service portal
• A support agent logs a refund request via phone/chat/email
• A return is triggered internally (e.g., loyalty appeasement, waiver)

Merchants can choose:

• infoOnly = true: No Signifyd evaluation — request is just logged
• infoOnly = false: Signifyd evaluates the request and returns a decision, used in Instant Refunds or Selective Appeasement flows

Recommended as the first step in most real-time return and refund flows.

Update Post-Sale Action

Use this to report status changes or final actions taken on a post-sale request.

Common updates include:

• Refund issued
• Replacement sent
• Request canceled or declined
• Guarantee cancellation when status is REFUNDED or PARTIAL_SETTLEMENT

UpdatePostSaleRequest helps Signifyd track request outcomes, refund timing (e.g. instant vs post-verification), and alignment with policies.

This call is important to:

• Close the loop on CreatePostSaleRequest
• Trigger guarantee cancellation logic (when applicable)

Can be called multiple times as the request progresses through stages (e.g. OPEN → IN_ANALYSIS → REFUNDED).

Record Post-Sale Action

Use this when the entire return, refund, or appeasement has already been completed — and you’re sending the outcome retrospectively.

This is the right choice for:

• Batch ingestion of historical return/refund data
• In-store returns (BORIS) where online events are logged post-fact
• Use cases where Create and Update were not called in real-time

It supports:

• Guarantee cancellation if the status is REFUNDED or PARTIAL_SETTLEMENT
• Partial refund logic via amount field
• Matching to the original orderId and Signifyd guarantee

RecordPostSaleRequest replaces Create + Update in one step. Do not use in combination with the above two.

Submit Post-Sale Action Feedback

Use this to report the quality of a return once the item is received, inspected, or confirmed.

This feedback trains Signifyd’s models and powers insights dashboards. Use cases include:

• Indicating whether returned items were fraudulent or abusive
• Labeling returns that were fully legitimate
• Flagging package tampering, item switches, or serial return behavior

Merchants specify granular disposition fields per item (e.g., MISSING, DAMAGED, AS_EXPECTED) and can optionally include returnOutcome (e.g., GOOD, FRAUD, ABUSIVE).

This endpoint is essential for merchants participating in Returns Insights, Returns Fraud prevention, or policy-triggered automations.