PAR Retail Stuzo
Sync loyalty segment memberships and track customer events in PAR Retail Stuzo Open Commerce. Zeotap connects to the Open Commerce platform to keep your fuel and convenience retail loyalty programs enriched with warehouse-driven audiences and behavioral data.
Prerequisites
- A PAR Retail Stuzo Open Commerce account with API access enabled
- An API key assigned by Open Commerce to identify your application
- A client ID and client secret for OAuth token generation (provided by your PAR Retail Stuzo account team)
- For segment syncs: the segment ID of the target segment in Open Commerce
- For event syncs: a defined event name/type in your Open Commerce configuration
Authentication
Client Credentials
PAR Retail Stuzo uses a combination of an API key and OAuth 2.0 client credentials for authentication.
- Contact your PAR Retail Stuzo account team to obtain your API Key, Client ID, and Client Secret
- Access the Open Commerce Command Center to verify your credentials and review the API documentation
- In Zeotap, navigate to Destinations and click Add Destination
- Select PAR Retail Stuzo from the destination list
- Enter your API Key in the API Key field
- Enter your Client ID and Client Secret in the corresponding fields
- Click Test Connection to verify the credentials are valid
Zeotap automatically obtains and refreshes OAuth access tokens using your client credentials. The API key is sent as an X-Api-Key header with every request.
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| API Base URL | Text | Yes | The PAR Retail Stuzo Open Commerce API base URL for your environment (e.g., https://api.opencommerce.stuzo.com) |
Target Settings
| Field | Type | Required | Description |
|---|---|---|---|
| Object Type | Select | Yes | The type of data to sync: Segments (manage loyalty segment memberships) or Events (track customer events) |
| Segment ID | Text | Yes (for Segments) | The identifier of the segment in Open Commerce to add or remove members from |
| Event Name | Text | Yes (for Events) | The name of the event type to record in Open Commerce (e.g., purchase, store_visit) |
Supported Operations
Sync Modes
| Mode | Supported |
|---|---|
| Upsert | — |
| Insert | Yes |
| Update | — |
| Mirror | — |
Insert mode is used for sending events to Open Commerce. Each event row is recorded as a new event entry.
Audience Sync Modes
| Mode | Supported |
|---|---|
| Add | Yes |
| Remove | Yes |
| Mirror | Yes |
| Upsert | — |
Audience sync modes manage membership in Open Commerce segments. Add enrolls members into the segment, Remove removes them, and Mirror ensures the segment membership exactly matches your source audience (adding new members and removing those no longer present).
Features
- Field Mapping: Yes
- Schema Introspection: No
Required Mapping Fields
| Field | Description |
|---|---|
membership_uuid | The Open Commerce membership UUID that uniquely identifies the loyalty program member. This is the primary key used to match rows to members in PAR Retail Stuzo. |
Default Destination Fields
Segments
| Field | Type | Description |
|---|---|---|
membership_uuid | string | Open Commerce membership UUID |
email | string | Member email address |
first_name | string | Member first name |
last_name | string | Member last name |
phone | string | Member phone number |
Events
| Field | Type | Description |
|---|---|---|
membership_uuid | string | Open Commerce membership UUID |
event_id | string | A unique identifier for the event (used for deduplication) |
event_timestamp | string | ISO 8601 timestamp of when the event occurred |
event_properties | object | A JSON object containing additional event attributes |
How It Works
-
Authentication: Zeotap obtains an OAuth 2.0 access token using your client credentials (client ID and client secret). The token is automatically refreshed before expiry. Every API request also includes your API key in the
X-Api-Keyheader. -
Segment Sync: For audience syncs, Zeotap sends membership add or remove actions to the Open Commerce segments API. Members are identified by their
membership_uuid. Rows are sent in batches of up to 100 members per request. -
Event Sync: For event syncs, Zeotap posts event records to the Open Commerce events API. Each event includes the member’s
membership_uuid, the configured event name, and any mapped event properties. Events are batched in groups of up to 100 per request. -
Mirror Mode: When using mirror mode for audience syncs, Zeotap compares the current segment membership with your source audience. New members are added and members no longer in the source are removed, ensuring an exact match.
-
Error Handling: The Open Commerce API may reject an entire batch if a single entry is invalid. Failed batches are reported with specific error messages. Transient errors (rate limits, server errors) are retried automatically with exponential backoff.
Rate Limits
PAR Retail Stuzo Open Commerce enforces rate limits on API requests. Specific limits depend on your account tier and are configured by the PAR Retail Stuzo team. Zeotap handles rate limiting by:
- Sending rows in batches of 100 to stay within payload size limits
- Retrying requests that receive a 429 (Too Many Requests) response with exponential backoff
- Respecting
Retry-Afterheaders when present
Contact your PAR Retail Stuzo account team for details on your specific rate limit allocation.
Best Practices
- Use stable membership UUIDs as the primary identifier. Avoid using mutable values like email addresses for matching, as they may change over time.
- Set up a unique event ID for event syncs to enable deduplication. This prevents duplicate events if a sync is retried.
- Test with a small audience first before syncing large segments to verify field mapping and segment configuration are correct.
- Schedule syncs during off-peak hours to minimize the impact on your Open Commerce API rate limits.
- Use mirror mode for full audience management when you want Zeotap to be the source of truth for segment membership. Use add/remove modes when integrating with segments managed by multiple systems.
- Keep event properties compact by mapping only the attributes needed for your loyalty program rules and reporting.
Troubleshooting
Authentication failed: invalid credentials
Verify that your API key, client ID, and client secret are correct. These credentials are provided by your PAR Retail Stuzo account team. If you recently rotated credentials, update them in the Zeotap destination configuration.
Segment not found
The segment ID in your target settings does not match a valid segment in Open Commerce. Log into the Open Commerce Command Center and verify the segment ID. Segment IDs are case-sensitive.
Membership UUID not found
The membership_uuid value in your data does not match any member in the Open Commerce loyalty program. Verify that the UUID values in your source data correspond to active memberships. Members who have been deactivated or deleted cannot be added to segments.
Batch rejected due to invalid entry
Open Commerce may reject an entire batch if one entry is invalid. Check the error details for the specific invalid entry. Common causes include malformed UUIDs, missing required fields, or data type mismatches. The failed batch will be reported in the sync run details.
Rate limit exceeded (429 errors)
Zeotap automatically retries rate-limited requests with exponential backoff. If you see persistent rate limit errors, consider reducing your sync frequency or contacting PAR Retail Stuzo to increase your rate limit allocation.
Event deduplication failures
If duplicate events appear in Open Commerce, ensure you are mapping a truly unique event_id field. The event ID should be unique across all syncs, not just within a single batch. Consider using a composite key (e.g., membership UUID + timestamp + event type) if your source data does not have a natural unique identifier.
OAuth token refresh failed
If the OAuth token cannot be refreshed, Zeotap will retry the token request. Persistent failures may indicate that your client credentials have been revoked or expired. Contact your PAR Retail Stuzo account team to verify your OAuth configuration.
Connection timeout
If requests are timing out, verify that the API base URL is correct and accessible from your network. Check that there are no firewall rules or IP allowlist restrictions blocking Zeotap’s connections to the Open Commerce API.