Accounts Payable

Recurring Payments

API Reference

Recurring payments allow your customers to make payments on a custom schedule from a single invoice template.

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.
POST
/invoice-template
1import datetime
2
3from mercoa import Mercoa
4from mercoa.invoice_types import (
5    InvoiceLineItemCreationRequest,
6    InvoiceTemplateCreationRequest,
7    PaymentDestinationOptions_Check,
8    PaymentSchedule_Monthly,
9)
10
11client = Mercoa(
12    token="YOUR_TOKEN",
13)
14client.invoice_template.create(
15    request=InvoiceTemplateCreationRequest(
16        status="NEW",
17        amount=100.0,
18        currency="USD",
19        invoice_date=datetime.datetime.fromisoformat(
20            "2021-01-01 00:00:00+00:00",
21        ),
22        due_date=datetime.datetime.fromisoformat(
23            "2021-01-13 00:00:00+00:00",
24        ),
25        deduction_date=datetime.datetime.fromisoformat(
26            "2021-01-10 00:00:00+00:00",
27        ),
28        payment_schedule=PaymentSchedule_Monthly(
29            repeat_on_day=10,
30            ends=datetime.datetime.fromisoformat(
31                "2021-01-01 00:00:00+00:00",
32            ),
33        ),
34        invoice_number="INV-123",
35        note_to_self="Monthly recurring payment",
36        payer_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
37        payment_source_id="pm_4794d597-70dc-4fec-b6ec-c5988e759769",
38        vendor_id="ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
39        payment_destination_id="pm_5fde2f4a-facc-48ef-8f0d-6b7d087c7b18",
40        payment_destination_options=PaymentDestinationOptions_Check(
41            delivery="MAIL",
42            print_description=True,
43        ),
44        line_items=[
45            InvoiceLineItemCreationRequest(
46                amount=100.0,
47                currency="USD",
48                description="Product A",
49                name="Product A",
50                quantity=1.0,
51                unit_price=100.0,
52                category="EXPENSE",
53                service_start_date=datetime.datetime.fromisoformat(
54                    "2021-01-01 00:00:00+00:00",
55                ),
56                service_end_date=datetime.datetime.fromisoformat(
57                    "2021-01-31 00:00:00+00:00",
58                ),
59                metadata={"key1": "value1", "key2": "value2"},
60                gl_account_id="600394",
61            )
62        ],
63        creator_entity_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
64        creator_user_id="user_e24fc81c-c5ee-47e8-af42-4fe29d895506",
65    ),
66)
  1. Ensure the invoice template has all the necessary information to create recurring invoices:
    • Payment Schedule (set by the paymentSchedule field)
    • First Payment Date (set by the deductionDate field)
    • All other fields required to schedule a normal invoice
  2. 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.

These invoices are created in the SCHEDULED state, and are paid on the scheduled date with no further action required. Once a recurring invoice moves to PENDING on its deductionDate, Mercoa automatically creates the next recurring invoice with the next deductionDate in the SCHEDULED state.

Viewing Recurring Invoices

To view recurring invoices created from an invoice template, filter on invoices with the invoiceTemplateId parameter on the Invoice Search API.

Stopping Recurring Payments

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