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.
Overview
Our integration with Rivo 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.
Connect your Rivo account
Sign in to the Subtotal Dashboard and connect your Rivo account to enable the integration. Navigate to Integrations → Rivo → Connect. Click theConnect Rivo button.
Save Integration.
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. |
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. |
Customer identification
The value Subtotal sends in thecustomer_identifier field depends on the Customer identifier type you’ve configured:
| Identifier type | Field on the connection |
|---|---|
email | |
| Customer ID | customer_id |
| Mobile | phone_number |
- Shopify app — the customer’s email is captured automatically from their Shopify profile. For
Customer IDorMobile, you’ll need to pass the value explicitly when launching Subtotal Link. - API integration — include the appropriate field (
email,customer_id, orphone_number) when creating a connection viaPOST /connections. - Subtotal Link query parameter — pass
customer_id(or the appropriate field) as a query parameter when launching Subtotal Link. See Link URLs and Link accounts to your Shopify store.
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.