Credit_note_reconciliation

[benb-j]

Hi, could you offer some advice on credit notes and their reconciliation?
If I want to cancel an invoice (or part of an invoice) without writing this off as bad debt, I thought I should create a credit note for this amount. My interpretation of the workflow required:

1. create the credit note, assigned to the correct contact, thus:
   POST https://api.sandbox.freeagent.com/v2/credit_notes
   {
   “credit_note”: {
   “contact”: “https://api.sandbox.freeagent.com/v2/contacts/95318”,
   “dated_on”: “2021-02-01”,
   “payment_terms_in_days”: 0,
   “credit_note_items”: [{“description”: “Excess on insurance”, “price”: -100, “quantity”: 1}]
   }
   }

2. transition the credit note to sent
   PUT https://api.sandbox.freeagent.com/v2/credit_notes/203626/transitions/mark_as_sent

3. create a credit note reconciliation, to tie the credit note to the relevant invoice, thus:
   POST https://api.sandbox/freeagent.com/v2/credit_note_reconciliations
   {
   “credit_note_reconciliation”: {
   “gross_value”: 100.0,
   “invoice”:“https://api.sandbox.freeagent.com/v2/invoices/198330”,
   “credit_note”:“https://api.sandbox.freeagent.com/v2/credit_notes/203626”
   }
   }

All elements appear to be created properly. However, this does not appear to change the invoice, specifically the “due_value”, leaving no evidence that I can see that the credit note has been applied.
Am I doing this all wrong? It seems rather long-winded and perhaps there’s a more elegant way?
I’d be grateful for some pointers.

[colingemmell]

Hi @benb-j

From what I can see you are following the right steps. Here is how I reconciled part of an invoice with a credit note in my account:

Create an invoice for a contact

curl -v -XPOST "https://api.freeagent.com/v2/invoices" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  --data @- << EOH
{
  "invoice":{
    "contact":"https://api.freeagent.com/v2/contacts/9938375",
    "dated_on":"2021-03-10",
    "due_on":"2021-04-10",
    "reference":"API_REF_001",
    "payment_terms_in_days":30,
    "invoice_items":[
      {
        "description":"Hammers",
        "item_type":"Hours",
        "price":"100.0",
        "quantity":"1.0"
      }
    ]
  }
}
EOH

This created my invoice with id https://api.freeagent.com/v2/invoices/42587001

I marked the invoice as sent

curl -v -XPUT "https://api.freeagent.com/v2/invoices/42587001/transitions/mark_as_sent" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-type: application/json" \
  -H "Accept: application/json"

Then created a credit note

curl -v -XPOST "https://api.freeagent.com/v2/credit_notes" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  --data @- << EOH
{
  "credit_note":{
    "contact":"https://api.freeagent.com/v2/contacts/9938375",
    "dated_on":"2021-03-10",
    "due_on":"2021-04-10",
    "reference":"CREDIT API_REF_001",
    "credit_note_items":[
      {
        "description":"Hammers",
        "item_type":"Hours",
        "price":"-50.0",
        "quantity":"1.0"
      }
    ]
  }
}
EOH

This created the credit note with id https://api.freeagent.com/v2/credit_notes/42587231

The I marked the credit note as sent as well

curl -v -XPUT "https://api.freeagent.com/v2/credit_notes/42587231/transitions/mark_as_sent" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-type: application/json" \
  -H "Accept: application/json"

Finally I applied the credit note to the invoice with credit note reconciliation

curl -v -XPOST "https://api.freeagent.com/v2/credit_note_reconciliations" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  --data @- << EOH
{
  "credit_note_reconciliation": {
    "gross_value":"50",
    "invoice":"https://api.freeagent.com/v2/invoices/42587001",
    "credit_note":"https://api.freeagent.com/v2/credit_notes/42587231"
  }
}
EOH

When I the retrieved the invoice it come back with a paid_value the same as the reconciliation (reduced for brevity)

{
  "invoice": {
    "url": "https://api.freeagent.com/v2/invoices/42587001",
    "contact": "https://api.freeagent.com/v2/contacts/9938375",
    "dated_on": "2021-03-10",
    "due_on": "2021-04-09",
    "reference": "API_REF_001",
    "total_value": "120.0",
    "paid_value": "50.0",
    "due_value": "70.0",
  }
}

And this is reflected in the UI as well.

I take you point it is quite long-winded and unfortunately there is no other elegant way of doing this via the API at the moment.
I will raise a feature request to see if we can do something to reduce the steps in the future.

Hope that helps and feel free to reply if you need anymore help.

Regards
Colin Gemmell (FreeAgent)