PartnerStack

Sync partner ecosystem data to PartnerStack for partnership management, customer attribution, deal tracking, and revenue recording. Zeotap supports creating and updating customers, partnerships, deals, and transactions via the PartnerStack Vendor API.

Prerequisites

A PartnerStack vendor account with API access enabled
PartnerStack API keys (public key and secret key) from Settings > Integrations > PartnerStack API Keys
Appropriate permissions for the objects you plan to sync (customers, partnerships, deals, or transactions)

Authentication

PartnerStack uses API Key authentication via HTTP Basic Auth.

Log in to your PartnerStack vendor dashboard
Navigate to Settings > Integrations > PartnerStack API Keys
Copy your Public Key and Secret Key
In Zeotap, enter the Public Key and Secret Key when configuring the destination

PartnerStack provides separate test and production keys. Use test keys during development and switch to production keys before going live.

Configuration

No additional configuration fields are required beyond authentication.

Target Settings

Field	Type	Required	Description
Object Type	Select	Yes	The PartnerStack object to sync data to. Options: Customers, Partnerships, Deals, Transactions.

Supported Operations

Sync Modes

Mode	Supported	Notes
Insert	Yes	Creates new records in PartnerStack
Update	Yes	Updates existing customers and partnerships by key
Upsert	Yes	Creates or updates records based on key presence

Note: Transactions are append-only and only support the Insert sync mode. Deals support Insert and Upsert only; the Update mode is not currently wired up for deals in Zeotap.

Audience Sync Modes

Mode	Supported
Add	—
Remove	—
Mirror	—

PartnerStack does not have a list or audience membership concept, so audience sync modes are not supported.

Features

Field Mapping: Yes
Schema Introspection: No

Required Mapping Fields

Required fields vary by object type.

Customers

Destination Field	Type	Required	Description
`email`	String	Yes	Customer email address
`partner_key`	String	Yes	Key of the partner responsible for the customer

Partnerships

Destination Field	Type	Required	Description
`email`	String	Yes	Partner email address

Deals

Destination Field	Type	Required	Description
`group_key`	String	Yes	Unique key of the group for the deal’s partner
`account_name`	String	Yes	Name of the deal account
`amount`	Number	Yes	Deal amount in cents
`close_date`	String	Yes	Expected close date (YYYY-MM-DD)
`contact_first_name`	String	Yes	Contact’s first name
`contact_last_name`	String	Yes	Contact’s last name
`stage`	String	Yes	Current deal stage (must match a configured stage)

Transactions

Destination Field	Type	Required	Description
`amount`	Number	Yes	Transaction amount in cents
`currency`	String	Yes	Three-letter ISO currency code (e.g., USD, EUR)
`customer_key`	String	Yes	PartnerStack customer key, external key, or email

Default Destination Fields

Customers

Field	Type	Description
`email`	String	Customer email address
`partner_key`	String	Key of the partner responsible for the customer
`customer_key`	String	External customer key for identification
`name`	String	Customer or company name (max 100 characters)
`provider_key`	String	Payment provider identifier (e.g., Stripe customer ID)

Partnerships

Field	Type	Description
`email`	String	Partner email address
`first_name`	String	Partner’s first name
`last_name`	String	Partner’s last name
`partner_key`	String	Unique partner identifier
`group_key`	String	Group identifier for partnership placement
`manager_email`	String	Email of the assigned partner manager

Deals

Field	Type	Description
`group_key`	String	Unique key of the group for the deal’s partner
`account_name`	String	Name of the deal account
`amount`	Number	Deal amount in cents
`close_date`	String	Expected close date (YYYY-MM-DD or ISO 8601)
`contact_first_name`	String	Contact’s first name
`contact_last_name`	String	Contact’s last name
`stage`	String	Current deal stage
`customer_key`	String	Associated customer identifier
`source`	String	Deal source: `partner` or `vendor`

Transactions

Field	Type	Description
`amount`	Number	Transaction amount in cents
`currency`	String	Three-letter ISO currency code
`customer_key`	String	PartnerStack customer key
`customer_external_key`	String	External customer key (alternative to customer_key)
`category_key`	String	Transaction category identifier
`product_key`	String	Transaction product identifier
`key`	String	Unique transaction key in PartnerStack

How It Works

Zeotap maps each row to the selected PartnerStack object type using your field mapping configuration
Each row is sent as an individual API request to the PartnerStack Vendor API v2 (https://api.partnerstack.com/api/v2/)
Authentication uses HTTP Basic Auth with your public key as the username and secret key as the password
For upsert sync mode on customers and partnerships, Zeotap attempts to update the record first (using customer_key or partnership_key), and creates a new record if the update fails
Transactions are always created (append-only) — they cannot be updated or deleted
Deals are created via POST — the PartnerStack API does not support deal updates
Failed rows are logged individually with error details and do not prevent remaining rows from being processed

Rate Limits

PartnerStack enforces a rate limit of 4,000 requests per minute per IP address. Exceeding this limit results in HTTP 429 (Too Many Requests) responses. Zeotap processes rows sequentially and includes automatic retry logic with exponential backoff for rate limit responses.

Best Practices

Use test API keys during initial setup and testing. Test keys create test customers that do not affect production data.
Provide a customer_key when creating customers so you can reference them in transactions later.
Match deal stages exactly to the stages configured in your PartnerStack group settings. Mismatched stage names cause API errors.
Use ISO currency codes for transactions (e.g., USD, EUR, GBP). The currency field must be exactly 3 characters.
Transaction amounts are in cents — multiply dollar amounts by 100 before syncing.
Set partner_key on customer records to ensure proper attribution in the partner program.

Troubleshooting

Authentication failed (HTTP 401)

Verify your public key and secret key in Settings > Integrations > PartnerStack API Keys. Ensure you are using the correct key pair (test vs. production). Regenerate keys if they may have been compromised.

Customer creation fails with “partner_key required”

Every customer record must include a partner_key field that references an existing partner in your PartnerStack program. Verify the partner key is correct and the partner exists.

Transaction fails with “customer not found”

The customer referenced by customer_key, customer_external_key, or customer_email must already exist in PartnerStack. Create the customer first, then sync transactions.

Deal creation fails with “invalid stage”

The stage field must exactly match one of the configured deal stages in your PartnerStack group settings. Check Programs > [Group] > Deal Stages for valid values.

Rate limit exceeded (HTTP 429)

Zeotap automatically retries rate-limited requests with exponential backoff. If you consistently hit rate limits, reduce the sync frequency or split large syncs into smaller batches.

Update fails with “not found” (HTTP 404)

When using Update sync mode, the record must already exist. Ensure the customer_key or partnership_key is correct. Consider switching to Upsert mode to automatically create missing records.

Test data appearing in production

Ensure you are using production API keys, not test keys. Customers created with test keys are marked as test customers and cannot receive production transactions.

Amount field errors

The amount field for both deals and transactions must be an integer representing cents. If you see validation errors, verify that amounts are not in dollars (e.g., use 1000 for $10.00, not 10.00).