Allocora
Docs / Import Template Library

Reference

Use import templates to start from the right source shape

Revenue import templates prefill mappings from known source shapes before preview. Payee migration accepts CSV, Excel 97–2003 XLS, and XLSX source files while keeping its downloadable generic templates in CSV and XLSX. It uses explicit mapping confirmation, an asynchronous no-write preview, and a separately confirmed atomic create-only import. Neither path bypasses validation, changes revenue math, starts calculations, or executes payouts.

Start Free Try Sample Data

Details

What to know

Prepare, review, and import payees

Workspace Owners and Admins can open Account > Payees > Import Payees to prepare one CSV, Excel 97–2003 XLS, or XLSX file per independent batch. Finance and Viewer roles cannot access this workflow.

  • Download the generic payee CSV or XLSX template; each contains exactly the supported payee and contract-economics fields with synthetic example data.
  • For XLS and XLSX, select one worksheet and its header row. Allocora never combines worksheets. For CSV, select the header row.
  • Excel 5/95 XLS workbooks are not supported. Save or convert them to CSV, Excel 97–2003 XLS, or XLSX before uploading.
  • In Excel 97–2003 XLS files, formulas are kept as raw formula text and are never run. Spreadsheet dates are normalized to YYYY-MM-DD.
  • Explicitly map External ID, Name, and Type. Allocora does not generate a missing stable source ID. Review every suggested mapping before confirming it.
  • Optional provider IDs can be retained as labelled provenance-only columns. They do not create or match provider identities.
  • After mapping confirmation, start an asynchronous no-write preview. It streams up to 50,000 rows, validates supported fields and dates, detects duplicate or existing external IDs, reports shared-email warnings, retains provider IDs as preview provenance, and projects workspace payee capacity.
  • Review blockers and warnings before continuing. Warning-bearing previews require explicit acknowledgement. Corrected worksheet, header, or mapping context requires regeneration; corrected row values or row count require uploading the corrected file as a new batch.
  • When the active preview has no blockers, explicitly confirm the create-only import. Allocora rechecks the reviewed evidence immediately and in the queued worker, including live role, plan capacity, and external-ID availability. A changed condition blocks the full batch instead of skipping or updating existing payees.
  • A successful commit atomically creates the full reviewed batch: one new payee, one version 1 containing only approved imported fields, and one immutable provenance row for each source row. Provider identifiers stay in provenance and the crosswalk; they never create provider identities.
  • Download the versioned XLSX crosswalk to match source rows and external IDs to the new Allocora payee IDs. After success, the raw source is queued for deletion while the immutable preview, commit result, row provenance, hashes, counts, and audit evidence remain.
  • The import does not create rules, start calculations, generate statements, create payouts, call integrations, or move money. You decide when to configure rules and run calculations.
  • If processing fails, the complete attempted import is rolled back. Failures marked retryable can use the same reviewed batch; source-data, identity, or capacity conflicts must be corrected first.
  • Open Completed import history to review batch counts, source and commit hashes, actors, timestamps, and the XLSX crosswalk. This history is available only to workspace Owners and Admins.
  • The first downstream use of any imported payee permanently blocks the entire batch from removal. This includes rules, later payee versions, calculations, tiers, statements, deliveries, reconciliation, external identities, portal access, feedback, and payee-specific exports. Deleting or archiving the dependent record never clears the lock.
  • Imports completed before permanent dependency tracking are Unverified: an empty current dependency list cannot prove that they were never used. They are not eligible for removal. For newly tracked imports, No recorded dependency is informational and any future removal must recheck eligibility.
  • Bulk removal of an imported payee batch is not available in this release. The history records eligibility evidence only; it does not delete batches, payees, or financial records.

Migrate dated rules after importing payees

Workspace Owners and Admins can open Account > Rules > Migrate rules to review one JSON or CSV file before creating inactive rules. This is separate from the standard Import controls for timeless rules.

  • Open rule migration to upload a file and review it before confirmation. Sign in as a workspace Owner or Admin.
  • Upload one JSON or CSV file up to 10 MiB, containing at most 100 logical rules. Each rule needs a stable external_id, an exact YYYY-MM-DD valid_from, and either an inclusive valid_to or an explicit open_ended=true decision.
  • Use source_external_id and optional allocora_payee_id from the payee crosswalk for allocation references. CSV allocation rows with the same rule external_id must agree on the rule definition.
  • Preview performs no business writes. Review exact effective dates, proposed inactive rules, resolved payees/products/revenue sources, allocation totals, tier schedules, and row-specific errors.
  • Blocking errors and unresolved rule conflicts prevent confirmation. Download the issue report, correct the source file, and generate a new preview. Review overlap and date-gap warnings separately.
  • Continue to the explicit confirmation only after reviewing a ready preview. Acceptance expires after 30 minutes, and confirmation rechecks current permissions, accepted evidence integrity, dependencies, and conflicts.
  • A successful confirmation creates the complete batch atomically as inactive rules. Download the JSON or CSV source-rule-ID crosswalk before leaving the page. CSV report cells neutralize spreadsheet formula prefixes; JSON preserves literal identifiers.
  • Stale or expired acceptance requires a fresh preview. If a connection or server error leaves the outcome uncertain, retry the same accepted confirmation to recover its original result without duplicate rules.
  • The page keeps review state only during the current session; refreshing does not restore it. Migration does not activate rules, run calculations, generate statements, or execute payouts. Activation remains a separate decision.

How template-assisted import works

Choose a template before uploading a CSV/XLS/XLSX file, or leave the selector on auto-detect. Allocora previews the file, applies template aliases where they match headers, then shows the final mapping for review.

  • Template suggestions prefill mappings only; required fields, invalid rows, duplicate mapping checks, currency checks, and product-mapping quality checks still run.
  • Users can override any suggested mapping before import confirmation.
  • The encrypted preview binds the selected template key and version, statement period, mapping, currency, and number format; changing any of them requires a fresh preview.
  • Confirmed imports store the selected template key, name, version, expected source type, required fields, optional fields, and sample filename on the retained import batch for audit review.
  • Template-specific source type labels are versioned with the import and normalized to sale, refund, or adjustment. Any other non-empty type value fails row validation instead of becoming a sale.
  • V2 stores mapping and template metadata per import batch; it does not silently set a source-level default template after one import.
  • Sample CSV files are available from this reference and from the import screen when a template is selected.

Template boundaries

Templates are source-shape helpers, not custom integrations. They do not call external systems or infer contractual payout terms.

  • Use templates to map dates, amounts, transaction IDs, currencies, product or catalog keys, and optional partner context.
  • Use Allocora products, payees, rules, and calculation runs to decide who is owed what.
  • PayPal, Wise, Tipalti, Trolley, and generic bank/AP templates are sample shapes for payout confirmation reconciliation evidence, not payment execution inside Allocora.

Reference Tables

Fields and checks

Revenue import templates

These templates are available in the revenue import screen and include downloadable sample CSV files.

Template Use when Sample file
Generic DSP royalty statement CSV Music royalty statements with ISRC, line IDs, net royalty, currency, title, and territory fields. /docs/import-templates/generic-dsp-royalty-statement/sample.csv
LabelGrid-style label royalty CSV Label royalty statements with ISRC/UPC, period, store, territory, adjustment, return, and payout context. /docs/import-templates/labelgrid-label-royalty/sample.csv
LabelWorx/RoyaltyWorx-style import CSV LabelWorx/RoyaltyWorx-style statements with release, track, store, territory, and statement-period fields. /docs/import-templates/labelworx-royaltyworx-import/sample.csv
Revelator-style royalty statement CSV Statement-style music royalty rows with payable amount, marketplace, territory, and usage context. /docs/import-templates/revelator-royalty-statement/sample.csv
Music distributor royalty variant CSV TuneCore, DistroKid, CD Baby, and distributor-style royalty exports with store/territory/catalog context. /docs/import-templates/music-distributor-royalty-variant/sample.csv
KDP book sales/royalty export Publishing royalty rows with ASIN/ISBN, title, marketplace, transaction ID, and royalty amount fields. /docs/import-templates/kdp-book-sales-royalty/sample.csv
IngramSpark-style book sales export Book distributor rows with ISBN, order ID, title, country, and net royalty fields. /docs/import-templates/ingramspark-book-sales/sample.csv
ACX audiobook royalty export Audiobook royalty rows with ASIN/ISBN, title, marketplace, royalty type, and period context. /docs/import-templates/acx-audiobook-royalty-export/sample.csv
Draft2Digital-style publishing export Publishing distributor rows with sale ID, ISBN/title ID, channel, and net earnings fields. /docs/import-templates/draft2digital-publishing/sample.csv
Shopify seller/creator revenue-share CSV Order-level seller, creator, or partner revenue-share worksheets with SKU/product and partner context. /docs/import-templates/shopify-seller-creator-revenue-share/sample.csv
Amazon SellerCentral payout/sales report Marketplace settlement rows with order, SKU/ASIN, seller, returns, adjustments, payout ID, and territory context. /docs/import-templates/amazon-sellercentral-payout-sales/sample.csv
Stripe subscription/affiliate commission CSV Stripe-derived invoice, subscription, product, affiliate, and commission amount worksheets. /docs/import-templates/stripe-subscription-affiliate-commission/sample.csv
Monthly affiliate revenue input CSV Pre-commission eligible revenue or refund rows with period end, source event, affiliate reference, product, canonical type, and description fields. /docs/import-templates/monthly-affiliate-payout-spreadsheet/sample.csv
Paddle or Chargebee subscription commission CSV Subscription billing commission worksheets with charge, subscription, product/plan, and partner fields. /docs/import-templates/paddle-chargebee-subscription-commission/sample.csv
Generic revenue-share CSV Plain revenue-share files with date, amount, external ID, product/catalog key, payee hint, and optional type. /docs/import-templates/generic-revenue-share/sample.csv

Payout confirmation sample templates

These sample files support reconciliation reference workflows and are not payment execution routes.

Template Use when Sample file
PayPal payout confirmation CSV Reconciling PayPal transaction IDs, payee emails, amounts, currency, paid date, and notes against statement obligations. /docs/import-templates/paypal-payout-confirmation/sample.csv
Wise batch payment confirmation CSV Reconciling Wise transfer IDs, recipient references/emails, paid amounts, currency, and transfer dates. /docs/import-templates/wise-batch-payment-confirmation/sample.csv
Tipalti-style payout confirmation CSV Reconciling supplier IDs, payment IDs, net payment amounts, currency, paid date, and status notes. /docs/import-templates/tipalti-payout-confirmation/sample.csv
Trolley-style payout confirmation CSV Reconciling recipient IDs, payout IDs, transfer amounts, currency, transfer date, and status notes. /docs/import-templates/trolley-payout-confirmation/sample.csv
Generic bank/AP payment confirmation CSV Reconciling vendor IDs, bank/AP references, paid amounts, currency, effective dates, and remittance notes. /docs/import-templates/generic-bank-ap-confirmation/sample.csv

Mapping provenance labels

The import preview labels each mapped field so reviewers can see where the suggestion came from.

Label Meaning Review action
Template The selected template matched the file header to an Allocora field. Review the suggestion and leave it if it matches the source file.
Auto Allocora generic header aliases matched the field without a selected template. Review as a generic suggestion.
User override A user selected a mapping that differs from the template or auto suggestion. Confirm the override is intentional before import.

Examples

Request and response examples

For dated rule migration, replace the example source IDs with your own stable rule ID and a source_external_id from the payee crosswalk. Omitted product, revenue-source, and territory fields intentionally leave that scope unrestricted; set them in the file when the source rule is narrower.

Minimal dated rule migration JSON

{
  "rules": [
    {
      "external_id": "source-rule-001",
      "name": "Historical royalty rule",
      "valid_from": "2026-01-01",
      "open_ended": true,
      "allocations": [
        {"source_external_id": "author-001", "percentage": "25"}
      ]
    }
  ]
}

Equivalent dated rule migration CSV

external_id,name,valid_from,open_ended,source_external_id,percentage
source-rule-001,Historical royalty rule,2026-01-01,true,author-001,25

Troubleshooting

If this does not work

A selected template still shows missing required mappings.

The file headers did not match enough template aliases. Map the required fields manually or download the sample CSV to compare header shape.

A template maps the wrong product field.

Override External Product/Catalog ID during preview. The final mapping is revalidated and persisted with the import batch.

A payout confirmation template appears in docs but not in revenue import.

Payout confirmation templates are confirmation sample shapes for reconciliation evidence. Revenue import exposes revenue templates, while the locked-run payout confirmation import uses the confirmation mapping fields.

Feedback

Was this page helpful?

Send a note if a step is unclear, missing, or out of date.

Email Support

Apply this in a workspace

Start free, use sample data, then replace examples with your own revenue rows when the workflow is clear.

Start Free Browse Docs