--- updatedAt: 2025-12-15T20:44:52.000Z agentTools: projectIndex: https://docs.pelcro.com/v2.4/llms.txt --- # Import tool Bulk import customers and subscriptions via CSV files. Process agency orders, renewals, address changes, and complimentary subscriptions. *** title: Import Tool slug: import-tool privacy: view: anyone\_with\_link content: excerpt: Bulk import customers and subscriptions via CSV files. Process agency orders, renewals, address changes, and complimentary subscriptions. metadata: description: Complete guide to the Pelcro Import Tool - learn how to bulk import customers and subscriptions via CSV, process agency orders, handle renewals, and manage address changes. keywords: import tool, csv import, bulk import, agency import, subscription import, customer import, data migration ------------------------------------------------------------------------------------------------------------------- The Import Tool allows publishers to bulk import customer and subscription data via CSV files. ## Where to Find It Log in to your dashboard, open the left side menu, and locate the Import Tool icon towards the bottom of the menu. ## Use Cases * Importing agency customers and subscriptions * Importing regular bulk customers and free subscriptions *** ## Import File Format All data imported into the Import Tool must be in CSV format. [Learn more about CSV file format](https://en.wikipedia.org/wiki/Comma-separated_values). ### File Structure Below are all the required headers. Copy and paste these columns, using comma as the separator: ``` first_name,last_name,email,phone,language,address_billing_line1,address_billing_line2,address_billing_city,address_billing_state,address_billing_country,address_billing_zip,address_billing_phone,address_shipping_first_name,address_shipping_last_name,address_shipping_line1,address_shipping_line2,address_shipping_city,address_shipping_state,address_shipping_country,address_shipping_zip,address_shipping_phone,quantity,plan_id,site_id,agency_id,action,agency_customer_id ``` ### File Naming Convention Once you upload a file, it is automatically renamed using these conventions: * `Agency_12345678` - for agency subscription files * `File_12345678` - for free subscription files ### File Limits * **Maximum rows per file**: 150 rows * **File format**: CSV (comma-separated values) * **Encoding**: UTF-8 *** ## Column Validations ### Customer Information | Column | Rules | | ------------ | ------------------------------------------------------------------------------------ | | `first_name` | Required. String. 255 characters maximum. | | `last_name` | Required. String. 255 characters maximum. | | `email` | Required for new customers. Valid email format. Unique per account. Unique per file. | | `phone` | Optional. Numeric. | | `language` | Required. 2 characters maximum (e.g., `en`, `fr`). | ### Billing Address All billing address fields are optional. However, if you provide any billing field, then `address_billing_line1`, `address_billing_state`, and `address_billing_country` become required. | Column | Rules | | ------------------------- | ---------------------------------------------------------------------------- | | `address_billing_line1` | Optional. Required if other billing fields provided. 255 characters maximum. | | `address_billing_line2` | Optional. 255 characters maximum. | | `address_billing_city` | Optional. 255 characters maximum. | | `address_billing_state` | Optional. Required if other billing fields provided. 2 characters maximum. | | `address_billing_country` | Optional. Required if other billing fields provided. 2 characters maximum. | | `address_billing_zip` | Optional. 255 characters maximum. | | `address_billing_phone` | Optional. Numeric. | ### Shipping Address | Column | Rules | | ----------------------------- | --------------------------------------------------------------------------------------------------- | | `address_shipping_first_name` | Optional by default. Required for products that require an address. String. 255 characters maximum. | | `address_shipping_last_name` | Optional by default. Required for products that require an address. String. 255 characters maximum. | | `address_shipping_line1` | Optional by default. Required for products that require an address. 255 characters maximum. | | `address_shipping_line2` | Optional. 255 characters maximum. | | `address_shipping_city` | Optional by default. Required for products that require an address. 255 characters maximum. | | `address_shipping_state` | Optional by default. Required for products that require an address. 2 characters maximum. | | `address_shipping_country` | Optional by default. Required for products that require an address. 2 characters maximum. | | `address_shipping_zip` | Optional by default. Required for products that require an address. 255 characters maximum. | | `address_shipping_phone` | Optional. Numeric. | ### Subscription Details | Column | Rules | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `quantity` | Optional. Integer. Minimum value is 0. | | `plan_id` | Required. Integer. For agency subscriptions: plan amount must be greater than zero, must be an agency plan, must be associated with the agency\_id. For free subscriptions: plan amount must be zero. | | `site_id` | Required. Integer. Find your site ID in the Integration page. | | `agency_id` | Required for agency subscriptions. Can be null for free subscriptions. Integer. | | `action` | Required. One of: `new`, `renew`, `change_of_address`, `free_subscription`. | | `agency_customer_id` | Required for agency subscriptions. Can be null for free subscriptions. Unique per file. | *** ## Actions | Action | Description | | ------------------- | -------------------------------------------------------------------------- | | `new` | Register a new customer on the platform for the first time. | | `renew` | Renew the subscription of an existing customer. | | `change_of_address` | Add or update the shipping and/or billing address of an existing customer. | | `free_subscription` | Register a new customer and assign a free subscription. | *** ## Sample CSV Files ### Agency Subscriptions ```csv first_name,last_name,email,phone,language,address_billing_line1,address_billing_line2,address_billing_city,address_billing_state,address_billing_country,address_billing_zip,address_billing_phone,address_shipping_first_name,address_shipping_last_name,address_shipping_line1,address_shipping_line2,address_shipping_city,address_shipping_state,address_shipping_country,address_shipping_zip,address_shipping_phone,quantity,plan_id,site_id,agency_id,action,agency_customer_id Doy,Gepson,hbowler0@microsoft.com,7043544773,En,01010 Killdeer Pass,Wayridge,Saint-Lambert-de-Lauzon,QC,CA,V6L,3963367817,Herta,Bowler,8081 Sommers Terrace,79538 Hintze Center,Saint-Augustin-de-Desmaures,QC,CA,G3A,7589175595,1,45163,160,1,new,ccDQ8 ``` ### Free Subscriptions ```csv first_name,last_name,email,phone,language,address_billing_line1,address_billing_line2,address_billing_city,address_billing_state,address_billing_country,address_billing_zip,address_billing_phone,address_shipping_first_name,address_shipping_last_name,address_shipping_line1,address_shipping_line2,address_shipping_city,address_shipping_state,address_shipping_country,address_shipping_zip,address_shipping_phone,quantity,plan_id,site_id,agency_id,action,agency_customer_id Darn,Camosso,gakram0@example.com,5523465143,En,216 Oriole Court,Dennis,Repentigny,QC,CA,J6V,5726309881,Georas,Akram,3137 Fuller Plaza,25513 Michigan Point,Trois-Rivières,QC,CA,L8J,9853764370,3,23,1,,free_subscription, ``` *** ## Step-by-Step Guide ### 1. Upload File 1. Open the Import Tool from the dashboard menu 2. Click the **Upload file** button 3. Select your CSV file The file uploads automatically. Reload the page to see your imported file ready for processing. ### 2. View Import Summary The summary page displays all imported files with these columns: | Column | Description | | ------------- | ----------------------------------------- | | **AGENCY** | Name of the agency that provided the file | | **SET** | Auto-generated set name | | **TOTAL** | Total number of rows in the file | | **REJECTED** | Rows that failed validation | | **FAILED** | Rows that failed during processing | | **PROCESSED** | Successfully processed rows | | **CREATED** | Import date | | **INFO** | System notifications | Each row has a menu with options: * **View details** - View the file data * **Delete** - Delete the file (only available if no rows have been processed) ### 3. Review Rows When viewing file details: * **White rows** - Passed validation, ready to process * **Red rows** - Failed validation, check error message * **Blue rows** - Validated and ready for processing * **Green rows** - Successfully processed ### 4. Process Rows #### Manual Processing (Row by Row) 1. Click the options menu on a white row 2. Select **Validate** 3. The row turns blue 4. Click the options menu again 5. Select **Process** 6. The row turns green when complete #### Bulk Processing 1. Validate all rows you want to process 2. Click **PROCESS ALL VALIDATED** at the top 3. All validated rows are processed automatically ### 5. Verify Results Navigate to the Customers section in the dashboard to find all customers and subscriptions created via the Import Tool. *** ## Searching Imported Files Search imported files by name: * Search "file" to list all free subscription files * Search "agency" to list all agency subscription files *** ## Handling Validation Errors When validation fails, the row is highlighted in red with an error message. ### To Fix Errors 1. Note the row ID and error message 2. Open your CSV file in a text editor 3. Find and fix the row causing the error 4. Save the file 5. Delete the failed import from the tool 6. Re-upload the corrected file *** ## Accounting For agency subscriptions, an invoice is automatically created and marked as paid via an offline payment. All offline payments from the Import Tool are marked as **agency payments**. # Sibling pages * [Billing Engine ](https://docs.pelcro.com/v2.4/docs/our-billing-engine.md) * [Account vs Site](https://docs.pelcro.com/v2.4/docs/accounts.md) * [Collaborators](https://docs.pelcro.com/v2.4/docs/collaborators.md) * [Automated emails](https://docs.pelcro.com/v2.4/docs/automated-emails.md) * [Logs](https://docs.pelcro.com/v2.4/docs/logs.md) * [Identity](https://docs.pelcro.com/v2.4/docs/identity.md) * [FAQs](https://docs.pelcro.com/v2.4/docs/faq.md)