Data Importer

Importing data into your channel program

Overview

The PartnerStack importer allows company users to create or update objects in PartnerStack by uploading a CSV (comma separated value) file into PartnerStack via their program dashboard or through the REST API.

Importing Data is a simple, secure way to bring data into PartnerStack:

  • Only users with elevated permission can access the importer
  • All objects follow the same patterns of import
  • Alerts prevent you from importing incorrect headers
  • Post import reports provide a detailed breakdown of imported and skipped rows
  • All importer activity is captured in the audit log

Supported Objects

The importer currently supports these objects:

  • Partners
  • Customers
  • Transactions
  • Rewards
  • Leads
  • Deals

These objects cannot currently be imported:

  • Partner Teams
  • Actions

📘

Company only feature

At this time, only Company users can import data. Partner users cannot import data.

Importing Data

To import data into PartnerStack, follow these steps:

  1. Ensure you have permission to access the Importer
  2. Understand your business use case
  3. Know your data and program configuration
  4. Select your object type
  5. Follow the guide for the object type you’re importing

1. Import Permissions

A user's access to the importer is controlled by their permission configurations. 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.

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.

2. Understand your business use case

The importer can be used to complete a variety of tasks within your partner program. Before you import any data, it is important to understand how your program functions and what your business process is. Importing certain data types such as transactions and orders have the potential to generate financial rewards for partners.

To provide your partners the best possible experience we recommend double checking the expected outcome of your import with your teammate who setup your program Triggers, or PartnerStack support.

Common use cases and important notes:

Use caseImportant NotesRelated objects
Bulk add new partnersDouble check the user of ‘send invite emails'. Toggling this option on will send all imported partners an email to ‘claim their account’. If you’re not ready for partners to login to the portal, ensure this is toggled off.Partner
Bulk update existing partnersSupply a valid "partner_key" or the primary "partner_email" of an existing partner.

Import supports updating partner Group, Tier, Tags, Join Date, as well as any custom partnership fields you've configured.

Note that updating a partner tag's will add the tag to the partner, and will not overwrite or remove existing tags.
Partner
Backfilling transactionsBackfilling Transaction due to an integration outage, or a migration from another platform, ensure that you have first uploaded all relevant customer objects into PartnerStack. Transaction without a corresponding customer record will not be imported.Customer Transaction

3. Know your data and program configuration

Now that you know what you want to accomplish and the relevant objects, you’ll need to ensure you have the proper data for those objects. For instance, a Transactions import will require you to have access to the customer identifier and the net sales amount for each transaction line. You should also double check and field level requirements you might have setup in PartnerStack.

A simple way to check the needed data is to select the object of interest in the Importer object drop down and then view the required fields.

4. Select your object type

Navigate to the importer tool in your company dashboard, and select a data type from the dropdown.

Hover over “View Headers” to see a list of required and optional fields, or simply download a CSV template that includes all the headers.

Partner Import

The partner importer supports both updating existing partners, and adding new partners.

Field NameTypeexampleRequired?
partner_emailstring"dr.jones@ gmail.com"yes, or partner_key
partner_keystring"PartnerBryn"yes, or partner_email
partner_firststring“Bryn”no
partner_laststring“Jones”no
partner_groupstring“Affiliates”no
partner_tierstring“tier_xyz”no
partner_joined_datestring (ISO 8601 YYYY-MM-DD)“2020-12-25”no
partner_phone_numberstring“1112223333”no
shipping_address_citystring“Toronto”no
shipping_address_countrystring“Canada”no
shipping_address_line1string“123 Spadina ave”no
shipping_address_line2string“Unit 12”no
shipping_address_postalstring“L5C3S9” or “32154”no
shipping_address_statestring“New York”no
tagsString"tag1, tag2, tag3"no

Customer Import

Field NameTypeexampleRequired?
customer_keystring“cus_123xyz”yes
emailstring[email protected]yes
partner_keystring“PartnerBryn”yes
namestring“Marlie the Dog”no
created_atstring (ISO 8601 YYYY-MM-DD)“2020-12-25”no
company_namestring“Marlie Co”no
provider_keystring"cus_123xyz"no
statestring“New York”no
citystring“Toronto”no
unitstring“Unit 12”no
regionstring“Americas”no
primarybooleanTRUEno
postalstring“L5C3S9” or “32154”no

Transaction Import

Field NameTypeexampleRequired?
customer_keystring“customer_123”yes
amount_in_cents
or
amount_in_dollars
integer40000yes (one of)
created_atstring (ISO 8601 YYYY-MM-DD)“2020-12-25”no
currencystring“USD”no
keystring“transaction_123”no
product_keystring“product_123"no
category_keystring"product_123"no

In addition, you can include metadata (in the form of key-value pairs) to be attached to the transactions you upload. For example, you could include an agreement number as part of the transaction. Metadata is not used by PartnerStack, and will not be shown to your partners unless you choose to show it to them.

This metadata will be visible when retrieving the transactions via our API, or when exporting your program data to CSV.

To do so, include columns starting with metadata. followed by the name of the key you want to upload. For example, if you wanted to include a metadata attribute called the agreement number, you could add a column to your export called metadata.agreement_number.

The following restrictions apply:

  • Metadata cannot be updated (as transactions cannot be updated once created)
  • You can have a maximum of 25 metadata values stored in a single transaction
  • Each metadata key (e.g agreement_number) can be at most 30 characters long
    • Metadata keys can only have letters, numbers or _ in them
  • Metadata values can be either:
    • Empty
    • A string with a 100 character length limit
    • An integer, or a decimal value

Reward import

Field NameDescriptionExample
partner_emailThe email of the partner to issue the reward to. This (or partner_key, but not both) is required."[email protected]"
partner_keyThe partner key of the partner to issue the reward to. This (or partner_email, but not both) is required."matttest401"
target_typeThe type of object in PartnerStack to associate the reward to. This can be either customer, transaction, or blank. However, if it is specified, a target_key column value must be specified too."customer"
target_keyThe key of the object specified in target_type:
- For transaction, this would be the transaction's key
- For customer, this would be the customer key (set when you created the customer using PartnerStackJS or our API)
"cus_abc123zyx"
amount_in_centsThe amount in cents to issue as a reward. This, or amount_in_dollars, but not both is required.1000
amount_in_dollarsThe amount in dollars to issue as a reward. This, or amount_in_cents, but not both is required.10.00
bodyRequired: A description for the reward. This will be shown to partners."Bonus reward for going above and beyond this month"
created_atOptional: The date the reward was created at. Can be specified as milliseconds since epoch, or in the format YYYY-MM-DD1636077035000 or "2021-11-05"
currencyOptional: The currency the reward is issued in. Will be converted to USD once imported."CAD"
statusOptional: The status of the reward. By default is pending, but can be one of:
- pending
- declined
- hold
- approved
- paid

If a reward has already been paid outside of PartnerStack, this should be set as paid.
"pending"
decline_reasonOptional: If the reward is declined, you can specify this to show a decline reason to the partner."Duplicate marked by accident"
is_externalOptional: A flag to note that a reward was generated outside of PartnerStack. Can be "true" or "false"."true"

Lead import

Note that you can only import leads for one group at a time. You have to select a group in the dashboard. That is required.

Field NameDescriptionExampleRequired
partner_keyThe partner key of the partner to assign the lead."matttest401"Yes
emailThe contact's email of the lead"[email protected]"Yes
first_nameThe contact's first name of the lead"Joe"Yes
last_nameThe contact's last name of the lead"Kirby"Yes
statusThe status of the lead. It can be the following:
- open (for a New lead)
- closed (for a Qualified lead)
- dead (for an Unqualified lead).
- closed won (for a Closed Won lead)
- closed lost (for a Closed Lost lead)
* Note that this field is case sensitive so make sure to enter the status in lowercase.
"open"Yes
custom_fields_nameOther additional fields on the lead form. Please select the correct group to view the additional fields.Depends on whether the fields was set to be required.

Deal import

Note that you can only import deals for one group at a time. You have to select a group in the dashboard. That is required.

Field NameDescriptionExampleRequired
amount_in_cents
or
amount_in_dollars
The amount of the deal10000Yes
close_dateThe expected close date of the deal“2020-12-25”Yes
external_keyThe unique key of the deal"deal_12345"Yes
stageThe stage of the deal"Working"Yes
partner_keyThe partner key of the partner to assign the deal."matttest401"No
account_nameThe account name of the deal"Kirby Company"No
contact_first_nameThe contact's first name of the deal"Joe"No
contact_last_nameThe contact's last name of the deal"Kirby"No
created_atThe date the deal was created“2020-12-01”No