Convercus

Convercus is a SaaS loyalty and coupon platform that helps brands and retailers grow customer frequency, basket value, and repurchase rates through omnichannel loyalty programs and personalized coupon campaigns.

This integration is maintained by Convercus.

About the integration

The Braze and Convercus integration is bidirectional: loyalty data flows into Braze in real time as custom attributes, custom events, and purchases, and Braze Canvases and campaigns can trigger loyalty actions in Convercus through webhooks. Use synced member tier, points balance, purchases, and coupon activity in Segments, Liquid, and Connected Content. From Braze journeys, you can also assign coupons, book, earn, and burn point transactions, and update email subscription preferences in Convercus.

Convercus hosts the integration, so you do not install additional infrastructure. Where most loyalty connectors only push data one way, Convercus closes the loop: react in Braze to a loyalty event, take an action in Convercus, and measure the result back in Braze.

Use cases

1. Tier-up celebration: When a member moves up a loyalty tier in Convercus, trigger a personalized Braze Canvas with a welcome message, a tier-exclusive perk, and the member’s new tier and points balance.
2. Birthday and milestone bonuses: From a Braze journey, book bonus points in Convercus on a member’s birthday or anniversary, then send a celebratory message confirming the new balance.
3. Lapsed-member win-back: For inactive members, have Braze assign a personalized coupon in Convercus through a webhook and deliver it across email, push, and in-app messages.
4. Live points balance in messaging: Use Connected Content to pull a member’s real-time points balance into Braze Liquid, powering cadences such as “you’re X points away from your next reward”.

Prerequisites

Before you start, you need the following:

You need a consistent user identifier between systems: the value used as external_id (or the chosen identifier type) in Braze must match the corresponding member identifier in Convercus. Otherwise, events do not attribute to the correct profile.

Integration

Step 1: Configure Braze in Convercus Selfservice

In Convercus Selfservice (the customer-facing admin UI—open it using the URL your Convercus account manager provides), open the program you want to connect to Braze and use the Braze integration card to:

1. Configure the Braze connection by completing the integration form:

   Field	Description
   apiKey	Your Braze REST API key (with the users.track permission).
   apiEndpoint	Your Braze REST endpoint, for example https://rest.iad-01.braze.com.
   Identifier type	Either external_id or user_alias. Determines how Convercus members are matched to Braze user profiles.
   defaultOptins	Multi-select of the program’s opt-in channels (from membershipOptins). Used as the default for the email subscription webhook when the request omits optins. The Braze config is treated as incomplete until at least one is selected.

2. Create an API key for inbound calls. Create a per-program X-Convercus-Key credential. The raw key is shown once at creation, prefixed cvc_ (format: cvc_<base64url>). Store it in Braze when you configure the webhook campaigns and Connected Content blocks in Step 2. Keys can be revoked at any time from the same card; revocation takes effect immediately.

After you save the Braze connection, Convercus immediately starts streaming loyalty events for that program to Braze. No additional infrastructure setup is required.

note

Each Convercus program is configured independently. A single Convercus tenant can connect different programs to different Braze workspaces, each with its own API key.

Step 2: Configure webhooks in Braze

To trigger Convercus actions from a Canvas or campaign, create Braze webhook actions that call the Convercus integration service. All requests must include the following headers:

• X-Convercus-Key: cvc_… - the API key generated in Step 1.
• Content-Type: application/json

All endpoints live under the base URL <SERVICE_HOST>/v1/programs/{programId}. Replace <SERVICE_HOST> with the host provided by your Convercus account manager and {programId} with your Convercus program ID.

Example — assign a coupon to a member:

1
2
3
4
5
6
7
8
POST <SERVICE_HOST>/v1/programs/{programId}/campaigns/{couponId}/assign
X-Convercus-Key: cvc_…
Content-Type: application/json

{
  "account_id": "{{custom_attribute.${convercus_account_id}}}",
  "braze_campaign_id": "{{campaign.${api_id}}}"
}

The other actions follow the same pattern, changing only the endpoint and the body. For example, a points booking posts to /members/{accountId}/bookings with booking_type (EARNBOOKING or BURNBOOKING), booking_type_code, points, and reason; the email subscription webhook posts to /subscriptions/email with account_id and status (allowed or declined).

Error responses and retries

warning

5xx responses are not safe to retry without confirming success—these operations are not idempotent, and retries may double-assign coupons or double-credit point bookings. Disable Braze auto-retry on 5xx for these webhooks, or configure a very low maximum retry count.

Step 3: Verify data in Braze

1. Trigger a loyalty event in Convercus—for example, a status level change, a points transaction, or a coupon redemption.
2. Open the matching user in Braze and confirm that the expected custom attribute, custom event, or purchase appears on the profile. Users are matched by external_id (or the identifier type chosen in Step 1).
3. To verify the opposite direction, run a Braze test send that calls one of the webhooks from Step 2 and confirm the action in Convercus (coupon assigned, points booked, or subscription updated).

Use Convercus with Braze

Step 1: Personalize messages with synced loyalty data

After the integration is live, Convercus events arrive on each user profile in Braze through the /users/track endpoint and can be used like any other native data:

1. Use loyalty custom attributes (for example, convercus_status_level, convercus_balance) in Segments to target tier holders, high-balance members, or recently downgraded users.
2. Use custom events (for example, convercus_status_level_changed, coupon and membership events) as trigger steps in Canvas or as filters in re-engagement campaigns.
3. Reference any of these fields in Liquid for in-message personalization (subject lines, body copy, push titles).
4. Use purchase events streamed from Convercus to drive product-aware journeys (replenishment, category upsell, post-purchase review requests).

Custom attributes

note

Within a Braze workspace, members are uniquely identified by convercus_account_id. convercus_user_id identifies the underlying person across multiple Convercus programs and is provided for cross-program analytics; for segmentation within Braze, use convercus_account_id.

email_subscribe mapping

Custom events

Purchases

Convercus transactions of type EARNTRANSACTION (points earned from customer spend) are reported to Braze as purchases and counted in Braze revenue analytics, RFM segmentation, and predictive features—using the transaction ID as the product identifier and the transaction amount and currency as price and currency.

Transactions of type PAYWITHPOINTSTRANSACTION (points burn) are not reported as purchases—they flow as the convercus_account_transaction custom event so they remain available for segmentation. Reversals and cancellations of earn transactions are reported as negative-price purchases, keeping Braze revenue aligned with Convercus.

Step 2: Fetch live loyalty data with Connected Content

For values that must be fresh at send time—current points balance, active coupons, latest tier—call Convercus from Braze using Connected Content instead of relying on the most recently synced attribute. Both endpoints sit under the same base URL as the webhooks and require the X-Convercus-Key header.

Connected Content endpoints always return HTTP 200 on expected failures so Liquid templates can branch on the error field:

Example — render a member’s loyalty status (tier, points, and active offers):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{% connected_content
  https://<SERVICE_HOST>/v1/programs/{programId}/members/{{custom_attribute.${convercus_account_id}}}/profile
  :headers { "X-Convercus-Key": "cvc_…" }
  :content_type application/json
  :cache_max_age 300
  :retry
  :save member
%}

{% connected_content
  https://<SERVICE_HOST>/v1/programs/{programId}/members/{{custom_attribute.${convercus_account_id}}}/coupons?lang=en
  :headers { "X-Convercus-Key": "cvc_…" }
  :content_type application/json
  :cache_max_age 0
  :retry
  :save coupon_data
%}

{% unless member.error %}
  <h2>Your Loyalty Status</h2>
  <p>Hi {{member.first_name}}, you're a <strong>{{member.tier_name}}</strong> member.</p>
  <p>Points balance: <strong>{{member.points_balance}}</strong></p>

  {% if coupon_data.coupons.size > 0 %}
    <h3>Your Active Offers</h3>
    {% for coupon in coupon_data.coupons %}
      <p><strong>{{coupon.title}}</strong> — valid until {{coupon.valid_to}}</p>
    {% endfor %}
  {% endif %}
{% endunless %}

Always wrap Connected Content in conditionals (check member.error and empty coupons) so a temporary lookup failure never ships a broken message. Cache the profile (cache_max_age 300) but not coupons (cache_max_age 0), since coupon status can change between sends.

Considerations

• Latency: Convercus-to-Braze events propagate through Kafka and reach Braze in seconds under normal load.
• Braze rate limits: The integration retries automatically on 429 responses, honoring Braze’s x-ratelimit-retry-after header with exponential backoff.
• Connected Content caching: Braze caches Connected Content responses for several minutes by default. For values that must be exact at send time (such as points balance), shorten or bypass the cache window in the Connected Content call.
• One configuration per program: Each loyalty program maps to a single Braze workspace. To connect a second workspace, configure it on a separate program.
• Observability: Per-program API call statistics and error history (both directions) are retained for 90 days and available from the Braze integration card in Selfservice.

Troubleshooting

• Events do not appear in Braze: Verify that the value used as the identifier (selected in Step 1) matches the user’s external_id (or chosen identifier type) in Braze. Mismatched identifiers cause events to be attributed to the wrong profile or dropped.
• Webhook returns 401: The X-Convercus-Key header is missing or the cvc_… API key has been revoked. Regenerate the key in Selfservice and update the webhook action in Braze.
• Webhook returns 400: The request is missing Content-Type: application/json, or the payload does not match the documented schema. For the email subscription webhook, a 400 also means the requested opt-ins are unknown to the program or none are configured.
• Deeper debugging: Review the per-program API call statistics and error history on the Braze integration card in Selfservice, or contact your Convercus representative.