> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subtotal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Introduction
> Connect Rivo and configure how customers are rewarded.
## Overview
Our integration with [Rivo](https://rivo.io) makes it easy to reward customers for linking accounts and making retail purchases.
Subtotal awards points in Rivo by posting events to Rivo's Custom Action API. Each action you configure in Subtotal maps to a matching Custom Action you've created in Rivo — so Rivo can apply its earning rule and display the reward in the customer's activity feed.
## Get your Rivo API key
Sign in to the Rivo app in your Shopify admin and navigate to *Settings → Developer Toolkit → API Keys*. Copy the REST API key — you'll need it to connect the integration.
Can't find your API key? [Rivo's help article has a walkthrough.](https://help.rivo.io/en/articles/8544831-how-to-get-your-rivo-api-key)
## Connect your Rivo account
Sign in to the Subtotal Dashboard and connect your Rivo account to enable the integration.
Navigate to [*Integrations → Rivo → Connect*](https://dashboard.subtotal.com/integrations/rivo).
Click the `Connect Rivo` button.
Paste your Rivo API key, then click `Save Integration`.
You should now see an `Active` status on the Rivo integration page.
## Configure actions
After connecting, configure the actions Subtotal should send to Rivo. Each action maps a Subtotal event (an account being linked, a purchase being made) to a **Custom Action** you've set up in Rivo. The **Action name** in Subtotal must match the Custom Action name in Rivo exactly — that's how Rivo applies the matching earning rule.
| Setting | Description |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Customer identifier** | The field on the connection used to identify the customer in Rivo: **Email**, **Customer ID**, or **Mobile**. |
| **Actions** | One or more event-to-Custom-Action mappings. Each action specifies the event type, the retailers it applies to, and how points are determined. |
To add an action, click `Add action` and choose an event:
| Field | Description |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Event** | `account.linked` (fired when a customer links a retailer account) or `purchase.created` (fired for each purchase Subtotal collects). |
| **Action name** | Must match the name of a Custom Action you've created in Rivo. Subtotal sends this value in the `custom_action_name` field so Rivo can apply the right earning rule. |
| **Retailers** | Restrict the action to specific retailers, or apply it to all. |
| **Points** *(account.linked)* | Number of points to award when a customer links an account. Subtotal sends this value to Rivo as `points_amount` on every event, so the points configured on your Rivo Custom Action rule are always overridden. |
| **Points per dollar** *(purchase.created)* | Points awarded per dollar of spend on items Subtotal collects from the purchase. Subtotal computes points as `ceil(items_subtotal × points_per_dollar)` — where `items_subtotal` is the sum of `price × quantity` for each collected item — and sends the resulting integer to Rivo. Taxes, shipping, and fees are excluded. |
| **Start date** *(purchase.created)* | Only purchases made on or after this date are rewarded. This controls how much historical purchase data gets sent to Rivo when a customer first links their account. |
See [Rewarding linked accounts](/docs/integrations/rivo/linked-account) and [Rewarding purchases](/docs/integrations/rivo/purchases) for setting up each action end-to-end in Rivo and Subtotal.
## Customer identification
The value Subtotal sends in the `customer_identifier` field depends on the **Customer identifier** type you've configured:
| Identifier type | Field on the connection |
| --------------- | ----------------------- |
| **Email** | `email` |
| **Customer ID** | `customer_id` |
| **Mobile** | `phone_number` |
How this field gets captured depends on your setup:
* **Shopify app** — the customer's email is captured automatically from their Shopify profile. For `Customer ID` or `Mobile`, you'll need to pass the value explicitly when launching Subtotal Link.
* **API integration** — include the appropriate field (`email`, `customer_id`, or `phone_number`) when creating a connection via [`POST /connections`](/docs/api-reference/connections/create).
* **Subtotal Link query parameter** — pass `customer_id` (or the appropriate field) as a query parameter when launching Subtotal Link. See [Link URLs](/docs/subtotal-link/link-urls) and [Link accounts to your Shopify store](/docs/guides/shopify-subtotal-link).
Without the configured identifier field set on the connection, Subtotal won't be able to identify the customer in Rivo and the action will be skipped.