Who is this article for? This article will be helpful to you if you are a company at PartnerStack looking for an overview of how to use the importer, and for best practices.
Overview
The importer allows you to create or update objects in PartnerStack by uploading a CSV (comma-separated value) file into PartnerStack via the program dashboard.
You can find this tab in your dashboard by navigating to the Settings tab > Import > Data Importer.
Import Permissions
By default ‘Admin' and ‘Technical Teammates’ have access to the importer.
Access to the importer can be provided as needed to individual teammates by using a ‘custom’ permission configuration and permissions can be updated by the company account owner. Please see our support guide on Configuring teammate permissions for full information.
Once a user has access to the importer page, that user has access to all import types available to the program. In other words, you cannot limit importer access to a subset of objects so please ensure to only grant import permissions to teammates who need them.
Data you can import:
*The leads and deals import option will be available if leads and/or deals are enabled for your program. If you are not currently using leads and/or deals and would like to add this to your program please reach out to your Customer Success Manager to get this set up for you.
For a full overview of how to use the importer, and how to format your data when you are using the importer, please go to the PartnerStack technical docs.
Importing historical data can allow you to:
- Create partnerships with a partner (or partners) that you work with
- Add customers and connect them to a specific partner
- Backfill historical transactions that customers have made
- Reward your partners for historical transactions - or just create manual rewards in bulk!
Example import flow
If you're looking to import a transaction, you may need to first import the partner and customer if they do not yet exist in your program. To import a transaction, a customer must exist for the transaction to be tied to. To import a customer, a partner must exist for the customer to be attributed to.
Importing historical data
Importing historical data is useful to backfill data created before your PartnerStack program was created, add data after an integration change, or credit a sale to a partner that happened prior to the partner joining your program.
To make any kind of import, you must provide specific required data which will vary by import type.
How to view required & optional data
You can access the list of required and optional data in the importer by navigating to Select Data type > View CSV header.
Importing Partners
Migrating from another system or a homegrown solution? Importing partners will create an account for all your partners - so that all that will be left for them will be to claim their account and start referring your business!
Partner import use cases:
- Create a new partner or update existing partner information
- Create a partner manager within your program
- Create tags within your program
- Achieve bulk group moves
- Update partner key(s)
Mandatory data:
- partner_first: The partner’s first name
- partner_last: The partner’s last name
- partner_email: The partner’s email address
Optional data:
- partner_key: This is a unique identifier for the partner. If none is provided, we will create a randomized partner key for them
- partner_group: Which group would you like the partner to go into? If none is provided, we will place the partner in the default group
- partner_joined_date: This is the date that the partner signed up for your partner program. If none is provided, we will use the date of import
More optional data fields are available, for more information and for examples of how to format your partner data, check out our Importer technical doc.
Best practices for partner imports:
- Upon import, if you check the "", Partners will receive invitation emails to join your program
- If you check "Disable triggers on import", No triggers will be activated: no rewards will be generated, no emails will be sent, and partners will not be moved
- Make sure a group is specified. If it is not, partners will be added to the "Default" group
- When importing, the CSV dates should be formatted as
YYYY-MM-DD, and if specific times are needed, useYYYY-MM-DD HH:MM
Importing Customers
Has a partner requested to have a previous referral they made attributed to their account? Importing customers will create a customer record and attach it to a partner profile so that the customer’s purchases will be tracked going forward and the partner can receive the credit!
Mandatory data:
- customer_key: Your internal customer key - which is how PartnerStack tracks recurring purchases made by customers
- If you are unsure of where to find this, we recommend looking at current customer records from within PartnerStack. Typical values here are the customer emails or an account ID that is synced with your billing system
- ps_customer_key: This is a unique identifier for an existing customer within PartnerStack
- Required one of (exactly one): If you add a customer_key, you must not add a ps_customer_key and vice versa.
- email: The customer’s email address. This can also be anonymized for the protection of PII*
- partner_key: The referring partner’s partner_key. This can be found in your All partners tab in the partner detail view
- partnership_key: This is a unique identifier that ties the partnership to an existing partner within PartnerStack
- Required one of (or none): This means that you can either add the partner_key or the partnership_key or a blank space in the field
*Note: The customer email address must be unique to import - so if a customer exists in PartnerStack with that email, that customer will fail to import.
Optional data:
- name: This is the customer’s name. If none is provided, we will leave the name blank and display the customer’s email instead
- created_at: This is the date that the customer signed up for your product. If none is provided, we will use the date of import
- provider_key: A unique identifier created by your payment provider that is required to track recurring subscriptions if you use a payment webhook
When adding in a customer, for recurring transactions to track properly, it is important to know whether your integrated payment method is a payment webhook. If it is, in order for recurring transactions to track moving forward, the customer needs to have both a customer_key and a provider_key attached. See Tracking recurring transactions with a payment webhook integration for more information.
More optional data fields are available, for more information and for examples of how to format your customer data, check out our Importer technical doc.
Best practices for customer imports:
- Double-check that the partner exists in your Partnerstack dashboard
- Double-check that the correct partner_key has been added to ensure the customer is attributed to your intended partner
- Be sure to enable or disable triggers
- If you check the "Disable triggers on import", no triggers will be activated: no rewards will be generated, no emails will be sent, and partners will not be moved
- If you uncheck the "Disable triggers on import", triggers may be activated: rewards may be generated, emails may be sent, and partners may be moved
Importing Transactions
Did a partner request to get credit for a previous referral they made? Importing transactions will create individual transactions and attach them to a customer record so that the customer’s lifetime value is accurate - and can also generate rewards for partners!
Transaction import use cases:
- Create new transactions
- Import historical data: backdate old transactions from another platform (remember to disable triggers!)
Mandatory data:
- customer_key: The customer key allows PartnerStack to track recurring purchases made by customers
- If you are unsure of what this is, we recommend looking at current customer records from within PartnerStack. Typical values here are the customer emails or an account ID that is synced with your billing system
- ps_customer_key: This is a unique identifier for an existing customer within PartnerStack
- Required one of (exactly one): If you add a customer_key, you must not add a ps_customer_key and vice versa.
- amount_in_cents or amount_in_dollars: This is the transaction amount in cents or dollars. E.g; $500 USD transaction? Enter 50000 as the amount_in_cents
- Required one of (exactly one): You must add either the amount in cents or in dollars but not both
Optional data:
- key: While this is optional, we highly recommend including a transaction_key. This is used as a de-duplication mechanism and is important for troubleshooting or reporting in the future. A best practice here is to use a unique value from your internal systems
- created_at: This is the date that the customer actually paid you for your product. If none is provided, we will use the date of import
- product_key: Some companies have different reward structures for different products. If you have this setup, you can pass over the product_key that you would like to import. If none is provided, we will leave this blank
- currency: This is the 3-digit currency code for the currency you would like us to upload the transaction in. If none is provided, we will default to USD
More optional data fields are available, for more information and for examples of how to format your transaction data, check out our Importer technical doc.
Best practices for transaction imports:
- If you are using this import to backfill revenue data from another platform:
- Ensure to select "Disable triggers on import" to ensure new rewards are not created for historical transactions
- Ensure that transactions are imported with a key to avoid duplicate transactions or rewards
- If you are using this import to generate a reward (linked to a group trigger):
- Ensure that "Disable triggers on import" is not selected so rewards generate for the transactions you are uploading
- When importing, the CSV dates should be formatted as
YYYY-MM-DD.if specific times are needed, useYYYY-MM-DD HH:MM
Importing Rewards
Want to reward partners in bulk for a quarterly bonus? Or maybe just for being great partners! Look no further - creating custom rewards via a rewards import is super simple.
Reward import use cases:
- Issue bulk rewards
- Import historical data by marking rewards as "paid" externally
- Rewards were mistakenly missed or declined
Mandatory data:
- partner_email or partner_key: This is a unique identifier for the partner and can either be the partner_key or the partner_email which is how PartnerStack attributes the reward to the correct partner
- target_type: The type of object in PartnerStack to associate the reward to i.e. transaction or customer
- Note: if you add a target type, you must add a target_key to specify which transaction or customer the reward should be tied to
- target_key: The key of the object specified in the target type
- amount_in_cents: The amount in cents to issue as a reward
- You can import the amount in cents, or the amount in dollars, but not both
- amount_in_dollars: The amount in dollars to issue as a reward
- You can import the amount in dollars, or the amount in cents, but not both
- reward_description (body): This is what your partners will see as a reward description. You can get pretty descriptive here, but we recommend keeping it short and to the point
Optional data:
- reward_currency: This is the 3-digit currency code for the currency you would like us to upload the reward in. If none is provided, we will default to USD
- is_external: A flag to note that a reward was generated outside of PartnerStack. Can be "true" or "false"
- status: The status of the reward. Can be: pending, declined, hold, approved, or paid
- The default status is "pending" if this is left blank
- If you choose the status "paid" rewards will not be pulled onto your next invoice. This can be used when you would like to import historical rewards that have already been paid out to your partners, or rewards that you are paying your partners externally.
More optional data fields are available, for more information and for examples of how to format your reward data, check out our Importer technical doc.
Best practices for reward imports:
- When importing, the CSV dates should be formatted as
YYYY-MM-DD, and if specific times are needed, useYYYY-MM-DD HH:MM - Ensure you are including the correct reward amount either in cents or dollars to avoid over or under-rewarding a partner
Importing Leads
Would you like to submit a lead on behalf of your partner? Importing leads will create leads, assign various statuses and attach them to a partner's record to eventually generate rewards for partners!
Leads import use cases:
- Create new leads on behalf of partners
The mandatory and optional data required for the import is determined by the set required fields in your lead form for each group. For full information on how to customize lead forms, please go to our guide on Accepting leads with lead forms.
Mandatory data:
- first_name: The lead’s first name
- last_name: The lead’s last name
- email: The lead’s email address
- company: The lead's company name
- partner_key: This is a unique identifier for the partner
- status: This refers to the state of the lead at the point of import. Can be: open, closed, dead, closed won, or closed lost
Optional data:
- notes: This is what your partners will see as a lead description. You can get pretty descriptive here, but we recommend keeping it short and to the point
More optional data fields are available, for more information and for examples of how to format your lead data, check out our Importer technical doc.
Best practices for leads imports:
- If the lead intake form isn’t turned on for a group, the group is not listed in the selection list
- Be sure to select the correct group for the intended partner
- Be sure to enable or disable triggers
- If you check the "Disable triggers on import", no triggers will be activated: no rewards will be generated, no emails will be sent, and partners will not be moved.
- If you uncheck the "Disable triggers on import", triggers may be activated: rewards may be generated, emails may be sent, and partners may be moved.
- Double-check that the correct partner_key has been added to ensure the lead is attributed to your intended partner
- Be sure to select the correct lead status
Importing Deals
Would you like to submit a deal on behalf of your partner? Importing deals will create deals, assign various statuses and attach them to a partner's record to eventually generate rewards for partners!
The mandatory data required for the import is determined by the set required fields in your created deal submission form. The deal Stage, Close date, and Amount are mandatory fields in the deal submission form and these fields may be relabeled, but cannot be removed. For full information on how to customize deal submission forms, please go to our guide on Using Deal submission.
Mandatory data:
- amount: This is the transaction amount in cents. E.g; $500 USD transaction? Enter 50000 as the amount_in_cents
- close date: This is the date that the deal was closed
- partner_key: This is a unique identifier for the partner
- status: This refers to the state of the deal at the point of import- It could be "Closed won", "Working", or "Negotiating" depending on your set deal statuses. You can also create more deal stages within your dashboard based on the needs of your program
Deals import use cases:
- Create new deals
Best practices for deals imports:
- Be sure to enable or disable triggers
- If you check the "Disable triggers on import", no triggers will be activated: no rewards will be generated, no emails will be sent, and partners will not be moved.
- If you uncheck the "Disable triggers on import", triggers may be activated: rewards may be generated, emails may be sent, and partners may be moved.
- Double-check that the correct partner_key has been added to ensure the deal is attributed to your intended partner
- Be sure to select the correct deal status