NAV Navbar
cURL .NET Java Go PHP Python Ruby

Credit Notes

A credit note represents a balance you owe to a Customer. Like invoices, each credit note has a collection of line items that detail the products or services that are being credited to the customer. You can think of credit notes as negative invoices, however, all of the amounts should be positive.

Credit notes must be issued against an existing invoice. The credit note will be applied to the balance on the invoice first. Any remaining balance should be credited to the customer.

Credit notes with a balance can be marked as paid by issuing a credit for the credit note using Payments. Once the sum of all applications for a credit note is greater than or equal to the total then the credit note will be considered paid in full.

Credit Note Object

Attributes 

{
    "balance": 51.15,
    "closed": false,
    "created_at": 1415229884,
    "currency": "usd",
    "customer": 15444,
    "date": 1416290400,
    "discounts": [],
    "draft": false,
    "id": 2048,
    "items": [
        {
            "amount": 45,
            "catalog_item": null,
            "description": null,
            "discountable": true,
            "discounts": [],
            "id": 7,
            "metadata": [],
            "name": "Copy Paper, Case",
            "object": "line_item",
            "quantity": 1,
            "taxable": true,
            "taxes": [],
            "type": "product",
            "unit_cost": 45
        },
        {
            "amount": 10,
            "catalog_item": "delivery",
            "description": null,
            "discountable": true,
            "discounts": [],
            "id": 8,
            "metadata": [],
            "name": "Delivery",
            "object": "line_item",
            "quantity": 1,
            "taxable": true,
            "taxes": [],
            "type": "service",
            "unit_cost": 10
        }
    ],
    "metadata": [],
    "name": null,
    "notes": null,
    "number": "CN-0016",
    "object": "credit_note",
    "paid": false,
    "pdf_url": "https://dundermifflin.invoiced.com/credit_notes/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "purchase_order": null,
    "status": "open",
    "subtotal": 55,
    "taxes": [
        {
            "amount": 3.85,
            "id": 20554,
            "object": "tax",
            "tax_rate": null
        }
    ],
    "total": 51.15,
    "updated_at": 1415229884,
    "url": "https://dundermifflin.invoiced.com/credit_notes/IZmXbVOPyvfD3GPBmyd6FwXY"
}
Parameter Type Description
id integer The credit note's unique ID
object string Object type, credit_note
customer integer Customer ID
name string Credit note name for internal use, defaults to "Credit Note"
number string The reference number assigned to the credit note for use in the dashboard
purchase_order string The customer's purchase order number
currency string 3-letter ISO code
draft boolean When false, the credit note is considered outstanding, or when true, the credit note is a draft
closed boolean When true, a credit note is closed and considered bad debt. No further payments are allowed.
paid boolean Indicates whether a credit note has been paid in full
status string Credit note state, one of draft, open, paid, closed, voided
date timestamp Credit note date
items array Collection of Line Items
notes string Additional notes displayed on credit note
subtotal number Subtotal
discounts array Collection of Discounts
taxes array Collection of Taxes
total number Total
balance number Balance owed
url string URL to view the credit note in the billing portal
pdf_url string URL to download the credit note as a PDF
created_at timestamp Timestamp when created
updated_at timestamp Timestamp when updated
metadata object A hash of key/value pairs that can store additional information about this object.

Create a credit note 

curl "https://api.invoiced.com/credit_notes" \
  -u {API_KEY}: \
  -d customer=15444 \
  -d items[0][name]="Copy paper, Case" \
  -d items[0][quantity]=1 \
  -d items[0][unit_cost]=45 \
  -d items[1][catalog_item]="delivery" \
  -d items[1][quantity]=1 \
  -d taxes[0][amount]=3.85
invoiced.CreditNote.create(
  :customer => 15444,
  :items => [
    {
      :name => "Copy paper, Case",
      :quantity => 1,
      :unit_cost => 45
    },
    {
      :catalog_item => "delivery",
      :quantity => 1
    }
  ],
  :taxes => [
    {
      :amount => 3.85
    }
  ]
)
<?php

$creditNote = $invoiced->CreditNote->create([
  'customer' => 15444,
  'items' => [
    [
      'name' => "Copy paper, Case",
      'quantity' => 1,
      'unit_cost' => 45
    ],
    [
      'catalog_item' => "delivery",
      'quantity' => 1
    ]
  ],
  'taxes' => [
    [
      'amount' => 3.85
    ]
  ]
]);
client.CreditNote.create(
  customer=15444,
  items=[
    {
      'name': "Copy paper, Case",
      'quantity': 1,
      'unit_cost': 45
    },
    {
      'catalog_item': "delivery",
      'quantity': 1
    }
  ],
  taxes=[
    {
      'amount': 3.85
    }
  ]
)
CreditNote creditNote = invoiced.newCreditNote();
creditNote.customer = 15444L;
LineItem[] items = new LineItem[2];
items[0] = new LineItem();
items[0].name = "Copy paper, Case";
items[0].quantity = 1D;
items[0].unitCost = 45D;
items[1] = new LineItem();
items[1].item = "delivery";
items[1].quantity = 1D;
Tax[] taxes = new Tax[1];
taxes[0] = new Tax();
taxes[0].amount = 3.85D;
creditNote.items = items;
creditNote.taxes = taxes;
creditNote.create();
var creditNote = invoiced.NewCreditNote();
creditNote.Customer = 15444;
LineItem[] items = new LineItem[2];
items[0] = new LineItem();
items[0].Name = "Copy paper, Case";
items[0].Quantity = 1;
items[0].UnitCost = 45;
items[1] = new LineItem();
items[1].Item = "delivery";
items[1].Quantity = 1;
Tax[] taxes = new Tax[1];
taxes[0] = new Tax();
taxes[0].amount = 3.85;
creditNote.Items = items;
creditNote.Taxes = taxes;
creditNote.Create();
creditNote, err := creditNote.Create(&invoiced.CreditNoteRequest{
  Customer: invoiced.Int64(15444),
  Items: []*invoiced.LineItemRequest{
    {
      Name: invoiced.String("Copy paper, Case"),
      Quantity: invoiced.Float64(1),
      UnitCost: invoiced.Float64(45),
    },
    {
      Item: invoiced.String("delivery"),
      Quantity: invoiced.Float64(1),
    },
  },
  Taxes: []*invoiced.TaxRequest{
    {
      Amount: invoiced.Float64(3.85),
    },
  },
})

The above command returns JSON structured like this:

{
    "balance": 51.15,
    "closed": false,
    "created_at": 1415229884,
    "currency": "usd",
    "customer": 15444,
    "date": 1416290400,
    "discounts": [],
    "draft": false,
    "id": 2048,
    "items": [
        {
            "amount": 45,
            "catalog_item": null,
            "description": null,
            "discountable": true,
            "discounts": [],
            "id": 7,
            "metadata": [],
            "name": "Copy Paper, Case",
            "object": "line_item",
            "quantity": 1,
            "taxable": true,
            "taxes": [],
            "type": "product",
            "unit_cost": 45
        },
        {
            "amount": 10,
            "catalog_item": "delivery",
            "description": null,
            "discountable": true,
            "discounts": [],
            "id": 8,
            "metadata": [],
            "name": "Delivery",
            "object": "line_item",
            "quantity": 1,
            "taxable": true,
            "taxes": [],
            "type": "service",
            "unit_cost": 10
        }
    ],
    "metadata": [],
    "name": null,
    "notes": null,
    "number": "CN-0016",
    "object": "credit_note",
    "paid": false,
    "pdf_url": "https://dundermifflin.invoiced.com/credit_notes/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "purchase_order": null,
    "status": "open",
    "subtotal": 55,
    "taxes": [
        {
            "amount": 3.85,
            "id": 20554,
            "object": "tax",
            "tax_rate": null
        }
    ],
    "total": 51.15,
    "updated_at": 1415229884,
    "url": "https://dundermifflin.invoiced.com/credit_notes/IZmXbVOPyvfD3GPBmyd6FwXY"
}

Create a new credit note with this endpoint.

HTTP Request

POST /credit_notes

Attributes

Parameter Type Description
customer integer Customer ID - required
name string Credit note name for internal use, defaults to "Credit Note"
number string The reference number assigned to the credit note, defaults to next # in auto-numbering sequence
purchase_order string The customer's purchase order number
currency string 3-letter ISO code - defaults to account currency
date timestamp Credit note date - defaults to current timestamp
draft boolean When false, the credit note is considered outstanding, or when true, the credit note is a draft
closed boolean Marks a credit note as closed
items array Collection of Line Items
notes string Additional notes displayed on credit note
discounts array Collection of Discounts
taxes array Collection of Taxes
metadata object A hash of key/value pairs that can store additional information about this object.
attachments array A list of File IDs to attach to the credit note
calculate_taxes bool Disables tax calculation, default is true

Retrieve a credit note 

curl "https://api.invoiced.com/credit_notes/:id" \
  -u {API_KEY}:
creditNote = invoiced.CreditNote.retrieve("{CREDIT_NOTE_ID}")
<?php

$creditNote = $invoiced->CreditNote->retrieve("{CREDIT_NOTE_ID}");
creditNote = client.CreditNote.retrieve("{CREDIT_NOTE_ID}")
CreditNote creditNote = invoiced.newCreditNote().retrieve({CREDIT_NOTE_ID});
var creditNote = invoiced.NewCreditNote().Retrieve({CREDIT_NOTE_ID});
creditNote, err := client.CreditNote.Retrieve({CREDIT_NOTE_ID})

The above command returns JSON structured like this:

{
    "balance": 51.15,
    "closed": false,
    "created_at": 1415229884,
    "currency": "usd",
    "customer": 15444,
    "date": 1416290400,
    "discounts": [],
    "draft": false,
    "id": 2048,
    "items": [
        {
            "amount": 45,
            "catalog_item": null,
            "description": null,
            "discountable": true,
            "discounts": [],
            "id": 7,
            "metadata": [],
            "name": "Copy Paper, Case",
            "object": "line_item",
            "quantity": 1,
            "taxable": true,
            "taxes": [],
            "type": "product",
            "unit_cost": 45
        },
        {
            "amount": 10,
            "catalog_item": "delivery",
            "description": null,
            "discountable": true,
            "discounts": [],
            "id": 8,
            "metadata": [],
            "name": "Delivery",
            "object": "line_item",
            "quantity": 1,
            "taxable": true,
            "taxes": [],
            "type": "service",
            "unit_cost": 10
        }
    ],
    "metadata": [],
    "name": null,
    "notes": null,
    "number": "CN-0016",
    "object": "credit_note",
    "paid": false,
    "pdf_url": "https://dundermifflin.invoiced.com/credit_notes/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "purchase_order": null,
    "status": "open",
    "subtotal": 55,
    "taxes": [
        {
            "amount": 3.85,
            "id": 20554,
            "object": "tax",
            "tax_rate": null
        }
    ],
    "total": 51.15,
    "updated_at": 1415229884,
    "url": "https://dundermifflin.invoiced.com/credit_notes/IZmXbVOPyvfD3GPBmyd6FwXY"
}

This endpoint retrieves a specific credit note.

HTTP Request

GET /credit_notes/:id

If you set the Accept header to application/pdf then the credit note PDF will be returned.

Query Parameters

Parameter Type Description
expand string Properties to expand

Update a credit note 

curl "https://api.invoiced.com/credit_notes/:id" \
  -u {API_KEY}: \
  -X PATCH \
  -d sent=1
creditNote.name = "July Paper Delivery"
creditNote.notes = "The order was delivered on Jul 20, 2015"
creditNote.sent = true
creditNote.save
<?php

$creditNote->name = "July Paper Delivery";
$creditNote->notes = "The order was delivered on Jul 20, 2015";
$creditNote->sent = true;
$creditNote->save();
creditNote.name = "July Paper Delivery"
creditNote.notes = "The order was delivered on Jul 20, 2015"
creditNote.sent = True
creditNote.save()
creditNote.name = "July Paper Delivery";
creditNote.notes = "The order was delivered on Jul 20, 2015";
creditNote.sent = true;
creditNote.save();
creditNote.Name = "July Paper Delivery";
creditNote.Notes = "The order was delivered on Jul 20, 2015";
creditNote.Sent = true;
creditNote.SaveAll();
err := client.CreditNote.Update(&invoiced.CreditNoteRequest{
  Name: invoiced.String("July Paper Delivery"),
  Notes: invoiced.String("The order was delivered on Jul 20, 2015"),
  Sent: invoiced.Bool(true),
})

The above command returns JSON structured like this:

{
    "balance": 51.15,
    "closed": false,
    "created_at": 1415229884,
    "currency": "usd",
    "customer": 15444,
    "date": 1416290400,
    "discounts": [],
    "draft": false,
    "id": 2048,
    "items": [
        {
            "amount": 45,
            "catalog_item": null,
            "description": null,
            "discountable": true,
            "discounts": [],
            "id": 7,
            "metadata": [],
            "name": "Copy Paper, Case",
            "object": "line_item",
            "quantity": 1,
            "taxable": true,
            "taxes": [],
            "type": "product",
            "unit_cost": 45
        },
        {
            "amount": 10,
            "catalog_item": "delivery",
            "description": null,
            "discountable": true,
            "discounts": [],
            "id": 8,
            "metadata": [],
            "name": "Delivery",
            "object": "line_item",
            "quantity": 1,
            "taxable": true,
            "taxes": [],
            "type": "service",
            "unit_cost": 10
        }
    ],
    "metadata": [],
    "name": "July Paper Delivery",
    "notes": "The order was delivered on Jul 20, 2015",
    "number": "CN-0016",
    "object": "credit_note",
    "paid": false,
    "pdf_url": "https://dundermifflin.invoiced.com/credit_notes/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "purchase_order": null,
    "status": "sent",
    "subtotal": 55,
    "taxes": [
        {
            "amount": 3.85,
            "id": 20554,
            "object": "tax",
            "tax_rate": null
        }
    ],
    "total": 51.15,
    "updated_at": 1415229884,
    "url": "https://dundermifflin.invoiced.com/credit_notes/IZmXbVOPyvfD3GPBmyd6FwXY"
}

Use this endpoint to update a credit note.

HTTP Request

PATCH /credit_notes/:id

Attributes

Parameter Type Description
name string Credit note name for internal use, defaults to "Credit Note"
number string The reference number assigned to the credit note, defaults to next # in auto-numbering sequence
purchase_order string The customer's purchase order number
currency string 3-letter ISO code - defaults to account currency
date timestamp Credit note date - defaults to current timestamp
draft boolean When false, the credit note is considered outstanding, or when true, the invoice is a draft
closed boolean Marks a credit note as closed
items array Collection of Line Items
notes string Additional notes displayed on credit note
discounts array Collection of Discounts
taxes array Collection of Taxes
metadata object A hash of key/value pairs that can store additional information about this object.
attachments array A list of File IDs to attach to the credit note. Replaces existing attachments. Not providing this keeps existing attachments.
calculate_taxes bool Recalculate taxes, default is false

Send a credit note 

curl "https://api.invoiced.com/credit_notes/:id/emails" \
  -u {API_KEY}: \
  -X POST
emails = creditNote.send
<?php

$emails = $creditNote->send();
emails = creditNote.send()
EmailRequest emailRequest = new EmailRequest();
EmailRecipient[] emailRecipients = new EmailRecipient[1];
emailRecipients[0] = new EmailRecipient();
emailRecipients[0].name = "Client";
emailRecipients[0].email = "client@example.com";

emailRequest.to = emailRecipients;
emailRequest.subject = "New Credit Note from Dunder Mifflin, Inc.: CN-0016";
emailRequest.message = "Dear Client, a new credit note for $51.15 has been created on your account. Thank you!";

Email[] emails = creditNote.send(emailRequest);
var emailRequest = new EmailRequest();
var emailRecipients = new EmailRecipient[1];
emailRecipients[0] = new EmailRecipient();
emailRecipients[0].Name = "Client";
emailRecipients[0].Email = "client@example.com";

emailRequest.To = emailRecipients;
emailRequest.Subject = "New Credit Note from Dunder Mifflin, Inc.: CN-0016";
emailRequest.Message = "Dear Client, a new credit note for $51.15 has been created on your account. Thank you!";

var emails = creditNote.SendEmail(emailRequest);
err := client.CreditNote.SendEmail({CREDIT_NOTE_ID}, &invoiced.SendEmailRequest{
  To: []*invoiced.EmailRecipient{
    Name: invoiced.String("Client"),
    Email: "client@example.com",
  },
  Subject: invoiced.String("New Credit Note from Dunder Mifflin, Inc.: CN-0016"),
  Message: invoiced.String("Dear Client, a new credit note for $51.15 has been created on your account. Thank you!"),
})

The above command returns JSON structured like this:

[
  {
     "created_at": 1436890047,
     "email": "client@example.com",
     "id": "f45382c6fbc44d44aa7f9a55eb2ce731",
     "message": "Dear Client, a new credit note for $51.15 has been created on your account. Thank you!",
     "object": "email",
     "opens": 0,
     "opens_detail": [],
     "reject_reason": null,
     "state": "sent",
     "subject": "New Credit Note from Dunder Mifflin, Inc.: CN-0016",
     "template": "credit_note_email",
     "updated_at": 1436890047
 }
]

This endpoint sends a credit note to your customer.

HTTP Request

POST /credit_notes/:id/emails

Request Parameters

Parameter Type Description
to array Optional array of recipients like:
[{"name": "Client", "email": "client@example.com"}]
bcc string Optional comma-separated list of email addresses to be blind carbon copied
template string Optional email template ID, otherwise a standard email template is selected
subject string Optional subject to override the template
message string Optional message body to override the template

List credit note attachments 

curl "https://api.invoiced.com/credit_notes/:id/attachments" \
  -u {API_KEY}:
attachments, metadata = creditNote.attachments
<?php

list($attachments, $metadata) = $creditNote->attachments();
attachments, metadata = creditNote.attachments()
Attachment[] attachments = creditNote.listAttachments();
var attachments = creditNote.ListAttachments();
attachments, err := client.CreditNote.ListAttachments({CREDIT_NOTE_ID})

The above command returns JSON structured like this:

[
  {
     "created_at": 1464625855,
     "file": {
         "created_at": 1464625855,
         "id": 13,
         "name": "logo-invoice.png",
         "object": "file",
         "size": 6936,
         "type": "image/png",
         "updated_at": 1464625855,
         "url": "https://invoiced.com/img/logo-invoice.png"
     },
     "id": 13,
     "object": "attachment",
     "updated_at": 1464625855
 }
]

This endpoint retrieves a list of files attached to a specific credit note.

HTTP Request

GET /credit_notes/:id/attachments

Void a credit note 

curl "https://api.invoiced.com/credit_notes/:id/void" \
  -u {API_KEY}: \
creditNote.void
<?php

$creditNote->void();
creditNote.void()
creditNote.voidCreditNote();
creditNote.Void();
creditNote, err := client.CreditNote.Void({CREDIT_NOTE_ID})

The above command returns JSON structured like this:

{
    "balance": 51.15,
    "closed": false,
    "created_at": 1415229884,
    "currency": "usd",
    "customer": 15444,
    "date": 1416290400,
    "discounts": [],
    "draft": false,
    "id": 2048,
    "items": [
        {
            "amount": 45,
            "catalog_item": null,
            "description": null,
            "discountable": true,
            "discounts": [],
            "id": 7,
            "metadata": [],
            "name": "Copy Paper, Case",
            "object": "line_item",
            "quantity": 1,
            "taxable": true,
            "taxes": [],
            "type": "product",
            "unit_cost": 45
        },
        {
            "amount": 10,
            "catalog_item": "delivery",
            "description": null,
            "discountable": true,
            "discounts": [],
            "id": 8,
            "metadata": [],
            "name": "Delivery",
            "object": "line_item",
            "quantity": 1,
            "taxable": true,
            "taxes": [],
            "type": "service",
            "unit_cost": 10
        }
    ],
    "metadata": [],
    "name": "July Paper Delivery",
    "notes": "The order was delivered on Jul 20, 2015",
    "number": "CN-0016",
    "object": "credit_note",
    "paid": false,
    "pdf_url": "https://dundermifflin.invoiced.com/credit_notes/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
    "purchase_order": null,
    "status": "voided",
    "subtotal": 55,
    "taxes": [
        {
            "amount": 3.85,
            "id": 20554,
            "object": "tax",
            "tax_rate": null
        }
    ],
    "total": 51.15,
    "updated_at": 1415229884,
    "url": "https://dundermifflin.invoiced.com/credit_notes/IZmXbVOPyvfD3GPBmyd6FwXY"
}

Use this endpoint to void a credit note.

HTTP Request

POST /credit_notes/:id/void

Delete a credit note 

curl "https://api.invoiced.com/credit_notes/:id" \
  -u {API_KEY}: \
  -X DELETE
creditNote.delete
<?php

$creditNote->delete();
creditNote.delete()
creditNote.delete();
creditNote.Delete();
err := client.CreditNote.Delete({CREDIT_NOTE_ID})

The above command returns 204 No Content

This endpoint deletes a specific credit note.

HTTP Request

DELETE /credit_notes/:id

List all credit notes 

curl "https://api.invoiced.com/credit_notes" \
  -u {API_KEY}:
creditNotes, metadata = invoiced.CreditNote.list(:per_page => 3)
<?php

list($creditNotes, $metadata) = $invoiced->CreditNote->all(['per_page' => 3]);
creditNotes, metadata = client.CreditNote.list(per_page=3)
EntityList<CreditNote> creditNotes = conn.newCreditNote().listAll();
var creditNotes = invoiced.NewCreditNote().ListAll();
creditNotes, err := client.CreditNote.ListAll(nil, nil)

The above command returns JSON structured like this:

[
  {
     "balance": 51.15,
     "closed": false,
     "created_at": 1415229884,
     "currency": "usd",
     "customer": 15444,
     "date": 1416290400,
     "discounts": [],
     "draft": false,
     "id": 2048,
     "items": [
         {
             "amount": 45,
             "catalog_item": null,
             "description": null,
             "discountable": true,
             "discounts": [],
             "id": 7,
             "metadata": [],
             "name": "Copy Paper, Case",
             "object": "line_item",
             "quantity": 1,
             "taxable": true,
             "taxes": [],
             "type": "product",
             "unit_cost": 45
         },
         {
             "amount": 10,
             "catalog_item": "delivery",
             "description": null,
             "discountable": true,
             "discounts": [],
             "id": 8,
             "metadata": [],
             "name": "Delivery",
             "object": "line_item",
             "quantity": 1,
             "taxable": true,
             "taxes": [],
             "type": "service",
             "unit_cost": 10
         }
     ],
     "metadata": [],
     "name": null,
     "notes": null,
     "number": "CN-0016",
     "object": "credit_note",
     "paid": false,
     "pdf_url": "https://dundermifflin.invoiced.com/credit_notes/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
     "purchase_order": null,
     "status": "open",
     "subtotal": 55,
     "taxes": [
         {
             "amount": 3.85,
             "id": 20554,
             "object": "tax",
             "tax_rate": null
         }
     ],
     "total": 51.15,
     "updated_at": 1415229884,
     "url": "https://dundermifflin.invoiced.com/credit_notes/IZmXbVOPyvfD3GPBmyd6FwXY"
 }
]

This endpoint retrieves all credit notes.

HTTP Request

GET /credit_notes

Query Parameters

Parameter Description
sort string Column to sort by, i.e. name asc
filter object Filter object
metadata object Metadata filter object
start_date timestamp Restricts the results to credit notes on or after the given timestamp
end_date timestamp Restricts the results to credit notes on or before the given timestamp
updated_after timestamp Only gets records updated after the given timestamp
cURL .NET Java Go PHP Python Ruby