Updating status on new invoice through API

Documentation
#1

Good afternoon, I’m hoping someone can assist me with what I believe… is something relatively straight forward.

I’m creating an invoice through the API, and I simply want to set the status of that invoice to “Open” - which then will trigger (I believe) the automatic email of that invoice to the customer.

My invoice is being made correctly, and I’m passing into the array the values for status as mentioned here however it still always comes back as “Draft”.

Below is a preview of my code, using a simply wrapper from github.

$invoices = array();
$invoices['invoice'] = array(
    'contact'                   => $contactId,
    'dated_on'                  => date('Y-m-d'),
    'reference'                 => time(),
    'status'                    => 'Open',
    'send_new_invoice_emails'   => true,
    'send_reminder_emails'      => true,
    'send_thank_you_emails'     => true,
    'payment_terms_in_days'     => 28,
    'invoice_items'             => $lineItems
);

$invoice = $fa->post('invoices', $invoices);

Any help would be greatly appreciated.

Many thanks,

#2

Hi Graeme,

Thanks for posting, and welcome to our API Forum! A newly created invoice will always have a “Draft” status which cannot be edited by you directly. Instead, the status attribute is determined by a range of factors (whether the invoice has been sent to the customer, whether it’s associated with a payment or credit note, etc). If I understand correctly, what you’re trying to do is to send the invoice to a customer, which can be achieved by making a POST request to the /v2/invoices/:id/send_email endpoint as documented here: Email an Invoice. Once the invoice is associated with at least one sent e-mail, its status will automatically change to Open.

I hope this helps, but let me know if you have any further questions.

Best wishes,

Ewa

#3

Thanks for the reply Ewa.

So there is no way to simply trigger the invoice to send, in the same way it does when you click “Send by Email” on the website?

I simply want to send it, to the email for the contact that is already stored in FreeAgent…

My worry is that I need one API call to create the invoice, another API call to fetch the contact details, then another API call to “send the invoice”.

We’re planning on using FreeAgent to handle all our billing for hundreds of invoices that happen at specific dates in the month - I’m worried that if my approach mentioned is correct, we will hit API rate limits.

EDIT: I’ve just seen this post - which says you can post empty options through, however that doesn’t work for me, I have to fill in all fields. Including the message body which is far from ideal :frowning:

Many thanks,

#4

Hi Graeme,

What I’d recommend in this case would be creating an invoice e-mail template and using that when making a request to the send_email endpoint, just as described in this forum thread: Emailing Invoices using the Contact's email address. This will allow you to have a minimal request body when sending invoice e-mails, i.e.:

{
  "invoice": {
      "email": { 
         "use_template": true
      }
   }
}

It looks like the use_template option isn’t mentioned in our main documentation, so I’ll make sure it gets added – thank you for helping us improve our docs with your query, and I hope this solution works for you! :smiley:

Best wishes,

Ewa

1 Like
#5

Ewa - this is perfect! Exactly what I was looking for - thank you!

In regards to my other comment (lots of API calls) do you happen to know if in a single API call you can create more than one invoice/email invoice request?

Many thanks,

#6

Hi again Graeme :wave: ,

I’m afraid currently our API only allows you to create/send invoices one by one, which means you will need to make 2 calls for each one (so you’ll be able to create and send 60 invoices every minute – we have a rate limit of 120 user requests per minute). I wonder whether our recurring invoices would be of any use to you? Unfortunately it’s not yet possible to manage them through the API, however if you have any clients that you bill the same amount at regular intervals, you could set up recurring invoice profiles for them in your FreeAgent account.

Best wishes,

Ewa