Invoices and credit notes
Invoices and credit notes are billing documents. They have their own permissions, lists, details, and PDF streams; they are separate from marketplace settlement statements in profitability.
Choose the document workflow
| If you need to | Start with | Keep in mind |
|---|---|---|
| Show what Nasam billed | List invoices | status, invoice date, due date, and balance describe the billing document |
| Show a credit issued against billing | List credit notes | Credit notes have their own IDs, statuses, and PDFs |
| Reconcile marketplace proceeds | Profitability | A settlement is not an invoice or credit note |
| Correct a draft's lines | Update invoice line items | Only Draft invoices can be edited through this operation |
Find and download a document
List invoices with filters such as status, contactId, brandIds, invoiceNumber, invoice-date bounds, and isOverdue. List credit notes with status, contact, brand, credit-note number, and credit-note-date filters. Both list responses include their named collection and pagination. Omitted brandIds use the caller's accessible brand scope; the required grant is invoices.read or creditNotes.read, respectively.
Use invoice detail or credit-note detail for a selected document ID. The invoice PDF and credit-note PDF stream application/pdf with an inline content disposition. Treat the response as binary, not as JSON; save or display it according to your product's document workflow.
curl --get 'https://backend.nasam.co/v1/invoicing/invoices' \
--data-urlencode 'brandIds=20' \
--data-urlencode 'status=Sent' \
--data-urlencode 'page=1' \
-H 'key: YOUR_API_KEY'
The list includes invoices and pagination; a credit-note list uses creditNotes. Invoice and credit-note statuses include Draft, Sent, Paid, Settled, Void, and Deleted. To find unpaid late invoices, use isOverdue=true: the server selects Sent invoices with a due date before the current time. For an exact billing entity, contactId is a separate filter from brandIds; the brand filter resolves the brands' billing contacts. If multiple contacts are selected, the service merges first-page results per contact and reports pagination for that merged set. Do not treat that merged page as a complete multi-contact ledger; narrow by contact when exhaustive traversal matters.
Download a selected PDF with the document id returned by the list or detail operation:
curl 'https://backend.nasam.co/v1/invoicing/invoices/INVOICE_ID/pdf' \
-H 'key: YOUR_API_KEY' \
-H 'accept: application/pdf' \
--output invoice.pdf
Handle non-2xx responses before opening the saved file as a PDF; an upstream document error can return JSON or end a stream early.
Edit a draft invoice
PATCH /v1/invoicing/invoices/{id}/line-items requires invoices.write. Read the invoice detail first to obtain line-item id values, then send a non-empty lineItems array with only the IDs to patch and any supported description, quantity, or unitAmount fields. An omitted field keeps its existing value. The operation replaces the invoice's resulting line set and returns updated invoice detail.
Only a Draft invoice can be edited. An unknown line-item ID is rejected. Setting a line's unitAmount to zero removes that line; the invoice must retain at least one line item. A status conflict returns HTTP 409, so re-read the invoice before retrying an edit after another user or process changes it.
For a draft with a known line-item ID, a patch can change just that line's quantity:
curl -X PATCH 'https://backend.nasam.co/v1/invoicing/invoices/INVOICE_ID/line-items' \
-H 'key: YOUR_API_KEY' \
-H 'content-type: application/json' \
-d '{"lineItems":[{"id":"LINE_ITEM_ID","quantity":2}]}'
Re-read the returned invoice detail, including totals and balance, before treating an edit as finished. A 400 for an unknown line ID or for removing the final line requires a corrected payload. A 409 means the document is no longer a draft; do not blindly repeat the write.