Credit Memo Export Profile

The Credit Memo Export Profile exports Magento credit memos to FreeAgent as credit notes. This profile ensures that refunds and returns are accurately reflected in your FreeAgent accounting records.

Overview

Profile Type ID: freeagent_creditmemo_export Direction: Magento → FreeAgent Purpose: Export Magento credit memos as FreeAgent credit notes

What Gets Exported

• Credit Memos: Complete credit memo data as FreeAgent credit notes
• Line Items: Refunded product line items with quantities and amounts
• Contacts: Customer information (creates/links FreeAgent contacts)
• Shipping Refunds: Shipping refund amounts as credit note line items
• Tax: Tax adjustments and amounts
• Refund Totals: Complete financial breakdown of the refund

Primary Use Cases

• Automated Refund Tracking: Automatically create FreeAgent credit notes for Magento refunds
• Financial Reconciliation: Ensure refund data matches between Magento and FreeAgent
• Tax Reporting: Maintain accurate tax adjustment records in FreeAgent
• Audit Trail: Complete financial history across both platforms

Export Workflow

Credit Memo Created (Magento)
         ↓
Credit Memo Export Profile Runs
         ↓
Contact Created/Updated in FreeAgent
         ↓
Credit Note Created in FreeAgent
         ↓
Credit Note Email Sent (Optional)
         ↓
Status Synced Back (Credit Memo Import)

Contact Dependency

Similar to Invoice Export, the Credit Memo Export pipeline automatically handles contact creation. If the customer doesn't exist as a FreeAgent contact, the pipeline will create the contact first.

Configuration Reference

All configuration options are found at: Admin Panel > Byte8 > FreeAgent > Profiles > [Your Credit Memo Export Profile]

1. Client Configuration

Client

Field: client_id Type: Select (Required) Scope: Global

Select the FreeAgent client configuration to use for this credit memo export profile.

Actions:

• Edit - Modify existing client configuration
• New Client - Create a new FreeAgent client connection
• Collect Configuration Data - Fetch configuration from FreeAgent
• Delete Configuration Data - Remove cached configuration data

---

2. Schedule Configuration

Enable Schedule

Field: status Type: Checkbox Default: Enabled Scope: Global

Enable automatic credit memo export processing via the scheduler.

When to Enable:

• Production environments with regular refund processing
• Automated financial record keeping
• Real-time or near-real-time refund tracking

When to Disable:

• Manual review before exporting refunds
• Testing and configuration phases

Schedule

Field: schedule_id Type: Select (Required when enabled) Scope: Global

Select the cron schedule for automatic credit memo export.

Common Schedules:

• Every 15 minutes - Standard credit memo sync (recommended)
• Every 30 minutes - Low-volume stores
• Every 60 minutes - Minimal refund activity
• Custom - Define your own cron expression

Recommended: Every 15-30 minutes. Credit memos are typically less frequent than invoices, so a longer interval is acceptable.

Process Batch Size

Field: process_batch_size Type: Number Default: 50 Scope: Global

Number of credit memos processed per batch.

Recommended settings:

• 50 (default) - Optimal for most stores
• 25-30 - Complex credit memos with many line items
• 75-100 - Simple credit memos with high memory

Enable Automatic Retry on Failure

Field: enable_retry_on_failure Type: Checkbox Default: Disabled Scope: Global

Automatically retry failed credit memo exports on subsequent schedule runs.

Maximum Retry Attempts

Field: retry_max_attempts Type: Number Default: 3 Scope: Global

Maximum number of retry attempts for failed credit memo exports.

---

3. HTTP API Configuration

Controls how the profile interacts with the FreeAgent API.

API Behavior

• Create New: Only create credit notes that don't exist in FreeAgent
• Update Existing: Only update credit notes that already exist
• Create and Update: Create new and update existing (recommended)

---

Processing Pipeline

The Credit Memo Export service uses a multi-stage processor pipeline:

Generators

Generator	Sort Order	Purpose
Contact Data	10	Generate contact payload for credit memo customer
Credit Memo Data	20	Generate credit note payload from credit memo data
Shipping Items	25	Generate shipping refund line items

Processors

Processor	Sort Order	Purpose
Contact Creation	40	Create or link FreeAgent contact
Credit Memo Processing	45	Create or update credit note in FreeAgent
Email Sending	50	Trigger credit note email delivery from FreeAgent

Post-Processors

Post-Processor	Sort Order	Purpose
Queue & Log	100	Update queue status and log processing results

Entity Data

Credit memo sync data is tracked in the freeagent_creditmemo_entity table:

Column	Type	Description
entity_id	INT	Primary key
creditmemo_id	VARCHAR	FreeAgent credit note ID
order_id	INT	Related Magento order ID
reference	VARCHAR	FreeAgent reference number
status	VARCHAR	Sync status
queue_status	VARCHAR	Queue processing status
message	TEXT	Sync messages (JSON)
metadata	TEXT	Additional data (JSON)
collected_at	DATETIME	When data was collected
processed_at	DATETIME	When data was last processed

CLI Commands

# Collect credit memos from FreeAgent
bin/magento fa_creditmemo:collect

# Export all pending credit memos
bin/magento fa_creditmemo:export

# Export specific credit memos by profile ID
bin/magento fa_creditmemo:export --profile=1

# Export specific credit memo by entity ID
bin/magento fa_creditmemo:export --id=42

# Dry run (preview without sending)
bin/magento fa_creditmemo:export --dry-run

# Import credit memo status from FreeAgent
bin/magento fa_creditmemo:import

Best Practices

1. Ensure invoices exist first - Credit notes in FreeAgent are typically linked to existing invoices. Export invoices before credit memos.

2. Monitor refund accuracy - Verify that credit note amounts in FreeAgent match Magento credit memos, especially for partial refunds.

3. Handle shipping refunds - Verify shipping refund amounts are correctly represented as credit note line items.

4. Use a reasonable schedule - Credit memos are typically less frequent than orders. A 15-30 minute schedule is usually sufficient.

5. Test with sandbox - Always test credit memo export in FreeAgent sandbox before enabling on production.

Troubleshooting

Credit Memos Not Exporting

Problem: Scheduled export runs but no credit memos are exported

Solutions:

1. Verify the profile schedule is enabled
2. Check that credit memos exist in the queue
3. Review var/log/freeagent/creditmemo.log for errors
4. Verify FreeAgent API credentials are valid
5. Test with CLI: bin/magento fa_creditmemo:export --dry-run

Contact Creation Fails

Problem: Credit memo export fails because contact creation fails

Solutions:

1. Check customer data for required fields
2. Review var/log/freeagent/contact.log for API errors
3. Verify the contact export profile is functioning correctly
4. Check for duplicate contacts in FreeAgent

Incorrect Refund Amounts

Problem: FreeAgent credit notes show incorrect amounts

Solutions:

1. Verify the credit memo data in Magento is correct
2. Check shipping refund calculations
3. Review tax adjustment handling
4. Compare line item amounts between Magento and FreeAgent

Linked Invoice Not Found

Problem: Credit note creation fails because the linked invoice doesn't exist in FreeAgent

Solutions:

1. Ensure invoice export ran before credit memo export
2. Check the freeagent_invoice_entity table for the related order
3. Manually run invoice export for the specific order first

Next Steps

1. Contact Export - Configure contact synchronization
2. Invoice Export - Configure invoice processing
3. CLI Commands - Full CLI reference

Related Documentation

• About Profiles
• Client Configuration
• Profile Configuration