Recurring Payments

API Reference

Recurring payments allow your customers to make payments on a custom schedule from a single invoice template. Once set up, the system automatically creates and processes invoices according to your specified payment schedule.

How Recurring Payments Work

Recurring payments are created by creating an invoice template and then updating it to the SCHEDULED status.

Invoice templates create invoices on a custom schedule to pay each recurring payment. To use recurring payments, you must:

1. Create an invoice template.

1
curl -X POST https://api.mercoa.com/invoice-template \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "amount": 100,
6
  "creatorEntityId": "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
7
  "creatorUserId": "user_e24fc81c-c5ee-47e8-af42-4fe29d895506",
8
  "currency": "USD",
9
  "deductionDate": "2021-01-10T00:00:00Z",
10
  "dueDate": "2021-01-13T00:00:00Z",
11
  "invoiceDate": "2021-01-01T00:00:00Z",
12
  "invoiceNumber": "INV-123",
13
  "lineItems": [
14
    {
15
      "amount": 100,
16
      "category": "EXPENSE",
17
      "currency": "USD",
18
      "description": "Product A",
19
      "glAccountId": "600394",
20
      "metadata": {
21
        "key1": "value1",
22
        "key2": "value2"
23
      },
24
      "name": "Product A",
25
      "quantity": 1,
26
      "serviceEndDate": "2021-01-31T00:00:00Z",
27
      "serviceStartDate": "2021-01-01T00:00:00Z",
28
      "unitPrice": 100
29
    }
30
  ],
31
  "noteToSelf": "Monthly recurring payment",
32
  "payerId": "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
33
  "paymentDestinationId": "pm_5fde2f4a-facc-48ef-8f0d-6b7d087c7b18",
34
  "paymentDestinationOptions": {
35
    "type": "check",
36
    "delivery": "MAIL",
37
    "printDescription": true
38
  },
39
  "paymentSchedule": {
40
    "type": "monthly",
41
    "repeatOnDay": 10,
42
    "ends": "2021-01-01T00:00:00Z"
43
  },
44
  "paymentSourceId": "pm_4794d597-70dc-4fec-b6ec-c5988e759769",
45
  "status": "NEW",
46
  "vendorId": "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d"
47
}'

2. Ensure the invoice template has all the necessary information to create recurring invoices:
   • Payment Schedule (set by the paymentSchedule field) - defines the frequency and pattern of payments
   • First Payment Date (set by the deductionDate field) - when the first recurring payment should be processed
   • All other fields required to schedule a normal invoice
3. Update the invoice template to the SCHEDULED status.

Once the invoice template reaches the SCHEDULED status, it remains there and begins creating recurring invoices according to the template’s paymentSchedule and deductionDate fields.

Payment Schedule Types

Recurring payments support several schedule types:

Daily

Payments occur every day or every N days:

1
{
2
  "type": "daily",
3
  "repeatEvery": 1,
4
  "ends": "2024-12-31T00:00:00Z"
5
}

Weekly

Payments occur on specific days of the week:

1
{
2
  "type": "weekly",
3
  "repeatOn": ["1", "3", "5"], // Monday, Wednesday, Friday
4
  "repeatEvery": 1,
5
  "ends": "2024-12-31T00:00:00Z"
6
}

Monthly

Payments occur on a specific day of the month:

1
{
2
  "type": "monthly",
3
  "repeatOnDay": 15, // 15th of each month
4
  "repeatEvery": 1,
5
  "ends": "2024-12-31T00:00:00Z"
6
}

Yearly

Payments occur on a specific date each year:

1
{
2
  "type": "yearly",
3
  "repeatOnDay": 1,
4
  "repeatOnMonth": 1, // January 1st
5
  "repeatEvery": 1,
6
  "ends": "2024-12-31T00:00:00Z"
7
}

Invoice Creation Timing

When Invoices Are Created

1. First Invoice: When you update an invoice template to SCHEDULED status, the first recurring invoice is immediately created with the deductionDate specified in the template.

2. Subsequent Invoices: New invoices are created automatically when the previous invoice moves to PENDING status on its deductionDate. This ensures there’s always one upcoming invoice in the SCHEDULED state.

Invoice Status Flow

• SCHEDULED: Invoice is created and waiting for its payment date
• PENDING: Payment date has arrived, invoice is being processed
• PAID: Payment has been successfully processed
• FAILED: Payment processing failed

Next Invoice Creation

The system automatically calculates the next deductionDate based on the payment schedule and creates the next invoice. This process continues until:

• The payment schedule reaches its end date
• The payment schedule reaches its maximum number of occurrences
• The invoice template is updated to CANCELED status

Invoice Numbering for Recurring Invoices

When a recurring invoice is created from a template, its invoice number is automatically incremented based on the template’s invoice number. For example, if the template’s invoice number is INV-001, the first recurring invoice will be INV-002, the next will be INV-003, and so on. The incrementing logic will preserve leading zeros and common patterns (e.g., INV-099 → INV-100).

• If the template’s invoice number does not end in a number, -001 will be appended (e.g., MONTHLY → MONTHLY-001).
• The system ensures that each generated invoice number is unique for the same vendor or payer.

Editing Invoice Numbers

You can edit the invoice number of any scheduled recurring invoice after it is created. Changing the invoice number for one invoice does not affect the numbering of future or past invoices. Each invoice’s number is independent once created.

• Editing the invoice number is allowed for scheduled recurring invoices (status SCHEDULED and created from a template).
• The template’s invoice number is only used as a base for generating new recurring invoices; editing a single invoice’s number does not change the template or future invoices.

Approvals for Recurring Payments

Template Approval

When you create an invoice template, it follows the same approval workflow as regular invoices. The template must be approved before it can be scheduled to create recurring invoices. Approval rules (approvers, approval workflow, etc.) apply to the invoice template itself.

Generated Invoice Approval

Once an invoice template is approved and scheduled, all recurring invoices created from that template are automatically approved and do not require additional approval. This ensures that recurring payments can proceed without manual intervention for each invoice.

Note: If you update the invoice template after it’s been scheduled, the template may need to be re-approved depending on the changes made, but existing generated invoices remain approved.

Updating Created Invoices

Individual Invoice Updates

You can update individual recurring invoices using the Invoice Update API. This allows you to modify:

• Amount, currency, and line items
• Payment source and destination
• Due date and deduction date
• Approvers and approval workflow
• Notes and metadata
• Status (with restrictions)

Important: Updating an individual invoice does not affect the invoice template or future recurring invoices.

Invoice Template Updates

Updating the invoice template affects future recurring invoices but not already-created invoices. You can modify:

• Payment schedule (affects future invoices only)
• Amount, currency, and line items (affects future invoices only)
• Payment source and destination (affects future invoices only)
• Template status (SCHEDULED, CANCELED, etc.)

Bulk Updates

To update multiple recurring invoices at once, you can:

1. Update the template - affects all future invoices
2. Use the Invoice Search API to find specific invoices and update them individually
3. Use webhooks to react to invoice events and make programmatic updates

Viewing Recurring Invoices

Finding Recurring Invoices

To view recurring invoices created from an invoice template, use the Invoice Search API with the invoiceTemplateId parameter:

$
GET /invoice?invoiceTemplateId=invt_12345678-1234-1234-1234-123456789abc

Invoice Template Details

Each recurring invoice includes:

• recurringTemplateId: Links the invoice to its template
• isRecurringTemplate: Set to false for created invoices
• nextDeductionDate: Shows when the next invoice will be created (on the template)

Template Status Tracking

The invoice template maintains:

• nextDeductionDate: When the next recurring invoice will be created
• status: Current template status (SCHEDULED, CANCELED, etc.)
• paymentSchedule: The recurring schedule configuration

Identifying Recurring Invoices

When an invoice is created from a recurring template, the invoice response will include a recurringTemplateId field that contains the ID of the template that created it. This field is only present for invoices that were created from a recurring template.

1
{
2
  "id": "in_12345678-1234-1234-1234-123456789abc",
3
  "status": "SCHEDULED",
4
  "amount": 100.00,
5
  "recurringTemplateId": "invt_87654321-4321-4321-4321-cba987654321",
6
  // ... other invoice fields
7
}

Stopping Recurring Payments

Cancel the Template

To stop an invoice template from creating more invoices, use the Update Invoice Template API to update the template to the CANCELED status:

1
{
2
  "status": "CANCELED"
3
}

End Date in Payment Schedule

You can also set an end date in the payment schedule when creating the template:

1
{
2
  "paymentSchedule": {
3
    "type": "monthly",
4
    "repeatOnDay": 15,
5
    "ends": "2024-12-31T00:00:00Z"
6
  }
7
}

Maximum Occurrences

Set a maximum number of payments:

1
{
2
  "paymentSchedule": {
3
    "type": "monthly",
4
    "repeatOnDay": 15,
5
    "ends": 12 // Stop after 12 payments
6
  }
7
}

Best Practices

Setting Up Recurring Payments

1. Test with a small amount first to ensure the schedule works as expected
2. Use specific end dates rather than unlimited recurring payments
3. Monitor the first few payments to ensure they process correctly
4. Set up webhooks to track payment events and failures

Managing Recurring Payments

1. Regular monitoring of payment success rates
2. Update payment methods before they expire
3. Communicate changes to customers when updating templates
4. Keep templates simple - complex schedules can be harder to debug

Webhooks and Events

Recurring payments trigger various events that you can monitor via webhooks:

• Invoice Created: When a new recurring invoice is created
• Invoice Status Changed: When an invoice moves between statuses
• Payment Processed: When a payment is successfully completed
• Payment Failed: When a payment fails to process

Set up webhooks to automatically handle these events and maintain your recurring payment system.