# API Authentication
Source: https://docs.withbenji.com/api-reference/authentication
Authenticating your API requests with the Benji Platform APIs
All API endpoints are authenticated using API keys via the `x-api-key` header. There are 2 types of API keys supported:
* **User-based access tokens**, to initiate user-based activities such as earn, redeem and get status actions. These tokens are returned as part of the access/token/exchange API flow following the **Benji Connect SDK** `onSuccess` callback.
* **Partner API keys**, which you can generate through the dashboard in your developer settings page on Pilot, for all non-user-based interactions like retrieving campaign and partner information.
Note that user tokens are short-lived and must be refreshed using the access/token/refresh API endpoint before they expire. User tokens are typically valid for 90 days. If a token has expired, you will get a 401 error from the relevant API endpoint. You can refresh the token using the access/token/refresh API endpoint.
In APIs that support user\_id or user\_external\_id, you can either use the Partner API key and explicitly specify the user\_id, or use the user-based access token and omit these parameters since they are distinguished through the access token.
Partner API key or User access token
# Get Partnership
Source: https://docs.withbenji.com/api-reference/endpoint/partnerships/get
GET https://api-staging.withbenji.com/partnerships/{id}
Get a single partnership by ID
The `x-api-key` header value to be used on this API is your **partner API key**, which can be generated through the dashboard.
Unique identifier of the partnership to retrieve (UUID)
### Response
The partnership object containing all partnership details including its configuration, associated campaigns, and performance metrics.
The UUID identifier of the partnership. This is an alternative identifier that can be used in API operations.
The name of the partnership that is displayed to users and administrators. Identifies the business relationship between a merchant and partner.
A detailed description of the partnership explaining its purpose, benefits, and terms. May be null if no description is provided.
The URL to the partnership logo or image that is displayed in marketing materials and the user interface. May be null if no image is provided.
The unique identifier of the merchant in this partnership. Merchants are businesses where users can earn or redeem rewards.
The unique identifier of the related partner in this partnership. May be null if no related partner is specified.
The unique identifier of the partner in this partnership. Partners are loyalty program providers who offer rewards to users.
Indicates whether this partnership is currently active and available to users. Values: 1=active, 0=inactive. Inactive partnerships do not generate rewards.
Indicates whether this partnership has been marked as deleted. Values: 1=deleted, 0=not deleted. Deleted partnerships are not shown in standard API responses.
The unique identifier of the user who created or owns this partnership. Used for attribution and permission management.
The total amount of rewards that users have earned through this partnership so far, in the smallest currency unit (e.g., cents). May be null if no rewards have been earned yet.
The total amount of rewards that users have redeemed through this partnership so far, in the smallest currency unit (e.g., cents). May be null if no rewards have been redeemed yet.
The total number of transactions that have occurred within this partnership. Used for analytics and reporting. May be null if no transactions have occurred yet.
Indicates whether this partnership is for demonstration purposes only. Values: 1=demo, 0=real. Demo partnerships are not included in production reports.
The date and time when this partnership was created, in ISO 8601 format. Used for auditing and sorting.
The list of campaigns associated with this partnership. Each campaign defines specific reward structures and eligibility criteria. May be null if no campaigns exist for this partnership yet.
```json 200 theme={null}
{
"code": "ok",
"data": {
"partnership": {
"uuid_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Test Partnership",
"description": "A partnership between merchant and loyalty partner",
"img": "https://example.com/partnership-logo.png",
"merchant_id": 1,
"related_partner_id": null,
"partner_id": 3,
"is_active": 1,
"is_deleted": 0,
"owner_id": 5,
"total_rewards_earned": 15000,
"total_rewards_redeemed": 3200,
"num_of_transactions": 142,
"is_demo": 0,
"created_date": "2024-11-20T00:30:57.256493+00:00",
"campaigns": null
}
}
}
```
```json 400 theme={null}
{
"error": "invalid_token",
"message": "Invalid token"
}
```
```json 401 theme={null}
{
"error": "unauthorized_request",
"message": "Token is not authorized to make this request"
}
```
```json 404 theme={null}
{
"error": "partnership_does_not_exist",
"message": "The partnership does not exist"
}
```
This endpoint retrieves detailed information about a specific partnership, including all associated campaigns and performance metrics.
# Get Reward Transaction
Source: https://docs.withbenji.com/api-reference/endpoint/transactions/get
GET https://api-staging.withbenji.com/transactions/{id}
Endpoint to retrieve information regarding a reward transaction
The `x-api-key` header value to be used on this API is your **partner API key**, which can be generated through the dashboard.
Unique identifier of the reward transaction to retrieve (UUID)
### Return values
A reward\_transaction object property
Benji Platform reward transaction identifier
The ID of the partner associated with this transaction in the Benji Platform
The UUID of the partnership associated with this transaction in the Benji Platform
The ID of the campaign triggered for this transaction in the Benji Platform
The UUID of the user associated with the transaction in the Benji Platform
The UUID of the trigger event associated with the transaction in the Benji Platform
The ID of the trigger event associated with the transaction in the Benji Platform
The ID of the merchant partner associated with this campaign in the Benji Platform
The total dollar amount of the transaction
The total amount of rewards earned or redeemed on this transaction
The external reference of the order on the merchant partner system
Integer representing an enum of one of the following transaction type values:
* **EARN (1)** : Indicating an earn transaction type
* **REDEEM (2)** : Indicating a redeem transaction type
Integer representing an enum of one of the following transaction status values:
* **INITIATED (1)** : Transaction has been initiated
* **PENDING (2)** : Transaction is pending and has not been confirmed by the partner yet
* **COMPLETED (3)** : Transaction has been completed successfully
* **ERROR (4)** : An error occurred during processing
* **REVERSED (5)** : Transaction was reversed
* **FAILED (6)** : Transaction was rejected by the partner
* **CANCELLED (7)** : Transaction was cancelled
The transaction date
```json 200 theme={null}
{
"code": "ok",
"data": {
"reward_transaction": {
"campaign_id": "675976-khkgyt7-9876-khfiy",
"created_date": "2025-08-18T20:45:01.186277+00:00",
"external_id": null,
"external_order_id": null,
"external_partner_transaction_id": null,
"id": 5924,
"merchant_id": 41,
"partner_id": 5,
"partnership_uuid": "partnership-uuid",
"trigger_event_uuid_id": "trigger-event-uuid",
"trigger_event_id": 12345,
"reward_amount": 600,
"transaction_amount": 0.0,
"transaction_status": 4,
"transaction_type": 1,
"user_uuid": "user-uuid"
}
}
}
```
```json 400 theme={null}
{
"code": "invalid_token",
"message": "Invalid token"
}
```
```json 401 theme={null}
{
"code": "unauthorized_request",
"message": "Token is not authorized to make this request"
}
```
```json 404 theme={null}
{
"code": "transaction_does_not_exist",
"message": "The transaction does not exist"
}
```
Note that you will only receive data that you as a loyalty partner or merchant partner are allowed to see based on the permissions in the access token you provide to the API.
# Send Trigger Event
Source: https://docs.withbenji.com/api-reference/endpoint/triggers/send
POST https://api-staging.withbenji.com/partnerships/{partnership_id}/triggers
Process a trigger event for a partnership to initiate campaign reward evaluation
The `x-api-key` header value to be used on this API is your **partner API key**, which can be generated through the dashboard.
The unique identifier of the partnership associated with this trigger event.
The name of the trigger event to process. This identifies the type of event being triggered (e.g., 'user\_signup', 'transaction\_completed'). Trigger name can be found in the triggers section of the Pilot dashboard.
Your external identifier of the user. Used to map the event to a specific user in the Benji platform.
The unique Benji identifier of the user associated with this trigger event.
Additional context data about the transaction that triggered this event. Contains partner-specific information about the transaction details as configured on the trigger in the triggers section on Pilot.
### Response
The UUID of the trigger event. This is the preferred identifier for referencing the trigger event.
```json 200 theme={null}
{
"code": "ok",
"data": {
"trigger_event_id": "f0f8ae48-f005-471c-9a15-ec53c207218c"
}
}
```
```json 400 theme={null}
{
"code": "invalid_token",
"message": "Invalid token"
}
```
```json 401 theme={null}
{
"code": "unauthorized_request",
"message": "Token is not authorized to make this request"
}
```
```json 404 theme={null}
{
"code": "partnership_does_not_exist",
"message": "The partnership does not exist"
}
```
Trigger events are used to activate campaign flows and generate rewards for users. Make sure the trigger is configured in your partnership settings before sending events.
# Get User
Source: https://docs.withbenji.com/api-reference/endpoint/users/get
GET https://api-staging.withbenji.com/users/{id}
Get a single user by ID
The `x-api-key` header value to be used on this API is your **partner API key**, which can be generated through the dashboard.
Unique identifier of the user to retrieve (UUID)
### Response
The requested user object containing all user details including personal information, partner statuses, and merchant associations.
UUID identifier for the user.
The user's first name.
The user's last name.
The user's email address.
The user's phone number in E.164 format.
The date and time when the user was created, in ISO 8601 format.
External system identifier for the user, if applicable.
List of partner status tier objects associated with the user. Each object contains details about the user's status with a partner.
Unique identifier for the partner status tier record.
The user's unique identifier.
The partner's unique identifier.
The status tier's unique identifier for this partner.
External system identifier for the partner status tier, if applicable.
First name as recorded for this partner status tier.
Last name as recorded for this partner status tier.
Total rewards available for this partner status tier.
Total rewards earned for this partner status tier.
Total rewards redeemed for this partner status tier.
Date and time when this partner status tier was created.
List of merchant association objects for the user. Each object contains details about the user's relationship with a merchant.
Unique identifier for the user-merchant association record.
The user's unique identifier.
The merchant's unique identifier.
External system identifier for the merchant association, if applicable.
Total rewards earned with this merchant.
Total rewards redeemed with this merchant.
Date and time when this merchant association was created.
```json 200 theme={null}
{
"code": "ok",
"data": {
"user": {
"created_date": "2026-02-08T00:13:59.970754+00:00",
"email": "test@test.com",
"external_id": null,
"first_name": "Test",
"id": 155,
"last_name": "User",
"merchants": [
{
"created_date": "2026-02-09T14:50:17.198641+00:00",
"external_id": "4731354127758848",
"id": 196,
"merchant_id": 85,
"total_rewards_earned": 0,
"total_rewards_redeemed": 0,
"user_id": 155
},
{
"created_date": "2026-02-11T18:08:18.532675+00:00",
"external_id": "daae5365-c895-48bf-bc23-a9861a351e04",
"id": 215,
"merchant_id": 93,
"total_rewards_earned": 3327,
"total_rewards_redeemed": 0,
"user_id": 155
}
],
"partner_status_tiers": [
{
"created_date": "2026-02-08T00:16:10.255945+00:00",
"external_id": "4731354127758848",
"first_name": "Test",
"id": 287,
"last_name": "User",
"partner_id": 61,
"partner_status_tier_id": 92,
"total_rewards": 8696,
"total_rewards_earned": 8873,
"total_rewards_redeemed": 0,
"user_id": 155
}
],
"phone_number": null,
"uuid_id": "77a5ad82-c27a-47fd-b21d-2d19a3ff222d"
}
}
}
```
```json 400 theme={null}
{
"error": "invalid_token",
"message": "Invalid token"
}
```
```json 401 theme={null}
{
"error": "unauthorized_request",
"message": "Token is not authorized to make this request"
}
```
```json 404 theme={null}
{
"error": "user_does_not_exist",
"message": "The user does not exist"
}
```
This endpoint retrieves detailed information about a specific user, including their loyalty status with all connected partners and merchants.
# Introduction
Source: https://docs.withbenji.com/api-reference/introduction
Welcome to the Benji Platform APIs
All API endpoints require authentication using an **API key** via the `x-api-key` header. API keys can be generated through the Benji dashboard.
## Overview
The Benji Platform APIs are REST-based APIs that give you access to trigger campaigns, manage partnerships, retrieve user loyalty data, and interact with reward transactions. All endpoints use the `x-api-key` header for authentication.
## API Base URL
```
https://api-staging.withbenji.com (sandbox)
https://api.withbenji.com (production - available after approval post sandbox integration)
```
## API Categories
Retrieve partnership details and send trigger events
Get user information and link external users
Retrieve reward transaction details
List and retrieve campaign information
Subscribe to events for real-time updates on users, campaigns, and transactions
# Benji Platform Webhooks Overview
Source: https://docs.withbenji.com/api-reference/webhooks/overview
An overview of the Benji Platform webhooks, allowing you to receive real-time updates on users, campaigns, and reward transactions.
## Overview
The Benji Platform webhooks allow you to receive updates in near real-time on activities in your partnership ecosystem. The following webhook entities are supported:
* **Users**: Updates on a user's partner connect status and lifecycle on the Benji Platform.
* **Campaigns**: Updates to relevant campaigns and their lifecycle on the Benji Platform.
* **Transactions**: Updates on reward transaction statuses and lifecycle.
### Webhook Format
All webhooks contain the following JSON body parameters:
The name of the event
Integer representing an enum of one of the following entity type values:
* **USER (1)** : Indicating a user entity
* **CAMPAIGN (2)** : Indicating a campaign entity
* **TRANSACTION (3)** : Indicating a reward transaction entity
The ID of the entity
### Webhook Authentication
In order to optionally authenticate and validate that the webhook was received from the Benji Platform, Benji provides a header value representing a signature that you can then validate.
The signature is essentially the webhook body, signed with the salt provided in the response from the [subscribe endpoint](/api-reference/webhooks/subscribe), using an HMAC SHA-256 (HS256) algorithm.
To authenticate the webhook, you can go through the following steps:
* Store the salt returned in the subscribe API call.
* When receiving a webhook:
* Extract the timestamp from the x-benji-timestamp header value.
* Create the signature input by concatenating: **timestamp** and **body**.
* Generate a signature using HMAC SHA-256 with your stored salt: HMAC-SHA256(salt, concatenated timestamp and body string).
* Extract the provided signature from the x-benji-signature header value.
* Compare your signed body and the signature provided, and continue processing the webhook only if the signatures match.
The webhook will also contain a header including the datetime in GMT format of the event. Typically, you can use this field to validate that this webhook is not a **replay** event.
Signature described above
String representing the datetime in GMT format of the event
### Webhook body sample
```json theme={null}
{
"event": "reward_transaction_updated",
"entity": 3,
"entity_id": "55af7b67-bf3c-4fbf-81bc-05db9426ca96"
}
```
### Webhook Flow
A typical webhook flow requires the following steps:
* **[Subscribe to an event](/api-reference/webhooks/subscribe)** and register your webhook endpoint. The Benji Platform will send any updates to this event to this endpoint using a **POST** request.
* **Listen to any webhooks** on your registered webhook event endpoint
* **Call the Benji Platform API** to retrieve additional information on the entity based on the event and the entity\_type parameters in the webhook.
### Supported events
The following events and their corresponding entity types are supported:
#### User Events
* user\_partner\_authentication\_created : Indicating a user has successfully connected with a partner through the Benji Platform
Typically after receiving a user entity webhook event, you will interact with the [get user status](/api-reference/endpoint/status/get) endpoint using the entity\_id from the webhook to receive additional user data
#### Campaign Events
* campaign\_updated : Indicating a campaign that you are associated with has been updated
* campaign\_activated : Indicating a campaign you are associated with has been activated (either manually or by reaching its scheduled date)
* campaign\_ended : Indicating a campaign has ended (either manually or by surpassing its end date)
Typically after receiving a campaign entity webhook event, you will interact with the [get campaign](/api-reference/endpoint/campaigns/get) endpoint using the entity\_id from the webhook to receive additional campaign data
#### Transaction Events
* transaction\_authenticated : Indicating a [transaction authentication token](/api-reference/endpoint/transactions/authenticate) has been created
* transaction\_created : Indicating a [transaction has been created](/api-reference/endpoint/transactions/create)
* transaction\_status\_updated : Indicating a transaction has been updated, typically meaning a status change on the transaction
Typically after receiving a transaction entity webhook event, you will interact with the [get reward transaction](/api-reference/endpoint/transactions/get) endpoint using the entity\_id from the webhook to receive additional transaction data
# Subscribe to a webhook event
Source: https://docs.withbenji.com/api-reference/webhooks/subscribe
POST https://notificationservice-staging.withbenji.com/webhooks/subscribe
Subscribe to a specific event or all entity events on the Benji Platform
The `x-api-key` header value to be used on this API is your **partner API key**, which can be generated through the dashboard.
Your endpoint URL that will receive the event webhooks
The event you are subscribing to. Note that if an event is not specified, all events for the entity type specified will be subscribed to.
Integer representing an enum of one of the following entity type values to subscribe to:
* **USER (1)** : Indicating a user entity
* **CAMPAIGN (2)** : Indicating a campaign entity
* **TRANSACTION (3)** : Indicating a reward transaction entity
If you do not specify an entity type or an event, you will be subscribing to all webhook events with the provided endpoint.
### Return values
A true or false value indicating whether the subscription was successful.
```json 200 theme={null}
{
"code": "ok",
"data": {
"subscribed": true
}
}
```
```json 400 theme={null}
{
"error": "invalid_subscription",
"message": "Invalid entity or event"
}
```
```json 400 theme={null}
{
"error": "subscription_already_exists",
"message": "A subscription already exists for this event"
}
```
```json 401 theme={null}
{
"error": "unauthorized_partner",
"message": "Invalid key, or key is not authorized to make this call"
}
```
```json 500 theme={null}
{
"error": "unexpected_error",
"message": "An unexpected error has occurred"
}
```
# Update a webhook subscription
Source: https://docs.withbenji.com/api-reference/webhooks/update
PUT https://notificationservice-staging.withbenji.com/webhooks/subscribe
Update a webhook subscription for a specific event or all entity events on the Benji Platform
The `x-api-key` header value to be used on this API is your **partner API key**, which can be generated through the dashboard.
Your endpoint URL that will receive the event webhooks
The event you are subscribing to. Note that if an event is not specified, all events for the entity type specified will be subscribed to.
Integer representing an enum of one of the following entity type values to subscribe to:
* **USER (1)** : Indicating a user entity
* **CAMPAIGN (2)** : Indicating a campaign entity
* **TRANSACTION (3)** : Indicating a reward transaction entity
To delete an endpoint subscription, just use this API with an empty endpoint parameter.
### Return values
A true or false value indicating whether the subscription was successful.
```json 200 theme={null}
{
"code": "ok",
"data": {
"subscribed": true
}
}
```
```json 400 theme={null}
{
"error": "invalid_subscription",
"message": "Invalid entity or event"
}
```
```json 401 theme={null}
{
"error": "unauthorized_partner",
"message": "Invalid key, or key is not authorized to make this call"
}
```
```json 404 theme={null}
{
"error": "event_not_exists",
"message": "The specified event subscription does not exist"
}
```
```json 500 theme={null}
{
"error": "unexpected_error",
"message": "An unexpected error has occurred"
}
```
# Create a token to initialize the Benji Connect SDK
Source: https://docs.withbenji.com/connect/create_token
POST https://api-staging.withbenji.com/auth/connect
Create a token to initialize an instance of the Benji Connect SDK or Benji Hosted Connect.
The `x-api-key` header value to be used on this API is your **partner API
key**, which can be generated through the [Developer](/pilot/developer) page
in Pilot.
The Connect Token API resolves **merchant** and **partner** from
**`partnership_id`**.
### Request body
The unique identifier of the partnership on the Benji Platform.
The connection mode for the SDK (Connect = 1, Transfer = 3, and Redeem = 4).
See [Connect modes](/connect/modes).
Display name shown in the Connect UI. If omitted, the name configured for the
partnership on the platform is used.
A unique identifier for the user in your system. When set, the flow can skip
the authentication step for your user.
Custom attributes for the connection flow (e.g. transfer actions).
Array of actions (e.g. transfer amounts).
Action mode: **Transfer = 3**
Preselected points amount for action.
Whether the user can edit the amount in the UI.
### Example requests
```json theme={null}
{
"partnership_id": 49,
"mode": 1,
"display_name": "Reward Cookies"
}
```
```json theme={null}
{
"partnership_id": 49,
"mode": 1,
"display_name": "Reward Cookies",
"user_external_id": "user-1234"
}
```
```json theme={null}
{
"partnership_id": 49,
"mode": 3,
"display_name": "Reward Cookies",
"custom_attributes": {
"actions": [
{
"mode": 3,
"amount": 1000,
"allows_editing": true
}
]
}
}
```
```json theme={null}
{
"partnership_id": 49,
"mode": 4,
"display_name": "Reward Cookies"
}
```
### Return values
The connect token to pass when [initializing the Benji Connect
SDK](/connect/initialization) or as `connect_token` on the [**Benji Hosted
Connect**](/connect/hosted/introduction) URL.
Base URL for **Benji Hosted Connect** for this partnership. Append `?connect_token=` (and optional query parameters) to send users into **Benji Hosted Connect**. May be empty if **Benji Hosted Connect** URLs are not enabled for your account.
```json 200 theme={null}
{
"code": "ok",
"data": {
"token": "0c371a1c-aa81-11ef-b28c-0a58a9feac02",
"connect_url": "https://connect.withbenji.com/khkgfoud76td"
}
}
```
```json 401 theme={null}
{
"error": "unauthorized_partner",
"message": "Invalid key, or key is not authorized to make this call"
}
```
```json 500 theme={null}
{
"error": "unexpected_error",
"message": "An unexpected error has occurred"
}
```
# Exchange the Connect Token
Source: https://docs.withbenji.com/connect/exchange_token
POST https://authservice-staging.withbenji.com/access/token/exchange
Exchange the short-lived token returned from the Benji Connect SDK to a long-lived access token and refresh token using the Benji Platform API
The `x-api-key` header value to be used on this API is your **partner API key**, which can be generated through the dashboard.
The **string token** passed as the first argument to your **`onSuccess`** callback after a successful Connect flow ([Methods & Events](/connect/methods#onsuccess)). This is the exchange token produced when the transport layer completes with **`FLOW_SUCCESS`** — pass it here, not the raw connect token used to initialize the **Benji Connect SDK**.
### Return values
The Benji Platform ID associated with the user.
Your system ID as specified on the Benji Platform.
An object representing the access\_token, refresh\_token to use when using the Benji Platform APIs as well as the access token expiry date. Once an access token expires, you can use the refresh token to obtain a new access token silently without requiring the user to authenticate again.
Access Token to use when making user-oriented requests to the Benji Platform APIs
Refresh Token to [use](/api-reference/endpoint/authentication/refresh) in order to silently obtain a new access token when it expires
A string representing a datetime of when this access token will expire
```json 200 theme={null}
{
"code": "ok",
"data": {
"user_id": 1,
"merchant_id": 1,
"token_data": {
"access_token": "0c371a1c-aa81-11ef-b28c-0a58a9feac02",
"refresh_token": "05tghegts-aa81-sgte-hgte-u8nhgbvgtio",
"access_token_expires_at": "Tue, 22 Oct 2024 21:57:02 GMT"
}
}
}
```
```json 401 theme={null}
{
"error": "invalid_exchange_token",
"message": "Invalid exchange token"
}
```
```json 401 theme={null}
{
"error": "expired_exchange_token",
"message": "The exchange token has expired"
}
```
Access tokens are typically valid for 90 days. You can refresh an access token either before it expires proactively, or after calling an API and getting an expired\_token 401 status code.
Call the Exchange Token API soon after **`onSuccess`**. The exchange token is valid for **15 minutes** after the successful callback.
See also [Methods & Events](/connect/methods#onsuccess) in the **Benji Connect SDK** docs for the shape of **`onSuccess`** metadata alongside the token.
# Introduction to Benji Hosted Connect
Source: https://docs.withbenji.com/connect/hosted/introduction
A fully hosted solution for connecting members to reward partners.
## Overview
**Benji Hosted Connect** is a fully hosted solution that allows you to connect your members to reward loyalty partners without integrating an SDK into your application. You send users to **Benji Hosted Connect**, which loads the [**Benji Connect SDK**](/connect/introduction) behind the scenes as a modal. You can also drive the flow entirely via **redirect**: create a token on your server, send the user to the **Benji Hosted Connect** URL with `connect_token`, and optionally return them to your app using a **Redirect URL** configured in Pilot.
This approach is ideal for:
* **Quick integration** — Get started without any frontend code changes beyond linking or redirecting
* **Server-side flows** — Connect users through email campaigns or backend-generated URLs
* **Multi-platform support** — One **Benji Hosted Connect** URL pattern for web, mobile, and other platforms
**Benji Hosted Connect** and the [**Benji Connect
SDK**](/connect/introduction) use the same token and callback semantics.
Choose **Benji Hosted Connect** (redirect) for simplicity, or embed the
**Benji Connect SDK** in your own app when you need the modal inside your UI.
## How it works (high level)
```mermaid theme={null}
flowchart LR
merchantApp[MerchantApp]
createToken[CreateTokenAPI]
benjiHosted["Benji Hosted Connect"]
sdkModal["Benji Connect SDK modal"]
redirectBack[RedirectToMerchant]
merchantApp --> createToken
createToken --> merchantApp
merchantApp --> benjiHosted
benjiHosted --> sdkModal
sdkModal --> redirectBack
redirectBack --> merchantApp
```
1. [Create a connect token](/connect/create_token) on your server using your **partner API key** (from [Pilot Developer](/pilot/developer)) and the fields your flow needs (`partnership_id`, `mode`, optional `user_external_id`, optional `custom_attributes`, etc.).
2. Send the user to **Benji Hosted Connect**. Either:
* Use the **`connect_url`** from the Create Token response and append the token: `?connect_token=`, **or**
* Open the **Benji Hosted Connect** base URL for your partnership and pass `connect_token` (and other query parameters below) as needed.
3. The user completes Connect (link, transfer, or redeem depending on [mode](/connect/modes)) in the modal inside **Benji Hosted Connect**.
4. If you configured a **Redirect URL** in Pilot, the browser is sent back to your URL with query parameters describing the outcome (see [Redirect URL and query parameters](#redirect-url-and-query-parameters)).
5. Use [Exchange Token](/connect/exchange_token) with the short-lived token from a successful flow when you need long-lived API access. Subscribe to [webhooks](/api-reference/webhooks/overview) for asynchronous lifecycle events.
Alternatively, Benji can connect to your IdP for native authentication of your users. Contact your Benji account manager for IdP setup.
## Building the Benji Hosted Connect URL
After [Create Token](/connect/create_token), you receive:
* **`token`** — Short-lived connect token used to initialize Connect.
* **`connect_url`** — Base URL for **Benji Hosted Connect** for this partnership (format may vary by environment).
Append the token so Connect can start:
```
?connect_token=
```
You may add other query parameters supported by **Benji Hosted Connect** (see next section). For correlation (e.g. CSRF protection or “which cart”), pass **`state`** on the inbound URL; it is echoed back on the [redirect](#redirect-url-and-query-parameters).
## Benji Hosted Connect query parameters
These parameters apply when the user lands on **Benji Hosted Connect**. Exact behavior is defined by the **Benji Hosted Connect** implementation; the following reflects the reference integration pattern.
| Parameter | Required | Description |
| ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connect_token` | No\* | If present, **Benji Hosted Connect** uses this token to open Connect. If omitted, **Benji Hosted Connect** may create a token server-side using the partnership context and other parameters. |
| `mode` | No | Connect flow mode: `1` = Connect, `3` = Transfer, `4` = Redeem (defaults to `1`). See [Connect modes](/connect/modes). |
| `user_external_id` | No | Your user identifier; forwarded into token creation when **Benji Hosted Connect** creates a token. |
| `amount` | No | When set together with `mode`, can be used to build `custom_attributes.actions` (e.g. transfer amount). |
| `state` | No | Opaque value echoed back on redirect to your **Redirect URL** for correlation. |
| `preview` | No | Pilot preview mode (e.g. `preview=1`) for reviewing **Benji Hosted Connect** content from the dashboard. |
\* **Token source:** For production flows, prefer passing `connect_token` from your server after Create Token, or rely on server-side token creation on **Benji Hosted Connect** when your integration supplies the right context.
### Resolving the partnership
**Benji Hosted Connect** resolves which partnership to show by:
* **Path** — e.g. `https:///` (common for default hosted domains), or
* **Hostname** — **custom domain** configured in Pilot for the partnership.
## Redirect URL and query parameters
Configure where users return **after** Connect completes by setting **Redirect URL (Optional)** on the partnership **Landing Page** in Pilot (partnership campaign / landing page editor).
If this URL is set:
* **Benji Hosted Connect** redirects the user there **after success or error** (not only on success). Your app should read the **`status`** query parameter.
* **Pilot** (tooltips and labels next to Redirect URL) might not list every parameter. **Benji Hosted Connect** may append more than what you see in the UI. Use the table below as the **integration contract** when you parse the redirect URL in your app:
| Parameter | When present | Description |
| ------------------ | ----------------------------------------------------------------- | ----------------------------------------------------------- |
| `status` | Success or error flow | `success` or `error`. Use this to branch in your app. |
| `state` | If you passed `state` on the inbound **Benji Hosted Connect** URL | Same value you sent for correlation. |
| `benji_user_uuid` | When available | Preferred stable user identifier when returned by the flow. |
| `benji_user_id` | When UUID is not available | Numeric Benji user ID. |
| `trigger_event_id` | When a transaction-related event applies | Useful for transfer/redeem flows tied to triggers. |
Redirects use absolute (`https://...`) or relative URLs; query strings are merged appropriately.
## Optional platform behavior (reference)
The **Benji Hosted Connect** reference implementation may send **campaign triggers** (e.g. after a successful connect) depending on your Benji Platform configuration. This is not automatic for every tenant—see [Triggers](/api-reference/endpoint/triggers/send) and your account setup.
## Integration checklist
See the [Benji Connect overview](/connect/overview#integration-checklist) for API keys, token exchange, webhooks, and how **Benji Hosted Connect** compares to the embedded **Benji Connect SDK**.
# Initialize the Benji Connect SDK
Source: https://docs.withbenji.com/connect/initialization
Importing and initializing the Benji Connect SDK to start connecting your users to their loyalty platforms.
## Installing the Benji Connect SDK
The **Benji Connect SDK** can be added to your application by including the SDK script in your HTML head.
```html theme={null}
```
or by installing the package via npm
```bash theme={null}
npm install @benji-money/connect-sdk
```
or by installing the package via yarn
```bash theme={null}
yarn add @benji-money/connect-sdk
```
or by installing the package via pnpm
```bash theme={null}
pnpm add @benji-money/connect-sdk
```
Note that you will be able to access the above packages/scripts once
authorized to use the Benji SDKs. Contact your account manager for additional
info.
## How the Benji Connect SDK loads Connect
When you call **`open()`**, the **Benji Connect SDK** creates a modal overlay and loads the Connect experience inside it.
## Initializing the Benji Connect SDK
The **Benji Connect SDK** is initialized with the following parameters:
Environment for the Connect flow: `development` | `sandbox` | `production`.
Connect token from the [Create Token](/connect/create_token) API.
Called when the flow completes successfully (`FLOW_SUCCESS`). Receives the
exchange token and [metadata](/connect/methods#onsuccess).
Called when the user leaves the Connect UI (`FLOW_EXIT`), whether or not
`onSuccess` ran.
Called when an error is reported from the Connect flow (`ERROR`).
Called for mid-flow and auxiliary events (e.g. `AUTH_SUCCESS`). See [Methods &
Events](/connect/methods#onevent).
Types are **optional**. The same runtime behavior applies to JavaScript and TypeScript; TypeScript users can import types from `@benji-money/connect-sdk` for autocomplete.
```javascript JavaScript theme={null}
import { ConnectSDK } from "@benji-money/connect-sdk";
let sdk = null;
function initializeSDK(token) {
sdk = new ConnectSDK({
environment: "sandbox",
token: token,
onSuccess: (token, metadata) => {
console.log("Benji Connect successful");
// Exchange `token` via Exchange Token API; use metadata for UI
},
onError: (error, errorId, metadata) => {
console.log("Benji Connect onError", error, errorId);
},
onExit: (metadata) => {
console.log("Benji Connect onExit", metadata.trigger);
},
onEvent: (type, metadata) => {
console.log("Benji Connect onEvent", type);
},
});
}
```
```typescript TypeScript theme={null}
import {
ConnectSDK,
type BenjiConnectOnSuccessMetadata,
type BenjiConnectMetadata,
type BenjiConnectOnExitMetadata,
type BenjiConnectEventType,
} from "@benji-money/connect-sdk";
let sdk: ConnectSDK | null = null;
function initializeSDK(token: string): void {
sdk = new ConnectSDK({
environment: "sandbox",
token,
onSuccess: (token: string, metadata: BenjiConnectOnSuccessMetadata) => {
console.log("Benji Connect successful", token, metadata.action);
},
onError: (
error: Error,
errorId: string,
metadata: BenjiConnectMetadata,
) => {
console.log("Benji Connect onError", error, errorId);
},
onExit: (metadata: BenjiConnectOnExitMetadata) => {
console.log("Benji Connect onExit", metadata.trigger);
},
onEvent: (type: BenjiConnectEventType, metadata: BenjiConnectMetadata) => {
console.log("Benji Connect onEvent", type);
},
});
}
```
To open the UI after initialization, call **`await sdk.open()`** (see [Methods & Events](/connect/methods#open)).
# Introduction to the Benji Connect SDK
Source: https://docs.withbenji.com/connect/introduction
An SDK that simplifies connectivity to reward partners.
![title]()
## Overview
The Benji Connect SDK is a JavaScript/TypeScript library that opens a **modal** to the Benji Connect experience. After your user completes the flow, you receive a short-lived token to [exchange](/connect/exchange_token) for API access, plus structured metadata about the user and any transaction context.
**Connect modes** (what the user is doing in the UI—link account, transfer points, redeem points) are determined by the [connect token](/connect/create_token) you create on your server (`mode` and optional `custom_attributes`). See [Connect modes](/connect/modes) for values and usage. That is separate from your **partnership type** in Pilot (e.g. [Direct vs Marketplace](/pilot/concepts)), which describes how the partnership is sourced.
The connect token encodes mode, partnership, and user hints. You create it with your **partner API key** ([Pilot Developer](/pilot/developer)) via the [Create Token](/connect/create_token) API.
### Benji Connect flow
1. [Create a connect token](/connect/create_token) on your server (`partnership_id`, `mode`, optional `user_external_id`, optional `custom_attributes`, etc.).
2. [Initialize the Benji Connect SDK](/connect/initialization) with that token, your [environment](/connect/initialization) (`development` | `sandbox` | `production`), and optional callbacks (`onSuccess`, `onError`, `onExit`, `onEvent`).
3. Call **`open()`** when the user starts Connect (e.g. button click). The **Benji Connect SDK** presents the Connect flow in that modal; the Connect URL includes your token as **`connect_token`** (same idea as [**Benji Hosted Connect**](/connect/hosted/introduction) query parameters).
4. [Handle callbacks](/connect/methods): completion and errors are described in the Methods & Events page (`onSuccess` receives the exchange token after **`FLOW_SUCCESS`**).
5. [(Optional) Exchange the token](/connect/exchange_token) from **`onSuccess`** for long-lived `access_token` / `refresh_token` pairs for user-scoped Benji APIs.
Treat access and refresh tokens as secrets. Store them securely and rotate using the refresh flow when access tokens expire.
# Benji Connect SDK methods and events
Source: https://docs.withbenji.com/connect/methods
Overview of supported methods and events in the Benji Connect SDK
Once initialized, the Benji Connect SDK exposes the methods below. User-driven outcomes are delivered through the callbacks you passed in the [initialization](/connect/initialization) step.
## Methods
### open()
Opens the Benji Connect UI in a modal. Call this after construction, typically from a button click or route handler.
```javascript theme={null}
document.getElementById('connectBtn').addEventListener('click', async (e) => {
e.preventDefault();
if (sdk) {
await sdk.open();
}
});
```
### ping()
Returns the string `'pong'`. Intended for quick debugging to verify the **Benji Connect SDK** bundle loaded; not required for production flows.
## Events
Callbacks match the `@benji-money/connect-sdk` contract. Types below are exported as `BenjiConnectEventType`, `BenjiConnectExitTrigger`, and related interfaces for TypeScript users.
### onSuccess
Fired when the Connect **flow completes successfully** (transport event `FLOW_SUCCESS`). This is the signal that the user finished link, transfer, or redeem as configured by the [connect token](/connect/create_token) ([modes](/connect/modes)).
**Arguments**
* **`token`** (`string`) — Short-lived **exchange** token. Use it with [Exchange Token](/connect/exchange_token) to obtain access and refresh tokens for user-scoped APIs. Exchange it promptly (see the Exchange Token page for validity).
* **`metadata`** — Payload aligned with `BenjiConnectOnSuccessMetadata`:
* **`context`** — SDK context (`namespace`, `version`).
* **`action`** (optional) — One of `connect`, `transfer`, `redeem` (`BenjiConnectAuthAction`).
* **`user_data`** (optional) — Structured user and status:
* **`user`**: `id`, `first_name`, `last_name`, optional `uuid`
* **`status`**: `status_id`, `num_of_rewards`, `reward_status`, optional `partner_status_tier_id`
* **`extra_data`** (optional): e.g. totals, dates
* **`transaction_data`** (optional) — When applicable: `action`, `amount`, `trigger_event_id`, `trigger_name`
Example shape (illustrative):
```json theme={null}
{
"context": { "namespace": "benji-connect-sdk", "version": "1.0.0" },
"action": "connect",
"user_data": {
"user": {
"id": 12345,
"first_name": "Test",
"last_name": "User",
"uuid": "550e8400-e29b-41d4-a716-446655440000"
},
"status": {
"status_id": "********4156",
"num_of_rewards": 45000,
"reward_status": "Mosaic 1"
}
},
"transaction_data": {
"action": "redeem",
"amount": 1000,
"trigger_event_id": "abc-123",
"trigger_name": "connect"
}
}
```
### onExit
Fired when the user leaves the Connect UI (transport event `FLOW_EXIT`). The **Benji Connect SDK** closes the modal after this callback.
**Arguments**
* **`metadata`** — `BenjiConnectOnExitMetadata`:
* **`context`**
* **`trigger`** — Why the UI closed (`BenjiConnectExitTrigger`):
* **`ACTION_BUTTON_CLICKED`** — User completed the flow and used the primary dismiss/action control.
* **`CLOSE_BUTTON_CLICKED`** — User closed via the chrome close control.
* **`TAPPED_OUT_OF_BOUNDS`** — User dismissed by tapping outside the modal (when supported).
* **`BACK_TO_MERCHANT_CLICKED`** — Deprecated; may still appear in older flows.
* **`step`** (optional) — Flow step when exit occurred.
`onExit` can run whether or not `onSuccess` ran. Only **`onSuccess`** indicates a completed successful Connect flow.
### onEvent
Fired for mid-flow and auxiliary transport events. The first argument is **`type`** (`BenjiConnectEventType`).
**Arguments**
* **`type`** — Values you may see include:
* **`AUTH_SUCCESS`** — Mid-flow authentication success. Delivered to **`onEvent`** only (not **`onSuccess`**). Use for progress or analytics; metadata can include action, user, and token-related fields.
* **`EVENT`** — Generic events with additional fields in **`metadata`**.
* Other values may be forwarded for forward compatibility.
* **`metadata`** — Varies by `type`; always includes **`context`**. Additional keys are merged from the payload when present.
**Routing (important):**
* **`FLOW_SUCCESS`** invokes **`onSuccess`** with the exchange token — not **`onEvent`**.
* **`FLOW_EXIT`** invokes **`onExit`** — not **`onEvent`**.
* **`ERROR`** invokes **`onError`**.
**Practical distinction:** Implement **`onSuccess`** for “flow completed + exchange token.” Use **`onEvent`** when you need mid-flow **`AUTH_SUCCESS`** or generic **`EVENT`** data before completion.
### onError
Fired when an error occurs in the Connect flow (`ERROR` transport event).
**Arguments**
* **`error`** — Typically an `Error` instance or platform-specific error information.
* **`error_id`** — Identifier for support correlation when applicable.
* **`metadata`** — Additional context; includes **`context`** where provided.
Documented error names include:
* **`unexpected_error`** — Unexpected platform error.
* **`partner_connect_error`** — Failure while connecting the user to the selected loyalty network.
The **Benji Connect SDK** may refine **`onError`** payloads in a future release; treat **`error`**, **`error_id`**, and **`metadata`** as the stable integration surface.
# Connect modes
Source: https://docs.withbenji.com/connect/modes
Connect, Transfer, and Redeem modes for Benji Connect tokens and the Benji Connect SDK.
## Overview
The **mode** on your [connect token](/connect/create_token) controls what the user does in Benji Connect: link their loyalty account, move points (**Transfer**), or spend points (**Redeem**). Modes apply to both [Benji Hosted Connect](/connect/hosted/introduction) and the [Benji Connect SDK](/connect/introduction).
| Mode | Value | Typical use |
| ------------ | ----- | ------------------------------------------------------------------------------------------------ |
| **Connect** | `1` | User links their loyalty account to your program. |
| **Transfer** | `3` | User transfers points (can be preselected amount via connect token `custom_attributes.actions`). |
| **Redeem** | `4` | User redeems points for offers or perks. |
**Pilot “Direct” partnership** ([concepts](/pilot/concepts)) describes how a
partnership is created—not the same as **Connect mode `1`**. Mode is always
the numeric field on the token request.
## Connect (`mode`: 1)
Default linking flow: authenticate and connect the member’s loyalty account. Use a minimal [Create Token](/connect/create_token) body with `partnership_id` and `mode: 1` (or rely on API defaults where supported).
## Transfer (`mode`: 3)
Used when the user should move points as part of the flow. Customize by supplying **`custom_attributes.actions`** with one or more action objects:
* **`mode`**: `3` (Transfer)
* **`amount`**: Preselected points amount
* **`allows_editing`**: Whether the user can change the amount in the UI
See the Transfer example on [Create Token](/connect/create_token).
## Redeem (`mode`: 4)
Used when the user should redeem points. Connect token **`mode`** set to **`4`**. Customize offers and perks by adding redeem actions to the partnership campaign in Pilot.
See the Redeem example on [Create Token](/connect/create_token).
## Benji Hosted Connect query parameters
On [**Benji Hosted Connect**](/connect/hosted/introduction), **`mode`** and optional **`amount`** in the URL can influence token creation for transfer/redeem-style entry points. Prefer server-side [Create Token](/connect/create_token) for production so amounts and partnership context are authoritative.
# Benji Connect Overview
Source: https://docs.withbenji.com/connect/overview
Choose the right integration approach for connecting members to reward partners.
## What is Benji Connect?
Benji Connect enables you to connect your members to reward loyalty partners, allowing them to earn and redeem rewards through your platform. There are two ways to integrate Benji Connect into your application:
* **Benji Hosted Connect** — Connect users through [**Benji Hosted Connect**](/connect/hosted/introduction) (Benji-managed page; no embedded JavaScript required)
* **Benji Connect SDK** — Embed the same Connect experience as a [modal in your app](/connect/introduction)
Both approaches accomplish the same goal—connecting your members to reward partners—but differ in implementation, customization, and user experience. Both use a [connect token](/connect/create_token) and support [Connect modes](/connect/modes) (link, transfer, redeem) depending on how you create the token.
## Benji Hosted Connect
**Benji Hosted Connect** is a fully hosted solution where you redirect users to a Benji-managed page that handles the entire Connect flow (internally using the same patterns as the **Benji Connect SDK**). You integrate primarily via URLs, [Pilot](/pilot/developer) configuration, and APIs—not by embedding JavaScript. No frontend code changes are required.
**Best suited for:**
* Quick integrations without building your own Connect UI
* Server-side or campaign-driven links
* Multi-platform use of a single **Benji Hosted Connect** URL pattern
* Dedicated **Benji Hosted Connect** experiences and custom domains configured in Pilot
Learn how to integrate with Benji Hosted Connect
## Benji Connect SDK
The **Benji Connect SDK** is a JavaScript/TypeScript library you load from npm or script tag. It opens the Connect experience in a modal over your page and delivers callbacks to your code. With this solution you have full control over when and how the connection flow is triggered.
**Best suited for:**
* Native app integrations
* Web applications requiring seamless user experience
* Scenarios where you want the connection flow embedded in your UI
* Tight control over when the modal opens and how you handle [events](/connect/methods)
Learn how to integrate with the Benji Connect SDK
## Comparison
| Feature | Benji Hosted Connect | Benji Connect SDK |
| ------------------- | ------------------------------------------ | ------------------------------------------------------ |
| **Integration** | Redirect + APIs; optional query parameters | Embed the **Benji Connect SDK**; initialize with token |
| **Customization** | **Benji Hosted Connect** in Pilot | Embedded in your UI |
| **User experience** | Full-page **Benji Hosted Connect** entry | Inline modal |
| **Best for** | Email campaigns, dedicated partner pages | Native app integrations, web applications |
| **Effort** | Minimal | Requires frontend integration |
You can use both: e.g. **Benji Hosted Connect** for campaigns and the **Benji
Connect SDK** for logged-in web sessions. Choose the approach that best fits
each use case in your application.
## Integration checklist
Use this list when wiring **Benji Hosted Connect**, the **Benji Connect SDK**, and your backend.
| Step | What to do | Where to read more |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| API access | Create a **partner API key** in Pilot | [Developer](/pilot/developer) |
| Token | `POST` [Create Token](/connect/create_token) with `partnership_id`, `mode`, and optional fields | [Create Token](/connect/create_token), [Modes](/connect/modes) |
| **Benji Hosted Connect** URL | Use `connect_url` + `?connect_token=`; configure **Redirect URL** and optional custom domain in Pilot | [Benji Hosted Connect](/connect/hosted/introduction) |
| **Benji Connect SDK** | Install package, [initialize](/connect/initialization), call `open()`, handle [callbacks](/connect/methods) | [Introduction](/connect/introduction) |
| Long-lived access | `POST` [Exchange Token](/connect/exchange_token) with the token from **`onSuccess`** within **15 minutes** | [Exchange Token](/connect/exchange_token) |
| Async updates | Subscribe to webhooks for user and transaction lifecycle | [Webhooks overview](/api-reference/webhooks/overview) |
# API Usage
Source: https://docs.withbenji.com/integrations/api_usage
How Benji uses integration APIs to process transactions and determine eligibility
Benji uses information about loyalty customers, their status, and their payment transactions in order to power the automatic processing and eligibility determination for each transaction.
## API Access
Not all data is present in webhooks provided by our integrators, so we correlate that information with loyalty customers using their APIs.
Benji uses the following APIs:
* **Payments**: Correlate payments with orders and customers.
* **Loyalty Customers**: Ensure we can connect the customer to their loyalty accounts for our suite of partners.
* **Orders**: Analyze the orders placed by customers to determine eligibility for rewards.
> **Note:** This data applies to all supported integrations (e.g., Square, Stripe). See [Integration Overview](./overview) for platform-specific details.
## Event Payload Examples
```json theme={null}
{
"type": "purchase",
"customer_id": "12345",
"amount": 100.00,
"items": [
{ "sku": "A1", "qty": 2 }
]
}
```
***
## Related Topics
* [Webhooks](./webhooks)
* [API Reference: Webhooks](../api-reference/webhooks/overview)
* [Pilot Concepts](../pilot/concepts)
# Benji Integrations
Source: https://docs.withbenji.com/integrations/introduction
Connect your payment processor or loyalty platform to the Benji Platform
Benji integrates with other platforms in the market in order to make onboarding and using our platform easy and seamless.
## Why Integrate?
* Unlock loyalty and rewards for your customers with **zero code**.
* Seamlessly connect your payment processor (starting with Square, more coming soon).
* Blend speed and security.
## Supported Platforms
* **Square Payment Processing** (available now)
* **Square Loyalty** (available now)
* **Stripe** (coming soon)
* **Shopify** (coming soon)
* **Salesforce** (coming soon)
* **WooCommerce** (coming soon)
* **Adyen** (coming soon)
* More to follow!
[Get started with setup →](./setup)
***
## Related Topics
* [Integration Setup](./setup)
* [Integration Overview](./overview)
* [Benji Connect SDK introduction](../connect/introduction)
# Integration Overview
Source: https://docs.withbenji.com/integrations/overview
Supported integrations, data access, and security for the Benji Platform
Benji Integrations allow you to connect your payment processor, e-commerce framework, or loyalty platform to seamlessly onboard with our platform.
## Supported Integrations
| Platform | Status |
| ------------------------- | -------------------- |
| Square Payment Processing | [Available](./setup) |
| Square Loyalty | [Available](./setup) |
| Stripe | Coming soon |
| Shopify | Coming soon |
| Salesforce | Coming soon |
| WooCommerce | Coming soon |
| Adyen | Coming soon |
| Others | Planned |
## What Data is Accessed?
* Customer IDs
* Loyalty customer information
* Payment transaction information
* Order contents
## How Benji Uses This Data
We use this data to link your customers to our loyalty partners, enabling account connections across platforms and powering our eligibility and rewards system.
> **Technical Users:** For exact data fields and payloads, see the [API Reference](../api-reference/webhooks/overview).
## Security & Permissions
* OAuth-based authorization
* Minimum access required
* Your data is secure and private
***
## Related Topics
* [Integration Setup](./setup)
* [API Reference: Webhooks](../api-reference/webhooks/overview)
# Integration Setup
Source: https://docs.withbenji.com/integrations/setup
Connect your Square account to Benji in a few simple steps
Connecting Square to Benji is simple and requires **no engineering effort**.
## Prerequisites
* Benji account
* Square account
## Steps to Connect Square
1. Go to your Benji Developer Settings.
2. Find "Square" in the Integrations list.
3. Click the “Connect” button.
4. Log in with your Square merchant username and password.
5. Review and accept the requested permissions (we only request the minimum needed).
6. That’s it! Your Square account is now connected to Benji.
If you run into issues, see [Troubleshooting](./troubleshooting).
## Connecting Your Consumers to Benji's Loyalty Partners
Once Square is connected, Benji can link your customers to our suite of loyalty partners.
For more information about Benji Connect and how to link your consumers to a loyalty partner consumer, see [Benji Connect](/connect/overview).
## FAQ
**Do I need to write any code?**
> No! Benji handles all the integration work for you.
**Who on my team is needed to authorize Square?**
> Whoever your Square administrator is, or another user with admin privileges.
***
## Related Topics
* [Troubleshooting](./troubleshooting)
* [Benji Connect SDK initialization](../connect/initialization)
# Troubleshooting
Source: https://docs.withbenji.com/integrations/troubleshooting
Common integration issues and how to resolve them
Having trouble with your integration? Here are some common issues and solutions.
## Connection Issues
* Ensure your Square account credentials are correct.
* If an admin has disconnected your Square account, you can find this in your Square console at: Settings > App integrations. Benji should be listed. If it is not, then we have been disconnected and you'll need to reauthorize through the Benji UI.
## Data Sync Issues
* Data may take a few minutes to sync after connecting.
* While Square sends events almost in real time, we process those payments in the background. Loyalty accruals may not be immediate.
## Support
If you need help, contact [support@withbenji.com](mailto:support@withbenji.com).
***
## Related Topics
* [Integration Setup](./setup)
* [Contact Support](mailto:support@withbenji.com)
# Square Webhooks
Source: https://docs.withbenji.com/integrations/webhooks
How Benji uses Square webhooks for purchases and refunds
Benji listens to webhooks from Square, giving access to events such as purchases and refunds.
## What are Webhooks?
Webhooks are automated messages sent from services or applications when something happens. Benji uses Square webhooks to stay up-to-date with your customers’ activity.
## Events We Listen To
* Payments
* Refunds
* Orders
## How Benji uses these events
When an event occurs, Benji:
* Checks eligibility for loyalty accrual or redemption
* Updates customer loyalty status in our integrated Loyalty Partners' systems
* Handles reversals in case of refunds
## No Setup Required
Benji manages all Square webhook subscriptions for you. No action is needed on your end.
> **Note:** Webhook endpoints are managed automatically by Benji and are not user-configurable in the UI.
***
## Related Topics
* [API Reference: Webhooks](../api-reference/webhooks/overview)
* [Pilot Concepts](../pilot/concepts)
# Analytics Page
Source: https://docs.withbenji.com/pilot/analytics
A granular view of all your campaigns, partnerships and member traction
The Analytics page provides a comprehensive view of performance across all your partnerships. You can filter and analyze data by time period, activity type, partner, and metric to understand how your campaigns are performing.
![Analytics]()
### Filters and Views
**Date Range**
Select a custom date range to view analytics for a specific time period. This updates both the chart and the partner performance table.
**Filter by Type**
Filter activity by campaign type:
* **All**: View all activity across earn, redeem, and transfer campaigns
* **Earn Activity**: View only point earning activity
* **Redeem Activity**: View only point redemption activity
* **Transfer Activity**: View only point transfer activity
**Filter by Partner**
Select specific partners to view their performance, or select All to view all partners.
**View Metric**
Choose which metric to display in the chart and table:
* **All**: View aggregated metrics
* **View in Points**: Display total points earned or redeemed
* **View in \$ Spent**: Display dollar value of transactions
* **View in # of Transactions**: Display transaction count
* **View in Connected Users**: Display number of connected members
**Clear Filters**
Reset all filters to their default state.
### Analytics Chart
The chart displays your selected metric over the chosen time period, allowing you to visualize trends and identify spikes or dips in activity.
### Partner Performance Table
The table displays detailed metrics for each partner:
* **Partner Name**: The name of the partner
* **Campaigns**: Number of active campaigns with this partner
* **Transactions**: Total transaction count for the selected period
* **Points Earned**: Total points earned through this partnership
* **Points Redeemed**: Total points redeemed through this partnership
* **Actions**: Click the eye icon to view the individual partnership page
You can search for specific partners using the search field, and export the current view as a CSV file using the Export View button.
# Campaign Settings Page
Source: https://docs.withbenji.com/pilot/campaign
Control all of your campaign settings
The Campaign Builder walks you through 4 steps to configure a campaign: Details, Schedule, Flows, and Goals. Navigate between steps using the step indicator at the top of the modal. Campaigns are saved as drafts until you complete all steps and click Save Campaign.
## Step 1: Details
Set up your campaign name, type, description, and icon.
In this section you can view or configure the following parameters:
| Parameter | Description | Possible values |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| | The unique system-generated identifier for this campaign. This identifier will be used by the integrating partner when calling the Benji API to interact with the campaign. | A system-generated number. This value is **Read Only** |
| | A descriptive name for the campaign. This name will be displayed by default on all relevant Benji Drop-In Components related to this campaign | |
| | A description for this campaign. | |
| | An image to associate with this specific campaign | A JPG, JPEG, PNG or SVG image |
### Campaign Type
In this section you can configure the distinct campaign type for this campaign.
![Campaign Type]()
The Benji Platform supports 4 different campaign types:
* **Earn Points**: A campaign that, once triggered and if the configured conditions are met, distributes points to the connected user based on the base points distribution amount and any multipliers associated with the specific connected user.
* **Redeem**: A campaign that, once triggered and if the configured conditions are met, allows the connected member to redeem points to use to purchase items (or partial items) on the partner's online store.
* **Transfer**: A campaign that allows connected members to transfer points between their loyalty program account and a partner's program. Operators configure a transfer conversion rate and transfer increments so members transfer in set multiples (for example, 1,000 points at a time).
* **Connect Only**: A status sharing only campaign, meant to connect member data between your and your partner's accounts. In this campaign type there is no movement of points to or from members.
## Step 2: Schedule
Set when the campaign goes live.
| Parameter | Description | Possible values |
| :------------------ | :------------------------------------------------------- | :--------------------------------------- |
| **Start Date** date | The date the campaign activates. | A valid future date |
| **End Date** date | The date the campaign automatically ends. Not mandatory. | A valid future date after the start date |
Note that an end date is not mandatory. Campaigns without an end date will be evergreen until paused.
## Step 3: Flows
Set who earns, how they earn, and what they earn for your campaign.
A campaign can have multiple flows. Each flow defines a separate trigger and its associated configuration. Use the left sidebar to add and switch between flows. Each flow consists of the following configurable sections:
### Campaign Trigger
The trigger is the user action that qualifies a member for the campaign. Once a trigger fires, the Benji Platform triggers a rule engine to validate the conditions associated with the flow, and distributes rewards if all conditions are met.
![title]()
The following trigger types are supported:
* **Spend Per Dollar**: Triggered on a transaction event on the partner's store.
* **Registration**: Triggered when a member registers on the partner store and connects their account through the Benji platform to your loyalty program.
* **Customer Referral**: Triggered when a connected member makes a successful referral on the partner store.
* **Custom Action**: A custom action that can be triggered from anywhere on the partner's store. This is meant for use cases that are not yet natively supported by the platform and provides flexibility to create any type of campaign using Benji's APIs.
Triggers are especially useful when used in conjunction with Benji Drop-In components. The drop-in components can automatically render on the partner's online store based on these triggers and their respective placement.
* **Points per dollar spent**: This numeric value represents the base value of a transaction with your points. For Earn type campaigns, this represents the base value of how many reward points the connected member will be earning for every dollar spent. For Redeem type campaigns, this value represents the base amount of dollars each reward point is worth on the partner's store. This value will not be displayed for Connect Only type campaigns.
### Campaign Actions
In this section you can configure the base actions that will occur when a trigger happens and the relevant conditions are met.
![title]()
You can configure multiple actions per campaign.
A common example of a campaign with multiple actions is receiving rewards from both partners. For instance, earn 2 reward points from Partner A and 3 reward points from Partner B for every transaction.
For each action, you can specify the action itself, which partner controls the action (if applicable), and the **base** conversion rate of the action:
When configuring an action, you will only be able to set your own organization as the owner of the action. If there is another partner, they will be able to do the same. The actions owned by the other partner will be visible in read-only mode on your account.
**Action**
Possible values of actions to perform:
* **Award Points/Redeem Points**: Depending on whether the campaign is an Earn or Redeem type campaign
* **Award Cashback**: If applicable and configured in your settings, enables earning cashback for a trigger on the user's account.
**Partner**
The partner owning this action. This will be automatically filled in based on who is editing/creating the campaign.
**Conversion Rate**
The base value of conversion of the action:
* **Reward Distribution Value**: A number representing the value of the conversion (e.g. **3 reward points per dollar spent**)
The conversion rate configured in this section is the **base** conversion rate. Any configured multipliers will take effect based on the conversion rates defined in this section.
### Campaign Conditions
In this section you can configure the conditions associated with a valid campaign trigger. When a trigger is met, the Benji Platform will validate the conditions configured on the campaign, and will approve and initiate the campaign transaction only if the conditions are met.
![Screenshot 2026 07 28 At 5 47 28 PM]()
Conditions are evaluated at the point of the eligibility check, either when a member links their account or when a transaction occurs. When no conditions are configured, all members qualify.
#### Condition groups
Conditions are organized into groups. Each group contains one or more conditions and has its own logic type, set using the toggle in the top right corner of the group:
* **Any (OR)**: The member needs to meet at least one condition in the group
* **All (AND)**: The member needs to meet every condition in the group
The description on the left side of the group updates to reflect the active logic. New groups default to Any (OR).
The first condition in a group is preceded by a When label. Each condition after it is preceded by an and or or label matching the group's logic type.
You can configure any number of groups. Groups always combine with AND logic at the top level, meaning a member needs to satisfy every group to qualify.
To build your logic, use Add Condition inside a group to add a row to that group, and Add Group below the groups to add a new group. The delete control on a row removes that condition. Removing the last condition in a group removes the group.
For each condition, you can specify the attribute, an operator, and a value. The following attributes and their respective operators and values are supported:
**Customer Geography**
Will only be valid if the user meets the geographical condition.
* **Operators**: **Is In** or **Is Not In**
* **Values**: Countries, US cities
**Customer Total Spend**
Will only be valid if the user has exceeded a total spend amount since they connected their account. For instance, if the campaign distributes a certain amount of reward points after the member has purchased over \$1000 in goods.
* **Operators**: **Greater Than**
* **Values**: Numeric amount
**Transaction Basket Size**
Will only be valid if a member is making a purchase over or under a certain amount.
* **Operators**: **Greater Than**, **Less Than**
* **Values**: Numeric amount
**Time Elapsed**
Will only be valid if a defined amount of time has passed since they connected their accounts.
* **Operators**: **Greater Than**, **Less Than**
* **Values**: A time period (e.g. 1 day, 2 weeks, 3 months, etc.)
**Custom Attributes**
Will only be valid if the member's custom attribute value meets the condition. Custom attributes are configured on the Partner Settings page and are listed by their attribute name.
* **Operators**: **Is In** or **Is Not In**
* **Values**: The configured values for that attribute
### Campaign Multipliers
In this section you can configure certain conditions under which a certain member would get a multiplier boost on their earned or redeemed rewards for a specific transaction.
For **Earn** type campaigns, this means the member, if the condition is met, will earn a multiplier on the base Points earned per dollar variable configured in the triggers section.
For **Redeem** type campaigns, this means the member will get a multiplier on the conversion rate per dollar defined in the triggers section above.
![multipliers]()
You can configure a limitless number of multipliers per campaign. For each multiplier, you can specify the multiplier amount, a customer attribute to validate (the condition) and the corresponding value of the customer attribute to validate. The following customer attributes are supported:
**Customer Status**
Will only be valid if the user is of a certain status.
* **Operators**: **Is In** or **Is Not In**
* **Values**: Any one of your loyalty programs' status tiers configured in the Benji Platform.
**Variable Attributes**
You can create multipliers based on any attribute returned as part of the Benji Platform integration with your platform. A typical example would be Card Member status, # of total rewards earned throughout their membership, etc.
* **Operators**: **Is In** or **Is Not In**
* **Values**: Configurable values based on the variable attribute possible values configured in the settings section of the Benji Platform.
### Campaign Limits
In this section you can configure limits to control how frequently members can qualify for rewards and the maximum value they can earn or redeem.
![limits]()
Limits set boundaries on transaction values, member qualification frequency, and total rewards. You can set transaction minimums to ensure meaningful engagement, cap total rewards per user, or limit qualification frequency to control the pacing of your campaigns.
You can configure multiple limits per campaign. The following limit types are supported:
**Transaction Limits**
Controls the minimum or maximum value allowed per individual transaction.
* **Operators**: Minimum, Maximum
* **Values**: Numeric amount (points or dollars depending on campaign type)
**User Limits**
Controls the maximum number of qualifying events or total points a user can accumulate within a specified time period.
* **Operators**: Maximum
* **Units**: Qualifying events or Points
* **Values**: Numeric amount
* **Time Period:** Per day, per week, per month, per quarter, per year, or lifetime
## Step 4: Goals
Set primary goals for your campaign. Benji will track progress against these goals, which you can view in the Analytics page when filtering by campaign.
![title]()
The Benji platform supports setting the following built-in goals:
**Registrations**
Specifies a goal of reaching or exceeding a certain number of new registrations as a result of the partnership
**Points Earned**
Specifies a number representing the total amount of reward points earned throughout the campaign
**Points Redeemed**
Specifies a number representing the total amount of reward points redeemed throughout the campaign
# Campaigns Page
Source: https://docs.withbenji.com/pilot/campaigns
A view of all the campaigns configured for a specific partnership
![]()
## Overview
The campaigns page provides a list view of all the currently configured campaigns under a specific partnership. Each campaign line item on the homepage shows you the following information:
| Parameter | Description | Possible values |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **ID** | The unique system-generated identifier for this campaign. This identifier will be used by the integrating partner when calling the Benji API to interact with the campaign. | A system-generated number |
| **Campaign Name** | This field shows 2 values: The type of campaign and the descriptive name assigned to this field. | For campaign type:
**Earn**
**Redeem**
**Transfer**
**Connect Only** |
| **Trigger** | The trigger action associated with this campaign. | **Spend per Dollar** - for campaigns triggered by a user transaction
**Registration** - for campaigns triggered by a user registration
**Customer Referral** - for a campaign triggered by a user referring another user to the partner
**Custom Action** - An action not supported natively by Benji. The partner will own the placement and rendering of the components for these action triggers |
| **Conditions and Multipliers** | All of the conditions and multipliers configured under this campaign | |
| **Status** | The running status of the Campaign | **Active** - a campaign that is currently live
**Scheduled** - a campaign scheduled for a future date
**Draft** - a campaign that has not yet been approved. |
| **Actions** | A list of actions to perform on the specific campaign | **Edit** - will open up the campaign edit modal
**Duplicate** - duplicates this campaign with all of its settings to a new campaign in **Draft** mode
**Approve** - initiates the campaign approval flow
**Delete** - will popup a confirmation modal to approve deletion of this campaign. |
## Navigation
The campaigns page is accessed by clicking on a partnership tile on the [Partnerships Homepage](/pilot/partnerships).
The campaigns page supports the following navigation/actions on the top header:
* Switching between Campaigns and Partner details. The partner details section will display read-only basic information about the given partner.
* CTA to import campaign: Allows you to upload a campaign configuration from an XLSX template
* New campaign: Opens the new/edit campaign modal
When creating a new campaign, the configuration modal uses a top tab navigation to step through each section. Sections include details, schedule, flows, and goals.
## Campaign Templates
Campaign templates streamline campaign creation by letting you reuse configurations across multiple partnerships and save time on setup.
* **Create campaigns using templates and customize.** When creating a new campaign, click "Import Campaign" to use an existing template that will prepopulate all your campaign settings based on the template configuration. You can modify any settings before saving the campaign to match your specific requirements.
* **Turn existing campaigns into reusable templates.** After creating a campaign, you can convert it into a template by clicking the "Actions" menu on the campaigns page for that campaign and selecting "Create Template". This template becomes available for use with any partner.
* **Access all your templates in one place.** View and manage all campaign templates by navigating to "Partner Settings" and clicking "Campaign Templates".
## Campaign Components
Once you've created a campaign, campaign components are automatically generated to promote across user touchpoints. Navigate to "Components" on the campaign page to access and customize:
* **Landing pages** direct users to your partnership and prompt them to link their reward accounts. You can customize the theme, background image, text, button color, and button text. Additionally, you can select which active campaign(s) to highlight on the landing page. You can also configure an inactive state for the landing page, displayed when a campaign has ended. Toggle the inactive state on in the landing page settings and set a custom title and intro message. Configuring this ensures members see a clean, branded experience rather than a broken page after a campaign concludes.
* **Connect buttons** can be added directly to a partner experience to direct users to link their accounts using the Benji Connect SDK.
## Transactional Emails
Benji can be configured to send campaign transactional emails to users, or you can listen for webhooks to configure your own transactional email system.
* **Account linking confirmation emails** highlight partnership benefits and showcase active campaigns.
* **Earn campaign confirmation emails** notify users when an earn transaction has been completed, providing transaction details and driving engagement with your rewards program.
**Use Benji's built-in email system or integrate with your own.** If you prefer to send transactional emails using your own system, [webhooks](/api-reference/webhooks/overview) allow you to receive real-time updates on users, campaigns and reward transactions.
# Key Benji Concepts
Source: https://docs.withbenji.com/pilot/concepts
Overview of key components in the Benji Ecosystem
Throughout this documentation, you will come across the following key concepts:
* **Partner**: The company you are forming the partnership with, whether through a direct partnership or through Benji Marketplace.
* **Direct**: A direct partnership, sourced and secured by you and built through the Benji Platform. This is a partnership that is exclusive to your brand. Your direct partners will not be a part of the Benji Marketplace network.
* **Marketplace**: A non-exclusive partnership formed with a partner on the Benji Marketplace.
* **Campaign**: A single campaign instance running under a specific partnership. A single direct partnership can have multiple campaigns configured and running, for instance:
* A campaign to **earn reward points for a new user registration**.
* A campaign to **earn points for every transaction** based on a defined conversion rate, conditions and multipliers.
* A campaign to allow users to **redeem their reward points to make purchases** based on a defined conversion rate.
* **Campaign Flow**: A flow is the core configuration unit within a campaign. Each campaign can have one or more flows, and each flow defines a trigger, actions, conditions, multipliers, and limits that together determine who qualifies, how they qualify, and what they receive. Multiple flows within a campaign allow you to configure different reward structures for different trigger types under the same partnership.
# Transactions
Source: https://docs.withbenji.com/pilot/customer_activity
A view of all your user activity on the Benji Platform, allowing you to drill into a specific member rewards usage across all your connected partners and campaigns
The Transactions page displays all reward activity across your partnerships. You can search for specific members, filter by transaction type, partner, and status, and view detailed information about each transaction.
![Screenshot 2026 07 28 At 5 37 53 PM]()
### Filters and Search
**Date Range**
Select a custom date range to view transactions for a specific time period.
**Member ID**
Search for transactions by entering a member's loyalty program ID.
**Member Name**
Search for transactions by entering a member's name.
**Filter by Type**
Filter transactions by activity type:
* **All**: View all transaction types
* **Earn**: View only point earning transactions
* **Redeem**: View only point redemption transactions
* **Transfer**: View only point transfer transactions
**Filter by Partner**
Select specific partners to view their transactions, or select All to view transactions across all partners.
**Filter by Status**
Filter transactions by their current status.
**Filter by Confidence**
Filter transactions by fraud confidence band: Low, Medium, or High.
**Clear Filters**
Reset all filters to their default state.
### Transaction Table
The table displays detailed information for each transaction and can be sorted by column:
* **Date**: The date the transaction occurred
* **Time**: The time the transaction occurred
* **Member Name**: The name of the member
* **Partner Name**: The partner associated with the transaction
* **Type**: Transaction type (Earn, Redeem, or Transfer)
* **Reward Amount**: The number of points involved in the transaction
* **Transaction**: The dollar value of the transaction
* **Confidence**: A color coded fraud confidence indicator for the transaction
* **Status**: Current status of the transaction (Completed, Pending, etc.)
* **Actions**: Click the menu icon to access transaction actions
### Confidence
Every reward transaction is automatically evaluated for fraud risk and assigned a confidence score, shown as a color coded badge:
* **Green**: High confidence the transaction is legitimate
* **Yellow**: Suspicious, warrants review
* **Red**: High likelihood of fraud
While a partnership's fraud models are still calibrating, its transactions show a gray badge with a clock icon and a preliminary score instead of the usual colored badge. Reviewing these transactions helps improve model accuracy. Once calibration is complete, transactions return to the normal colored badges.
Once a transaction has been reviewed, a colored pip overlays its Confidence badge: green for reviewed as legitimate, red for reviewed as fraud. Reviewed rows also carry a subtle background tint.
### Fraud Alert Emails
You can subscribe to email notifications for flagged transactions from your profile. Fraud alert emails are off by default. When you enable them, choose which transactions trigger an email:
* **High Risk Only**: Only transactions with high fraud likelihood
* **High Risk and Suspicious**: High risk and suspicious transactions
* **All Transactions**: Every assessed transaction
Each user manages their own subscription, so different users on the same account can choose different thresholds or opt out entirely.
### Transaction Actions
**Reverse**
Reverses the transaction. For Earn transactions, this removes the points from the member's account. For Redeem transactions, this refunds the points back to the member. For Transfer transactions, this reverses the point movement in both the source and destination accounts.
### Transaction Detail Page
![Screenshot 2026 07 28 At 5 35 27 PM]()
See Details opens a dedicated page for the transaction, laid out in two columns. The left column holds the transaction details and, when flagged, the fraud assessment. The right column holds the assessment summary, fraud score, disposition, and actions.
**Fraud Assessment**
For flagged transactions, this section lists each detection model that contributed a signal and its reasoning:
* **Transaction Frequency**: Abnormally high number of transactions in a short window
* **Transaction Size**: Amount deviates from the partnership's historical norms
* **IP Analysis**: Multiple distinct IP addresses for the same member in a short window
* **Velocity**: Rapid, successive transactions from the same member
* **Amount Anomaly**: Deviates from the member's own spending pattern
* **Account Takeover**: Multiple accounts share a device, with elevated risk on the first earn from that device
Shown only for transactions that have a fraud assessment.
**Disposition**
Mark a transaction as Legitimate or Fraud. Once set, the disposition can be switched to the other but cannot be cleared.
**Actions**
* **Reverse Transaction**: Voids the transaction and undoes the points movement
* **Block Member**: Suspends the member from all future program activity
Each requires an inline confirmation before it executes.
### Export
Click the Export All button to download all transactions matching your current filters as a CSV file.
# Pilot Dashboard Overview
Source: https://docs.withbenji.com/pilot/dashboard
An overview of your partnership statuses, traction and activity
![Dashboard]()
## Overview
The dashboard section gives you an overview of all your partnerships' overall activities and traction, giving you a single point to track the health of all your partnerships and campaigns at a glance. The dashboard consists of the following sections:
## Sections
### Activity Chart
This section consists of a single chart, that is date range customizable, to see the overall activities across all your campaigns. The line indicators indicate an action triggered by the different campaigns (e.g. Earn or Redeem rewards) and allow you to see aggregated campaign traction over a period of time.
### Partnerships Breakdown
This section provides you data on your currently running partnerships and campaigns, and consists of the following data points:
* Number of active and scheduled partners
* Number of active and scheduled campaigns
* Total amount of points earned through the Benji Platform across all your active, scheduled and completed campaigns
* Total amount of points redeemed through the Benji Platform across all your active, scheduled and completed campaigns
Note that only active, scheduled, or completed partnerships will be aggregated here. Draft campaigns will not be displayed until they are confirmed.
### Highlights
This section provides you with highlights across your top running partnerships and campaigns:
* Breakdown of activity between [Direct](/pilot/concepts) and [Marketplace](/pilot/concepts) partnerships
* Your top 3 performing campaigns and their overall activity, with an indicator of change in traction during the last week (e.g. increase/decrease in traffic percentage)
### Support
This section provides you with quick links to get help and contact Benji Support:
* Quick link to the Benji Help Center to answer any common questions
* Quick link to contact Benji Support on a chat interface
# Developer
Source: https://docs.withbenji.com/pilot/developer
Manage API authentication, webhook subscriptions, and platform integrations
The Developer Settings page provides tools for integrating with the Benji Platform programmatically. You can generate API keys for authentication, configure webhook endpoints to receive real-time updates, manage IP whitelisting, and connect to pre-built integrations.
![Developer]()
### API Tokens
Generate and manage API keys to authenticate your requests to the Benji Platform API.
**Add Key**
Click the Add Key button to generate a new API key. You'll be prompted to enter a name for the key to identify it. When created, the full key value will be displayed once. Copy and store it securely, as you won't be able to view the complete key again. To access the key value later, you'll need to generate a new key.
**API Keys Table**
Each API key displays:
* **Key Name**: The identifier for the key
* **Key Value**: The API key value (masked for security)
* **Actions**:
* **Edit**: Modify the key name
* **Delete**: Remove the API key (this will invalidate it immediately)
**Important**: Store your API keys securely when first generated. They provide access to your Benji Platform account and should never be shared publicly or committed to version control. If you delete a key, update any applications using it immediately to prevent authentication failures. After creating keys, they can be used with the [Benji API](/api-reference/authentication).
### Webhooks
Configure webhook endpoints to receive real-time notifications about users, campaigns, and transactions. Learn more about webhook implementation in the [Webhooks documentation](/api-reference/webhooks/overview).
**Add Webhook**
Click the Add Webhook button to create a new webhook subscription. You'll need to provide:
* **Endpoint URL**: The URL where Benji will send webhook notifications
* **Entity Type**: Select USER or TRANSACTION to specify which type of events to receive
* **Event Name**: Select the specific event you want to subscribe to (options vary based on entity type)
* **Active**: Toggle to enable or disable the webhook
**Webhooks Table**
Each webhook displays:
* **Endpoint URL**: The destination for webhook notifications
* **Entity Type**: The type of entity (User or Transaction)
* **Event Name**: The specific event being monitored
* **Status**: Whether the webhook is active or inactive
* **Salt**: The authentication salt used for webhook [signature verification](/api-reference/webhooks/overview#webhook-authentication)
* **Actions**: Edit webhook configuration, delete the webhook, or send a test webhook
**Entity Types and Events**
* **USER**: user\_partner\_connected
* **TRANSACTION**: transaction\_authenticated, transaction\_created, transaction\_status\_updated
For detailed information about webhook authentication and payload formats, click the info icon next to the Add Webhook button.
### IP Whitelist
The IP Whitelist tab allows you to request that specific IP addresses be whitelisted for your Benji Platform integration. This is typically used to restrict API access to known server IPs and improve the security of your integration.
**Requesting an IP Whitelist**
Click the Add IP button and enter the IP address you want to whitelist. Once submitted, the request is sent to the Benji team for review. You will be notified once the IP has been approved and added.
### Integrations
Connect your Benji account to pre-built integrations with third-party platforms and services. Available integrations streamline common workflows and data synchronization tasks.
# Finance Page
Source: https://docs.withbenji.com/pilot/finance
A page displaying all your past, upcoming and due Benji invoices information, with the ability to get a per transaction breakdown for each invoice
![title]()
# The Benji Platform
Source: https://docs.withbenji.com/pilot/overview
Benji is your one-stop shop to build, manage, and expand all of your Loyalty Partnerships
Benji provides your team with all the tools they need to set up new and existing partnerships, leveraging Benji's platform to easily configure, manage, experiment, and track even the most complex partnerships.
## Why Benji?
### An all-in-one solution for all your partnership needs
* **Platform**: Build, manage, and expand your partnerships using Benji's proprietary rule engine logic to handle even the most complex partnership campaigns.
* **Developer Experience**: Never worry about another integration again. Once integrated with the Benji APIs, Benji handles all partner integration using Benji's set of best-of-breed APIs, SDKs and drop-in components.
* **Expand to new partnerships**: Using Benji's robust Marketplace, get instant access to unlimited partners to expand on your partnerships with a click of a button.
* **Insights**: Get rid of ad hoc dashboards and gain valuable insights from your current and past campaigns across all your partners.
Build, Manage and Track all your partnerships under a single dashboard.
Enable your users to seamlessly connect to their loyalty programs with a few lines of code.
A rich and full API for you to trigger campaigns, get notified on reward activity and extract meaningful data and insights from the Benji Platform.
# Partnerships Homepage
Source: https://docs.withbenji.com/pilot/partnerships
A bird's-eye view of all your active, scheduled and draft partnerships
![Partnerships]()
### Overview
The partnerships homepage gives you a view of all your active, scheduled, and draft partnerships. Each partnership object on the homepage shows you the following information:
| Parameter | Description | Possible values |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status** | The running status of the Partnership | **Active** for partnerships that have a campaign that is currently live, **Scheduled** for partnerships that have a campaign scheduled for a future date, **Draft** for partnerships that have not yet been approved. |
| **Partner Name** | The name of the partner | |
| **Partnership Type** | Whether this is a [Direct](/pilot/concepts) or [Marketplace](/pilot/concepts) originated partnership | **Direct** or **Marketplace** |
| **Date Launched/Scheduled Date** | The launch date of the partnership. For partnerships with multiple running campaigns, this will be the earliest launch date of all campaigns. | N/A for WIP partnerships, any date in the past for active partnerships or any date in the future for scheduled partnerships |
| **Campaigns** | Total number of active, scheduled or draft campaigns in the partnership | |
| **Points Earned** | The total points distributed to members as part of this partnership | Number representing the total number of rewards distributed as part of this partnership, or N/A if this partnership does not have any Earn type campaigns configured |
| **Points Redeemed** | The total points redeemed by members as part of this partnership | Number representing the total number of rewards redeemed as part of this partnership, or N/A if this partnership does not have any Redeem type campaigns configured |
## Navigation
The partnerships homepage is accessed by clicking on the Partnerships item in the Pilot sidebar.
The partnerships homepage supports the following navigation/view actions on the top header:
* Switching between All, Direct, Marketplace partnerships for quick partnership filtering
* Switching between List and Card View. Note that both the list view and card tile view display the same information.
* Call to Action button to create a new partnership campaign.
* Clicking on a tile or line item will navigate you to the [partnerships campaigns page](/pilot/campaigns).
# Partner Settings Page
Source: https://docs.withbenji.com/pilot/settings
A page to set and view your account settings and configurations
Partner Settings allows you to configure your loyalty program's details including branding, tier structure, custom member attributes, and custom campaign triggers.
![Settings]()
### General Settings
Configure your basic program information and branding.
**Partner Details**
Click Edit to update your branding:
* **Logo (Full Size)**: Your loyalty program's full logo (minimum 500px, PNG or SVG)
* **Logo (Square Icon)**: Square icon version (minimum 250px x 250px, PNG or SVG)
* **Partner Name**: Display name for your loyalty program
**Loyalty Program**
Click Edit to update your loyalty program details:
* **Loyalty Program Name**: Name of your loyalty program
* **Loyalty Currency**: The currency used for rewards (e.g., Points, Miles)
### Loyalty Tiers & Attributes
Define your loyalty program's tier structure and custom member attributes.
**Loyalty Tiers**
Define your loyalty program's tier structure. Click New Tier to add a tier:
* **Your ID**: The tier identifier in your system
* **Status Tier Name**: Display name for the tier
* **Base Tier**: Check this box to set as the base tier
**Custom Attributes**
Custom attributes capture additional information about your members that can be used in campaign conditions and multipliers. For example, you might create an attribute to track cardholder status, membership level, or a renewal date.
Click New Attribute to create a custom attribute:
* **Attribute Name**: Display name for the attribute
* **Your ID**: The attribute identifier used in your system
* **Attribute Type**: Data type for the attribute
The following attribute types are supported:
* **Text**: A single string value. Can optionally be restricted to a defined list of allowed values, each with its own display label, so a raw value received from your system can be shown as a friendly label.
* **Number**: An integer or decimal value. Supports comparison operators such as equals, greater than, less than, and between when used in campaigns.
* **Boolean**: A true or false value, with optional custom labels for the true and false states.
* **Date**: A calendar date value. Supports date based comparisons when used in campaigns.
* **Multi Value**: Holds more than one value at once for a given member, chosen from a defined list of allowed values that you configure up front.
Once created, an attribute is available in the campaign builder as a selectable field in Conditions and Multipliers, alongside native fields like Time Elapsed, Geography, and Basket Size. Attribute values are populated through the Benji API and can be manually edited on a member's profile.
An attribute belongs to the partner that defines it and is visible in any partnership that partner participates in. When both partners in a partnership define attributes, each is shown separately and labeled by its source, so a campaign condition always references a specific source attribute.
### Custom Triggers
Configure custom triggers for use in campaigns with the Custom Action trigger type. Custom triggers provide flexibility to create campaigns for use cases not covered by standard trigger types, for example, Spend Per Dollar, Registration, or Customer Referral.
Click New Trigger to create a custom trigger:
* **Name**: Display name for the trigger
* **Trigger Value**: The identifier sent when triggering the campaign via API
* **Description**: Description of when this trigger should be used
**Instructions to Send Events**
Click "Instructions to Send Events" to view the JSON payload format for sending custom trigger events via the Benji API. The payload shows the trigger\_name and user\_id fields required to activate campaigns using this trigger.
### Redemption Codes
The Redemption Codes tab lets you manage a pool of pre-generated codes for a partner. It appears only for partners that have an eligible product. If you do not see the tab, the partner has no eligible product associated.
The tab shows all uploaded codes in a table with the following columns:
* **Date Uploaded**: When the code was added
* **Product Variant**: The product variant the code belongs to
* **Redemption Code**: The code value
* **Status**: The current state of the code
* **Action**: Per row actions, described below
**Filtering and search**
Narrow the list using search by code, an upload date range, a product variant filter, and a status filter. Use Clear Filters to reset all of them.
**Uploading codes**
Click Upload to add codes in bulk from a file. Uploads are processed in the background. When processing finishes, the result summary shows the total number of rows, how many new codes were added, and an error count. Any rows that failed are listed individually with the row number, the code, and the reason. Duplicate codes already present in the pool are reported as errors with a duplicate reason rather than being added again.
**Viewing and deleting codes**
Select a redeemed code to view its details. Available codes can be deleted individually from the row action, or in bulk by selecting multiple rows with the checkboxes and choosing Delete Selected.
Uploading and deleting codes are permissioned actions. View-only users can see the codes and their status but cannot upload or delete. In a partnership context these follow partnership edit permissions, and in Partner Settings they follow partner settings edit permissions.
### Users
Manage administrator access for your loyalty program. Click Invite New User to grant users access to manage campaigns and settings for your program.
### Allowed Collaborators
Account Admins control which email addresses can be invited as collaborators on partnerships. This is managed from Partner Settings.
* **Email domains**: Add approved domains. Any email at an approved domain can be invited.
* **Individual email addresses**: Add specific pre-approved addresses for exceptions, such as a consultant using a personal email.
Only Account Admins can add, edit, or remove approved domains and addresses. When someone invites a new collaborator, their email must either belong to an approved domain or match a pre-approved address. Users who already exist in either company's account can be added regardless of their email domain.
### Campaign Templates
Create reusable campaign configurations that can be quickly deployed across multiple campaigns. Templates allow you to standardize campaign structures for common use cases.
Click Add New Template to open the campaign editor and create a template with pre-configured triggers, actions, conditions, and multipliers.
# Users & Permissions Page
Source: https://docs.withbenji.com/pilot/users
Manage platform administrators and loyalty program members
The Users page allows you to manage two types of users: Admin Users who access the Benji platform, and Members who have connected their loyalty program accounts to participate in your partnerships.
![Users]()
### Admin Users
Each admin user is assigned one or more roles that control what they can access and action within Pilot. All users have view-only access across the account by default. Roles add the ability to take actions on top of that baseline.
The following roles are available:
* **Admin**: Full access to all features and settings in Pilot, including user management. Admin must be assigned on its own.
* **Campaign Manager**: Create new partnerships and campaigns, and access the marketing section.
* **Support**: Reverse transactions, and block or unlink members.
* **Developer**: Access the developer section, manage API keys, and configure webhooks and integrations.
* **Member**: View-only access across the entire account. Member must be assigned on its own and is selected by default when inviting a new user.
A user can hold more than one role, with two restrictions: Admin must be assigned alone, Member must be assigned alone, and Campaign Manager, Support, and Developer can be combined in any mix. At least one role must always be assigned. Only Admins can assign or change roles, and changes take effect immediately.
**Invite New User**
Click the Invite New User button to send an invitation to a new administrator. They will receive an email with instructions to set up their account. Select a role for the user during the invitation flow.
**Admin User Actions**
* **Resend Invite**: Send a new invitation email to users with Invited status
* **Edit**: Modify the user's name
* **Delete**: Remove the user from your account
### Collaborators
Collaborators are users invited to access a specific partnership. Collaborator status grants edit access on that partnership beyond the view-only access every user already has.
All users at either company automatically have view-only access to the partnerships their company is connected to. On the partnerships list, each partnership shows a Collaborator badge if the user has edit access, or a View only badge if they do not. A view-only user can open the partnership and see all of its content, but the actions are disabled until they are added as a collaborator.
Collaborators are invited from the partnership page. Each collaborator is assigned one of the following roles:
* **Owner**: Full control over the partnership, including managing all other collaborators and transferring ownership. There is only one Owner per partnership, and the creator of the partnership is the Owner by default.
* **Admin**: Edit anything in the partnership and manage collaborators, except the Owner. Cannot transfer ownership.
* **Campaign Manager**: Create, edit, and launch campaigns. Cannot manage collaborators.
* **Marketing**: Edit partnership components and landing pages. Cannot create or edit campaigns.
Assigning the Owner role to another collaborator transfers ownership. The current Owner becomes an Admin, and the change requires an explicit confirmation.
**Collaborator Actions**
* **Edit**: Modify the collaborator's name or role
* **Delete**: Remove the collaborator's access to the partnership
### Members
The Members tab is available to Admin users and displays all loyalty program members who have connected their accounts through your partnerships.
**Member Actions**
* **View**: Open the detailed member profile showing transaction history and connection details
* **Unlink**: Disconnect the member's account from a specific partner (typically used for troubleshooting)
* **Block**: Prevent the member from participating in campaigns
### Member Profile
Clicking View on a member opens their detailed profile, which includes:
**Summary Metrics**
* **Transactions**: Total number of transactions
* **Points Earned**: Total points earned across all partnerships
* **Points Redeemed**: Total points redeemed across all partnerships
**User Details**
Displays the member's basic information including name, loyalty program member number, status, and email.
**Custom Attributes**
Displays the member's custom attribute values that are visible to this partner. Values are populated through the Benji API. You can manually edit a value directly on the profile, mainly for support cases. A manually edited value is marked as overridden and is no longer updated by API refreshes until the override is cleared. The profile shows whether each value is synced from the API or manually overridden.
**Connections**
Shows all partnerships the member is connected to, including the partner name, connection date, and member ID for each partner.
**Transactions Tab**
View the member's complete transaction history across all partnerships.