How to Migrate Data to your Blnk Ledger

​

Overview

​

Key features for migration

​

Effective date (backdating)

• effective_date: The actual date the transaction happened financially.
• created_at: The system timestamp when the transaction is recorded (set automatically).

​

Bulk transactions

• Atomic processing: All transactions succeed or fail together. If one fails (e.g., due to invalid data), none is processed, ensuring consistency. Ideal for critical migrations where partial success risks discrepancies.
• Independent processing: Each transaction is processed separately. If one fails (e.g., due to formatting errors), others can still succeed. Useful when most data is valid but some issues are expected.
• Asynchronous processing: Process large transaction batches in the background to avoid slowdowns, enabling uninterrupted work during migrations of thousands of transactions.
• Inflight transactions: Generate transactions for later commit or voiding, allowing review and adjustments—like verifying totals or fixing errors—ideal for testing complex migrations before finalizing.

​

Migration strategy

​

Step 1: Prepare your historical data

1. Sort transactions chronologically by their original effective_date values to maintain a clear timeline.
2. Format your data to match the Blnk transaction structure for compatibility.
3. Validate your data (e.g., check for duplicates using unique references).
4. Divide transactions into manageable batches (recommended: 1,000–5,000 per batch) to simplify processing.

​

Step 2: Choose your migration approach

​

Option A: Full historical migration

​

Option B: Balance-forward migration

Important to note: In this approach, set the initial balance adjustment’s effective_date before all subsequent transactions. This sets the correct starting point without being affected by backdated transactions that follow, while backdated transactions will impact the running balance, ensuring the initial balance adjustment is accurate keeps the overall balance correct.

​

Option C: Hybrid approach

​

Step 3: Execute the migration

1. Use the Bulk Transactions API with backdated effective dates to process multiple transactions efficiently.
2. Process asynchronously for large batches to avoid system delays and handle high volumes smoothly.
3. Monitor webhook notifications for completion status to stay informed about progress and issues.
4. Validate balances after each batch to ensure accuracy and catch errors early.

​

Implementation guide

​

Creating bulk backdated transactions

POST http://YOUR_BLNK_INSTANCE_URL/transactions/bulk

{
  "atomic": true,
  "inflight": false,
  "run_async": true,
  "transactions": [
    {
      "amount": 358.90,
      "precision": 100,
      "reference": "migration_2024_001",
      "description": "Invoice payment - Client A",
      "currency": "NGN",
      "source": "@source_account",
      "destination": "@destination_account",
      "effective_date": "2024-09-15T10:30:00Z"
    },
    {
      "amount": 1250.00,
      "precision": 100,
      "reference": "migration_2024_002",
      "description": "Supplier payment",
      "currency": "NGN",
      "source": "@source_account",
      "destination": "@vendor_account",
      "effective_date": "2024-09-18T14:15:00Z"
    }
  ]
}

​

Webhook notification upon successful completion

{
  "event": "bulk_transaction.applied",
  "data": {
    "batch_id": "bulk_c62f200b-905f-4983-a349-cadd279234aa",
    "status": "applied",
    "transaction_count": 1000,
    "timestamp": "2025-03-02T15:30:45+01:00"
  }
}

​

Best practices

1. Phased approach: Migrate data in chronological phases, starting with the oldest transactions. This ensures proper balance calculations and helps isolate any issues.
2. Balance validation: After each migration phase, verify account balances against your source system to ensure accuracy. Use the Historical Balance API to check balances at specific points in time, like this:
   Copy

   GET http://YOUR_BLNK_INSTANCE_URL/balances/{balance_id}/at?timestamp=2024-12-31T23:59:59Z
   

3. Transaction references: Establish a consistent reference naming convention for migrated transactions, such as:
   • migration_{year}_{original_reference}
   • migrate_{source_system}_{original_id}
4. Error handling: For larger migrations, set atomic: false to use independent processing. This prevents one transaction’s failure from stopping the entire batch, keeping the migration running smoothly.
5. Monitoring progress: For large migrations:
   • Track progress by monitoring webhook notifications to stay updated on status.
   • Keep a log of successfully migrated batches for reference.
   • Maintain a record of any failed transactions for retry, ensuring you can address issues quickly.
6. Transaction batching strategy: Group transactions logically:
   • By date range (e.g., monthly batches)
   • By account
   • By transaction type (e.g., payments, transfers, fees)

​

Common migration scenarios

​

Scenario 1

• Import all historical transactions with their original effective dates to maintain a complete record.
• Process transactions in chronological order to ensure accurate financial timelines.
• Use asynchronous (async) processing for large volumes to handle the data efficiently without system delays.

​

Scenario 2

• Prioritize transactions from the current reporting period to focus on recent, critical data.
• Use the effective_date to ensure correct attribution to the financial period, maintaining accurate reporting.
• Validate month-end balances after migration to confirm accuracy and resolve any discrepancies.

​

Scenario 3

• Migrate year-to-date (YTD) transactions with their original effective dates to capture ongoing activity.
• Use inflight transactions for any pending or in-progress transactions, allowing you to review or adjust them before finalizing.
• Verify running balances before finalizing the migration to ensure all data is accurate and consistent.

​

Limitations & considerations

1. Future dates: The effective_date must not exceed the current date. For future entries, use scheduled transactions instead.
2. Performance: Large migration batches should use asynchronous processing to avoid timeouts and ensure smooth processing.
3. Order dependency: When using atomic: true, transactions are processed in the order provided, so ensure the sequence is correct for dependencies.
4. Account preparation: Ensure all required balances (accounts or wallets) exist in Blnk before starting the migration to avoid errors.
5. Currency consistency: Verify that the currencies used in each transactions are consistent to prevent issues during processing.

​

Need help?