Pinch concepts

Most of Pinch's documentation refers to the same handful of objects and ideas. This page defines them once, so the rest of the docs can be brief.

The post-purchase pipeline

Every order, return, and disposition event flows through the same pipeline:

1. 1
   Event arrives

   A signup, login, order, return, disposition, or dispute is sent to Pinch — either through the Shopify app, an RMS integration, or your own server calling the REST API.

2. 2
   Variables are computed

   Pinch updates pre-computed signals about the customer (e.g. Num returns per email in last 1 year, Return rate by value by email).

3. 3
   The relevant workflow runs

   The Orders workflow or Returns workflow evaluates its conditions against the event and the customer's variables.

4. 4
   A decision is returned

   The workflow emits one of ALLOW, DENY, or REVIEW, plus an abuse score (0–100), a suspected abuse type, and the reasons that drove the decision.

5. 5
   The decision is enforced

   Pinch writes customer tags back to Shopify, sends an email through a template, triggers a playbook, or returns the decision to your service via API response or webhook.

Core objects

Decisions

A Decision is one of three outcomes: ALLOW, DENY, or REVIEW. Decisions are also reusable rule blocks — you author a Decision once (e.g. "Block if more than 5 returns per email in 90 days") and reference it from multiple workflows.

A Decision response also includes:

• Sub Decision — a configurable category (e.g. Suspect Abuse, High Customer Value)
• Decision Reason — the model explainer and the workflow steps that triggered
• Abuse Score — 0–100, where higher means more abuse risk

See Decisions.

Workflows

A Workflow is a visual decision tree that runs on either Orders or Returns. Workflows are composed of conditions, reusable Decisions, and email templates. Branches are evaluated top-down; the first matching branch wins. There is always a default branch (typically a Default Approve).

See Workflows.

Variables

A Variable is a pre-computed signal about a customer, used inside Workflow conditions. Pinch ships ~90 standard variables and you can author your own.

Common variables:

• Num returns per email in last 1 year
• Num returns per phone in last 1 year
• Num returns per address in last 1 year
• Return Due To Size Ratio By Email
• Customer Value Per Email
• Return Rate by value by Email

Variable types include REALTIME AGGREGATE (recomputed on every event), behavioral (derived from order/return patterns), and identity-linked (rolled up across all identifiers tied to one customer).

See Variables.

Playbooks

A Playbook is an automated action triggered when a customer enters a specific segment. The most common action is sending a Dixa or Gorgias email; other actions include order tagging, Shopify customer notes, and webhooks. Playbooks fire in addition to workflow decisions, not instead of them.

See Playbooks.

Pinch Assessment score

The Pinch Assessment is a 0–100 score on every customer that summarizes their abuse risk. It's surfaced on the customer profile in the dashboard, returned in every Decision API response, and refreshed continuously as new events arrive.

Each Assessment includes:

• The numeric score (0–100)
• A Suspected Abuse Type — Wardrobing, Empty Box, Copycat, Missing Item, or N/A
• Key Risk Indicators — the top variables that contributed to this customer's score
• The Triggered Workflow that last ran on this customer

See Customers.

Customer segments

Every customer falls into one of four segments, based on their score and behavior:

Segment	Typical share	Meaning
VIP	~2%	High lifetime value, low abuse signal — give them frictionless returns
Others	~97%	Standard customers, default policies apply
Suspect	under 1%	Elevated abuse signal, typically routed to Review
Egregious	under 0.1%	High-confidence abuse, typically denied

Thresholds and policies are configurable.

Pinch Identity Number

Real customers aren't a single email. The same person buys under different emails, ships to the same address with a slightly different name, uses three phone numbers, and accesses your site from two devices. The Pinch Identity Number is the stable ID Pinch assigns that links all of those identifiers together — so a workflow can ask "has this person abused us before?" rather than "has this email abused us before?"

The Identity Number is exposed on every API response and on the customer profile in the dashboard. The Customer Graph view shows the linked identifiers behind one Identity Number.

See Pinch Identity Number.

Suspected abuse types

Pinch detects and labels these abuse patterns:

Type	What it looks like
Wardrobing	Customer wears or uses an item briefly, then returns it as new
Empty Box	Customer claims package was empty on arrival, requests refund
Copycat	Multiple accounts that look the same — same address, similar emails, same device
Missing Item	Customer claims one or more items weren't in the package
Return Tag	Return shipped without the return label that was issued
Switch fraud	Customer returns a damaged or different item than the one purchased
Bricking	Customer returns a working item stripped of valuable components
Receipt fraud	Forged receipts or cross-store return arbitrage

See Returns intelligence overview for how these map to workflow conditions.

Dashboard surface

The Pinch dashboard at app.pinch.ai exposes every concept above:

Section	Purpose
Analytics	Abuse impact, return rate, segments, geographic distribution, trends, custom widgets
Workflows	Build and edit Orders and Returns workflows (Decisions are authored inside the workflow editor)
Review	Manual queue for orders and returns flagged as Review
Playbooks	Segment-triggered actions
Customers	Customer list and profile with Pinch Assessment
Integrations	Returns system, warehouse, customer support, custom
Variables	Library of pre-computed signals

Environments

Pinch runs in two environments:

• Production — https://api.pinch.ai, app.pinch.ai
• Sandbox — https://qa.pinch.ai, qa.pinch.ai/dashboard

Sandbox is identical to production except it uses isolated data and test API keys. See Environments.

Next

🏪Shopify Quickstart

Install the Pinch app and start scoring orders in 30 minutes.

⌨️API Quickstart

Send your first Order and Return via REST.