> ## Documentation Index
> Fetch the complete documentation index at: https://help.hoopai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Importing and exporting payment data

> Import historical transactions, orders, and products via CSV, and export payment data for reporting and accounting.

The HoopAI Platform lets you move payment data in and out of the system through CSV imports and exports. Use imports to bring in product catalogs and historical records from a previous platform, and use exports to feed data into accounting software, create custom reports, or archive payment history.

<Note>
  CSV imports create new records — they do not update existing ones. If you need to modify existing products or transactions, edit them individually within the platform or use the bulk edit options where available.
</Note>

***

## Importing products via CSV

If you have an existing product catalog in a spreadsheet or another platform, you can import it directly into the HoopAI Platform without manual data entry.

<Steps>
  <Step title="Navigate to the Products import screen">
    Go to **Payments → Products** in the HoopAI web app. Click the **Import** button (or the dropdown arrow next to it) and select **Import as CSV**.
  </Step>

  <Step title="Download the CSV template">
    Click **Download Template** to get a pre-formatted CSV file with all the correct column headers. Always use the template as the starting point to ensure your file is formatted correctly before uploading.
  </Step>

  <Step title="Fill in the template">
    Open the downloaded template and add your products. Required and optional columns are described in the table below.
  </Step>

  <Step title="Upload the CSV">
    Drag and drop your completed CSV file into the upload area, or click **Browse** to select it from your computer.
  </Step>

  <Step title="Review the import preview">
    The platform shows a row-by-row preview of the data it will import. Review the preview carefully to confirm that prices, names, and types are correct.
  </Step>

  <Step title="Confirm the import">
    Click **Import** to create the products. Once complete, you will see a summary showing how many rows were successfully imported and how many had errors.
  </Step>

  <Step title="Fix errors and re-upload if needed">
    If any rows failed, download the error report. It shows the row number and the specific validation failure for each problem row. Fix the issues in your CSV and re-upload only the failed rows.
  </Step>
</Steps>

### Product CSV column reference

| Column             | Required | Notes                                                      |
| ------------------ | -------- | ---------------------------------------------------------- |
| Name               | Yes      | The product display name                                   |
| Description        | Yes      | Short product description                                  |
| Price              | Yes      | Numeric value without currency symbols (e.g., `49.99`)     |
| Type               | Yes      | `Physical`, `Digital`, or `Free`                           |
| Currency           | Yes      | Three-letter ISO code (e.g., `USD`, `GBP`, `EUR`)          |
| SKU                | No       | Stock-keeping unit for inventory tracking                  |
| Inventory Quantity | No       | Leave blank for unlimited stock                            |
| Weight             | No       | For physical products; used in shipping calculations       |
| Compare At Price   | No       | Original price shown as a strikethrough (for sale pricing) |
| Collection         | No       | Assigns the product to an existing product collection      |

<Warning>
  If the **Type** column contains a value other than `Physical`, `Digital`, or `Free` (case-sensitive), the row will fail validation. Check for trailing spaces or different capitalization if you encounter errors on this column.
</Warning>

***

## Importing products from Stripe

If you have an existing product and price catalog in Stripe, you can pull it directly into the HoopAI Platform without building a CSV.

<Steps>
  <Step title="Connect Stripe">
    Ensure your Stripe account is connected in **Payments → Payment Integrations**. The import will not be available if Stripe is not connected.
  </Step>

  <Step title="Open the import screen">
    Go to **Payments → Products**, click the **Import** dropdown, and select **Import from Stripe**.
  </Step>

  <Step title="Review and confirm">
    The platform displays a list of all products found in your Stripe account. Review the list to confirm the products and prices are the ones you want to import.
  </Step>

  <Step title="Complete the import">
    Click **Import**. All Stripe products are pulled in automatically with their prices and variants preserved.
  </Step>
</Steps>

<Note>
  The Stripe product import is a one-time operation. Changes made to products in Stripe after the import are not automatically reflected in the HoopAI Platform. To keep catalogs in sync, update products directly in the HoopAI web app after the initial import.
</Note>

***

## Importing historical transactions via CSV

Use the transaction import to bring payment history from a previous platform into HoopAI. This is particularly useful when migrating so that your reporting and customer payment history remain intact.

<Steps>
  <Step title="Navigate to transaction import">
    Go to **Payments → Transactions** and click **Import**.
  </Step>

  <Step title="Download the CSV template">
    Download the transaction import template to ensure your data is structured with the correct column headers.
  </Step>

  <Step title="Prepare your CSV">
    Fill in the template using your historical data. Required columns are described in the table below.
  </Step>

  <Step title="Upload and review">
    Upload the CSV and review the import preview. Confirm that dates, amounts, and customer details look correct.
  </Step>

  <Step title="Confirm the import">
    Click **Import** to create the transaction records. Imported transactions will display **Imported** in the source column, distinguishing them from transactions processed natively through the platform.
  </Step>
</Steps>

### Transaction CSV column reference

| Column         | Required | Notes                                      |
| -------------- | -------- | ------------------------------------------ |
| Date           | Yes      | ISO format recommended: `YYYY-MM-DD`       |
| Amount         | Yes      | Numeric value without currency symbols     |
| Currency       | Yes      | Three-letter ISO code                      |
| Customer Name  | Yes      | Contact's full name                        |
| Customer Email | Yes      | Used to match or create a contact record   |
| Description    | Yes      | Brief description of what was purchased    |
| Status         | Yes      | `Paid`, `Refunded`, `Failed`, or `Pending` |

***

## Importing historical invoices via CSV

If you are migrating from QuickBooks, FreshBooks, or another invoicing platform, you can import your invoice history to maintain a complete billing record.

<Steps>
  <Step title="Navigate to invoice import">
    Go to **Payments → Invoices** and click **Import**.
  </Step>

  <Step title="Download the invoice import template">
    Use the provided template to format your invoice data. The template includes all supported fields.
  </Step>

  <Step title="Prepare already-paid invoices">
    For invoices that were already paid before the migration, include the payment date in the corresponding column. The import will mark those invoices as paid with the recorded date rather than as outstanding.
  </Step>

  <Step title="Upload and confirm">
    Upload the completed CSV, review the preview, and click **Import**. Invoices will appear in **Payments → Invoices** with the status set based on the data in your file.
  </Step>
</Steps>

<Tip>
  Set already-paid invoices to a paid status during import rather than leaving them as due. This keeps your invoice dashboard accurate and prevents automated payment reminders from going out for invoices that were settled before the migration.
</Tip>

***

## Exporting transactions as CSV

Export your full transaction history or a filtered subset for accounting, reporting, or external analysis.

<Steps>
  <Step title="Apply filters (optional)">
    In **Payments → Transactions**, use the filter controls to narrow the data before exporting. You can filter by:

    * Date range
    * Transaction status (paid, refunded, failed, pending)
    * Payment gateway (Stripe, Square, PayPal, NMI, Authorize.net)
    * Payment mode (live or test)
  </Step>

  <Step title="Click Export">
    Click the **Export** button. The platform will generate a CSV file containing all transactions that match your current filter criteria.
  </Step>

  <Step title="Download the file">
    Once the export is ready, the download will begin automatically or a download link will appear. Save the file to your computer.
  </Step>
</Steps>

### Transaction export columns

| Column          | Description                                                                             |
| --------------- | --------------------------------------------------------------------------------------- |
| Date            | Transaction timestamp                                                                   |
| Amount          | Total charged amount                                                                    |
| Currency        | Transaction currency                                                                    |
| Customer Name   | Contact's name                                                                          |
| Customer Email  | Contact's email address                                                                 |
| Payment Method  | Card, ACH, Apple Pay, cash, etc.                                                        |
| Gateway         | Which payment processor handled the transaction                                         |
| Status          | Paid, refunded, failed, or pending                                                      |
| Refund Status   | Refunded, partially refunded, or not refunded                                           |
| Tax Amount      | Total tax collected                                                                     |
| Discount Amount | Total discount applied                                                                  |
| Coupon Code     | Coupon code used (if any)                                                               |
| Late Fee        | Late fee amount (if applicable)                                                         |
| Tip             | Tip amount (if applicable)                                                              |
| Source          | Where the transaction originated (invoice, order form, subscription, POS, payment link) |
| Source ID       | The ID of the originating record                                                        |

***

## Exporting orders as CSV

Export your order history from order forms and product purchases.

<Steps>
  <Step title="Navigate to Orders">
    Go to **Payments → Orders**.
  </Step>

  <Step title="Apply filters (optional)">
    Filter by date range, status, or payment mode to narrow the export scope.
  </Step>

  <Step title="Click Export">
    Click the **Export** button to download the orders CSV.
  </Step>
</Steps>

### Order export columns

| Column       | Description                                                  |
| ------------ | ------------------------------------------------------------ |
| Order ID     | Unique system identifier for the order                       |
| Date         | Order timestamp                                              |
| Customer     | Contact name                                                 |
| Product Name | Name of the purchased product                                |
| Quantity     | Number of units purchased                                    |
| Unit Price   | Price per unit                                               |
| Discount     | Discount applied to this line item                           |
| Subtotal     | Line total after discount, before tax                        |
| Tax Name     | Name of the tax applied                                      |
| Tax Amount   | Tax collected on this line item                              |
| Total        | Final line total including tax                               |
| Status       | Paid, pending, refunded, etc.                                |
| Payment Mode | Live or test                                                 |
| Source       | Which funnel, website, or order form originated the purchase |

***

## Exporting subscriptions as CSV

Export your active and historical subscription data for reporting and accounting.

<Steps>
  <Step title="Navigate to Subscriptions">
    Go to **Payments → Subscriptions**.
  </Step>

  <Step title="Apply filters (optional)">
    Filter by status (active, paused, cancelled, or expired) or by date range to refine your export.
  </Step>

  <Step title="Click Export">
    Click the **Export** button to generate the subscriptions CSV.
  </Step>
</Steps>

### Subscription export columns

| Column          | Description                                         |
| --------------- | --------------------------------------------------- |
| Subscription ID | Unique system identifier                            |
| Customer        | Contact name                                        |
| Start Date      | When the subscription began                         |
| End Date        | When the subscription ended (blank if still active) |
| Trial Period    | Trial length in days (if applicable)                |
| Status          | Active, paused, cancelled, or expired               |
| Payment Method  | Card type and last four digits                      |
| Subtotal        | Recurring charge before discounts and taxes         |
| Discount        | Discount applied (flat or percentage)               |
| Tax             | Tax amount per billing cycle                        |
| Coupon Code     | Coupon applied at subscription signup               |
| Line Items      | Products included in the subscription               |

***

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I import subscriptions?">
    No. Subscriptions cannot be imported via CSV. They must be created manually through **Payments → Subscriptions** or through an order form connected to a subscription product. If you are migrating from another platform, customers will need to re-enter their payment details on a new subscription signup flow.
  </Accordion>

  <Accordion title="What file format is required for CSV imports?">
    All CSV imports require a UTF-8 encoded `.csv` file. Download the provided template for each import type to ensure the column headers and formatting are correct. Incorrect encoding or extra columns outside the template can cause import failures.
  </Accordion>

  <Accordion title="Can I update existing products via CSV import?">
    Not currently. CSV imports create new products rather than updating existing ones. To modify an existing product, open it in **Payments → Products** and edit it directly. For bulk edits, use the bulk edit option available in the product list.
  </Accordion>

  <Accordion title="Is there a row limit on CSV imports?">
    There is no hard row limit enforced for CSV imports. Very large files may take longer to process and the import may run in the background. For best results, split exceptionally large files (tens of thousands of rows) into smaller batches.
  </Accordion>

  <Accordion title="Can I export a single invoice as PDF?">
    Yes. From **Payments → Invoices**, find the invoice you want and click the three-dot menu on that row. Select **Download** to save the invoice as a PDF file. This is separate from the CSV export and generates a formatted invoice document.
  </Accordion>

  <Accordion title="Does exporting transactions include refunded amounts?">
    Yes. The transaction export includes a **Refund Status** column and a **Status** column. Refunded transactions appear in the export with refund details included so your accounting records reflect the net amount accurately.
  </Accordion>

  <Accordion title="Can I schedule recurring exports?">
    Not currently. All CSV exports are manual and on-demand. For automated reporting, use the Reporting section within the platform or set up a Zapier or Make integration to pull transaction data on a schedule and push it to a spreadsheet or data warehouse.
  </Accordion>

  <Accordion title="What happens if imported transactions reference contacts that don't exist yet?">
    The platform will attempt to match the customer email in your CSV to an existing contact. If no matching contact is found, a new contact record will be created using the name and email from the CSV row.
  </Accordion>

  <Accordion title="Can I re-import a CSV if the first attempt had errors?">
    Yes. Fix the errors in your CSV and re-upload the file. Only re-upload the rows that failed — successfully imported rows will be duplicated if included again. Use the error report from the failed import to identify exactly which rows need correction.
  </Accordion>
</AccordionGroup>