> For the complete documentation index, see [llms.txt](https://devs.snowdropsolutions.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://devs.snowdropsolutions.com/advanced-use-cases/subscription-detection.md).

# Subscription Detection

MRS Subscription Detection is an add-on module for MRS. When enabled, the MRS API response includes a <mark style="background-color:$info;">subscription</mark> object for matched merchants, indicating whether a transaction is a subscription payment and providing a confident score.

It uses the same MRS call, with no separete integration. Existing response fields are unchanged.

**Availability**: enabled per customer. Contact your Snowdrop account manager.

### Request fields

In addition to the merchant name and country already sent to MRS, include the following fields with each transaction to enable accurate scoring:

<table><thead><tr><th width="186.47808837890625">Field</th><th width="189.158447265625">Type</th><th width="90.9351806640625">Required</th><th>Description</th></tr></thead><tbody><tr><td><mark style="background-color:$info;">amount</mark></td><td>number (numeric string accepted, e.g. "<mark style="background-color:$info;">5.99</mark>")</td><td><strong>Yes</strong></td><td>Transaction amount.</td></tr><tr><td><mark style="background-color:$info;">currency</mark></td><td>string, ISO 4217 (e.g. <mark style="background-color:$info;">EUR</mark>)</td><td><strong>Yes</strong></td><td>Transaction currency.</td></tr><tr><td><mark style="background-color:$info;">timestamp</mark></td><td>string, ISO 8601 (e.g. <mark style="background-color:$info;">2026-10-20T14:32:00Z</mark>)</td><td>No</td><td>Transaction date and time. Use for batch requests. Defaults to the time MRS receives the request.</td></tr><tr><td><mark style="background-color:$info;">credit_debit_indicator</mark></td><td>string: <mark style="background-color:$info;">debit</mark> or <mark style="background-color:$info;">credit</mark></td><td>No</td><td>Only debits are evaluated. Credits (e.g. refunds) return <mark style="background-color:$info;">matched: false</mark>. Defaults to <mark style="background-color:$info;">debit</mark>.</td></tr></tbody></table>

### Response structure

```json
"subscription": {
  "matched": true,
  "score": 0.7
}
```

<table><thead><tr><th width="190.93603515625">Field</th><th width="151.7681884765625">Type</th><th>Description</th></tr></thead><tbody><tr><td><mark style="background-color:$info;">subscription</mark></td><td>object</td><td>Returned when MRS can evaluate the merchant.</td></tr><tr><td><mark style="background-color:$info;">subscription.matched</mark></td><td>boolean</td><td><mark style="background-color:$info;">true</mark> when <mark style="background-color:$info;">score</mark> is ≥ 0.7 (recommended threshold); <mark style="background-color:$info;">false</mark> otherwise</td></tr><tr><td><mark style="background-color:$info;">subscription.score</mark></td><td>number (0–1)</td><td>Confidence that the transaction is a subscription. 1 = certain.</td></tr></tbody></table>

You can use <mark style="background-color:$info;">matched</mark> for the recommended threshold or evaluate the <mark style="background-color:$info;">score</mark> directly to set stricter or lower thresholds:

#### Confidence levels

<table><thead><tr><th width="129.7027587890625">Confidence</th><th width="162.839111328125">Score</th></tr></thead><tbody><tr><td>Strong</td><td>≥ 0.8</td></tr><tr><td>Probable</td><td>≥ 0.5 and &#x3C; 0.8</td></tr><tr><td>Possible</td><td>≥ 0.25 and &#x3C; 0.5</td></tr><tr><td>Weak</td><td>&#x3C; 0.25</td></tr></tbody></table>

### How detection works

Each merchant has a subscription profile:

* **Always**: subscription-only brands (e.g. Netflix). Returns <mark style="background-color:$info;">matched: true</mark>, <mark style="background-color:$info;">score: 1.</mark>
* **Never**: brands that do not sell subscriptions (e.g. IKEA). Returns <mark style="background-color:$info;">matched: false</mark>.
* **Conditional**: brands that sell both (e.g. Amazon). MRS looks for subscription terms in the merchant name and compares the amount with the brand's subscription prices in the transaction currency. A subscription term in the name is required for a match, and a matching price raises the confidence.

### Examples

* Always-subscription merchant:

```json
"subscription": { "matched": true, "score": 1 }
```

* Conditional merchant (subscription term found, amount does not match a known price):

```json
"subscription": { "matched": true, "score": 0.7 }
```

* Never-subscription merchant:

```json
"subscription": { "matched": false }
```

* No subscription profile / module disabled: the <mark style="background-color:$info;">subscription</mark> object is omitted entirely.

### Notes

* Single transaction: each transaction is evaluated on its own. MRS does not track payment history, detect recurrence over time, or predict upcoming payment dates.
* Currency handling: amounts are compared in the transaction currency only, with no currency conversion performed. Always send the currency alongside the amount.
