Best practices for importing data into your program

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.

Importing data 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:

• Partners
• Customers
• Transactions
• Commissions
• Leads* 
• Deals*

*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 
• Issue commissions to your partners for historical transactions - or just create manual commissions in bulk!

Import order

The order in which you import your data is important as specific data types require specific targets to be tied to. For example, a partner must exist for a customer or commission to be tied to, and a customer must exist for a transaction or commission to be tied to. If you attempt to import customers for a partner, but the partner does not yet exist in PartnerStack, the import will fail.

An example import flow when importing your data would then be:

1. Import your desired partners if they do not already exist 
2. Import your desired customers and specify the partner they should be tied to using the partner_key
3. Import your desired transaction and specify the customer they should be tied to using the customer_key
4. Import your desired commission and specify the partner they are for using the partner_key 
   1. Optional, if the commission should be for a specific target (an existing customer or transaction) specify the target type, and target key in your import. If the target type is customer or transaction enter the customer_key or transaction_key as the import "target_key".

If triggers are left enabled when importing customers or transactions, commissions will automatically fire depending on your offer structure.

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)

Partner import mandatory data:

• partner_first: The partner’s first name
• partner_last: The partner’s last name
• partner_email: The partner’s email address

Partner import 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
• tags: Any tags you would like added to your partner. These can be used to build customized email campaigns or triggers. For more information on tags see the Tagging your partners support guide.

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 "Send partner invitation emails", Partners will receive invitation emails to join your program
• If you check "Disable triggers on import", No triggers will be activated: no commissions 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 asYYYY-MM-DD, and if specific times are needed, use YYYY-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!

Customer import 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. 

Customer 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 commissions 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: commissions 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 commissions for partners!

Transaction import use cases:

• Create new transactions
• Import historical data: backdate old transactions from another platform (remember to disable triggers!)

Transaction import 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 

Transaction import 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 commission 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 commissions are not created for historical transactions
  • Ensure that transactions are imported with a key to avoid duplicate transactions or commissions
• If you are using this import to generate a commission (linked to a group trigger):
  • Ensure that "Disable triggers on import" is not selected so commissions generate for the transactions you are uploading
• When importing, the CSV dates should be formatted asYYYY-MM-DD.if specific times are needed, use YYYY-MM-DD HH:MM

Importing commissions 

Want to create commissions for partners in bulk for a quarterly bonus? Or maybe just for being great partners! Look no further - the commissions importer can help.

Commissions import use cases:

• Issue bulk commissions
• Import historical data by marking commissions as "paid" externally
• Commissions were mistakenly missed or declined

Commission import 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 commission to the correct partner
• amount_in_cents: The amount in cents to issue as a commission
  • 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 commission
  • You can import the amount in dollars, or the amount in cents, but not both
• commission_description (body): This is what your partners will see as a commission description. You can get pretty descriptive here, but we recommend keeping it short and to the point

Commissions import optional data:

• target_type: The type of object in PartnerStack to associate the commission 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 commission should be tied to
• target_key: The key of the object specified in the target type
• currency: This is the 3-digit currency code for the currency you would like us to upload the commission in. If none is provided, we will default to USD
• is_external: A flag to note that a commission was generated outside of PartnerStack. Can be "true" or "false"
• status: The status of the commission. Can be: pending, declined, hold, approved, or paid
  • The default status is "pending" if this is left blank
  • If you choose the status "paid" commissions will not be pulled onto your next invoice. This can be used when you would like to import historical commissions that have already been paid out to your partners, or commissions that you are paying your partners externally.

More optional data fields are available, for more information and for examples of how to format your commission data, check out our Importer technical doc. 

Best practices for commission imports:

• When importing, the CSV dates should be formatted asYYYY-MM-DD, and if specific times are needed, use YYYY-MM-DD HH:MM
• Ensure you are including the correct commission amount either in cents or dollars 

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 commissions 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.

Lead import 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

Lead import 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 commissions 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: commissions 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 commissions 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.

Deals import use cases:

• Create new deals

Deal import mandatory data:

• amount: This is the transaction amount in cents i.e $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

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 commissions 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: commissions 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