Recurring profiles are templates that generate invoices on a recurring basis.

Staff access

Staff do not have access to the API calls listed below.

recurring.create

Create a new recurring profile.

The method arguments are nearly identical to invoice.create, but include four new fields:

• occurrences
  • Number of invoices to generate, with zero (0) being infinite
• frequency
  • Rate at which to generate invoices - can be one of ‘weekly’, ‘2 weeks’, ‘4 weeks’, ‘monthly’, ‘2 months’, ‘3 months’, ‘6 months’, ‘yearly’, ‘2 years’
• stopped
  • This profile is no longer generating invoices (1 - stopped, 0 - active)
• send_email
  • Notify client by email each time a new invoice is generated (1 or 0)
• send_snail_mail
  • Send a copy of your invoice by snail mail, each time it’s generated (1 or 0)

Other Notes

• New profiles must begin tomorrow at the earliest

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="recurring.create">
  <recurring>
    <client_id>40</client_id>              # Client to generate invoices for

    <date>2007-09-23</date>                # Must be in the future
    <po_number>2314</po_number>            # Purchase order number (Optional)
    <discount>10</discount>                # Percent discount (Optional)
    <occurrences>1</occurrences>           # Number of invoices to generate; 0 infinite (default 1)
    <frequency>monthly</frequency>         # One of 'weekly', '2 weeks', '4 weeks', 'monthly', '2 months', '3 months', '6 months', 'yearly', '2 years'

    <send_email>1</send_email>              # Send email notification (Default 1)
    <send_snail_mail>0</send_snail_mail>    # Send copy by snail mail (Default 0)

    <notes>Due upon receipt.</notes>       # (Optional)
    <terms>Payment due in 30 days.</terms> # (Optional)

    <first_name>John</first_name>           # (Optional)
    <last_name>Smith</last_name>            # (Optional)
    <organization>ABC Corp</organization>   # (Optional)
    <p_street1></p_street1>                 # (Optional)
    <p_street2></p_street2>                 # (Optional)
    <p_city></p_city>                       # (Optional)
    <p_state></p_state>                     # (Optional)
    <p_country></p_country>                 # (Optional)
    <p_code></p_code>                       # (Optional)

    <lines>
      <line>
        <name>Yard Work</name>
        <description>Mowed the lawn.</description>
        <unit_cost>10</unit_cost>
        <quantity>4</quantity>
        <tax1_name>GST</tax1_name>
        <tax2_name>PST</tax2_name>
        <tax1_percent>8</tax1_percent>
        <tax2_percent>6</tax2_percent>
      </line>
    </lines>
  </recurring>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok">
  <recurring_id>21</recurring_id>
</response>

recurring.update

Update an existing recurring profile. Only supplied fields will be changed.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="recurring.update">
  <recurring>
    <recurring_id>21</recurring_id>

    ...
  </recurring>
</request>

recurring.get

Return the details of an existing recurring profile.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="recurring.get">
  <recurring_id>20</recurring_id>
</request>

recurring.delete

Delete a recurring profile. Once deleted, it will no longer generate invoices.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="recurring.delete">
  <recurring_id>20</recurring_id>
</request>

recurring.list

Returns a list of recurring profile summaries. Results are ordered by descending recurring_id.

Note: A list request that returns no results (i.e. page 999), will return an empty result set, not an error.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="recurring.list">
  <client_id>3</client_id>            # Filter by client (Optional)

  <page>1</page>                      # Page number to return, default is 1 (Optional)
  <per_page>10</per_page>             # Number of results per page, default is 25 (Optional)
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok">
  <recurrings page="1" per_page="10" pages="5" total="48">
    <recurring>
      <recurring_id>344</recurring_id>
      <client_id>3</client_id>
      <organization>ABC Corp</organization>
      <amount>45.6</amount>
      <date>2007-06-23</date>
    </recurring>
    ...
  </recurrings>
</response>