Read and manage invoices - filter and page through records with compact or full response views, and create, edit, issue, pay, cancel, credit and send them.
Generated from the OpenAPI schema. Always matches the live API.
| Attribute | Type | Required | Description | Example |
|---|---|---|---|---|
id | integer | - | Internal record id. | 11589 |
type | enum | - | Record type, fixed per endpoint. | invoice |
number | string | - | Zero-padded document number (display format). | 001956 |
contact | integer or null | - | Contact id: the customer on invoices/orders, the supplier on purchases, or null. | 25174 |
vehicle | integer or null | - | Vehicle id, or null. | |
additional_cost_vehicle | integer or null | - | Purchases only: the DEFAULT vehicle this purchase is linked to as an additional cost, or null - lines without their own line vehicle feed this vehicle's cost row. Distinct from vehicle, which is also populated on vehicle-acquisition purchases. | |
lead | integer or null | - | Lead id, or null. | |
aftersale | integer or null | - | Aftersale id, or null. | |
status | object | - | Document status. | |
status.id | integer | - | Status code: 0 draft, 1 issued, 2 paid (for orders: converted), 3 cancelled. | 2 |
status.name | enum | - | Status name. Code 2 is "paid" for invoices/purchases and "converted" for orders (an order converted into an invoice). See GET /reference/invoice-statuses. | paid |
version | integer | - | Document behaviour version, stamped at creation and never changed. 1: invoice-level discounts[] and adjustments[]. 2: discounts move to the line (lines[].discount); discounts[] is rejected. 3: additionally no adjustments[] - use a line for a fee or charge, or part_exchange[].settlement for outstanding finance. New documents are created at version 3. | 3 |
totals | object | - | Computed monetary totals. | |
totals.sub_total | number | - | Net total before tax. | 500 |
totals.exchange | number | - | Part-exchange total. | 0 |
totals.settlement | number | - | Finance settlements added back to the customer's total (sales documents); on a purchase, the settlement expected to be paid to lenders. | 0 |
totals.adjustment | number | - | Adjustments total. | 0 |
totals.discount | number | - | Discount total. | 0 |
totals.tax | number | - | Tax (VAT) total. | 25 |
totals.finance | number | - | Finance total. | 0 |
totals.deposit | number | - | Deposit total (the reservation deposit; distinct from the finance-scheme deposit in finance.deposit). | 0 |
totals.total | number | - | Gross total. | 525 |
totals.total_sale | number | - | Total sale value. | 525 |
totals.total_due | number | - | Outstanding amount due. | 525 |
totals.credit_sub_total | number | - | Credited net total. | 0 |
totals.credit_tax | number | - | Credited tax total. | 0 |
totals.credit_total | number | - | Credited gross total. | 0 |
scheme | enum | - | VAT scheme: vat = standard VAT invoice; margin = second-hand margin scheme. | margin |
currency | string | - | ISO currency code for all monetary values on the document. | GBP |
settlement_outstanding | number or null | - | Purchases: the finance settlement still to be paid to the lender(s) - the expected total on the acquisition lines less the Finance Settlement payments recorded. null on invoices and orders. | |
paid_date | string or null | - | Date paid (YYYY-MM-DD date string), or null if unpaid. The paid field gives the same event as a Unix timestamp. | 2026-06-02 |
paid | integer | - | Unix timestamp paid, or 0 if unpaid. | 1780394814 |
created | integer | - | Unix timestamp created. | 1780394800 |
updated | integer | - | Unix timestamp last updated. | 1780394814 |
reference | string | - | Document reference, if set. | |
nominal | string | - | Document-level accounting nominal code override, if set. | |
invoice_date | integer or null | - | Invoice date (Unix timestamp), or null. | 1779962100 |
supply_date | integer or null | - | Time/date of supply (Unix timestamp), or null. | 1781827200 |
notes | string | - | Invoice notes (may contain HTML). | <p><strong>some notes</strong></p> |
terms | string | - | Terms & conditions text (may contain HTML). | |
options | object | - | Document output options/flags. | |
options.hide_vat | boolean | - | Ireland VRT/VAT-hidden output option. | false |
options.hide_registration | boolean | - | Hide the vehicle registration on the document. | false |
options.payment_online | boolean | - | Allow online payment. | true |
options.review | boolean | - | Document is in review mode. | false |
options.eu_goods_services | boolean | - | EU goods/services flag. | false |
contact_snapshot | object | - | Contact details captured on the document (full view only). The customer on invoices/orders, the supplier on purchases. | |
contact_snapshot.id | integer or null | - | Contact id, or null. | 25174 |
contact_snapshot.name | string | - | Customer name. | New Customer |
contact_snapshot.company | string | - | Company name. | Test Ltd. |
contact_snapshot.email | string | - | Email address. | |
contact_snapshot.telephone | string | - | Landline number. | |
contact_snapshot.mobile | string | - | Mobile number. | |
contact_snapshot.address | object | - | Billing address captured on the document. | |
contact_snapshot.address.line1 | string | - | 333 Oxford Street | |
contact_snapshot.address.line2 | string | - | ||
contact_snapshot.address.line3 | string | - | ||
contact_snapshot.address.city | string | - | London | |
contact_snapshot.address.state | string | - | Greater London | |
contact_snapshot.address.country | string | - | United Kingdom | |
contact_snapshot.address.zip | string | - | W1C 2HY | |
delivery | object | - | Delivery / collection party, when set (separate from the billing customer). | |
delivery.name | string | - | ||
delivery.telephone | string | - | ||
delivery.address | object | - | ||
delivery.address.line1 | string | - | ||
delivery.address.line2 | string | - | ||
delivery.address.line3 | string | - | ||
delivery.address.city | string | - | ||
delivery.address.state | string | - | ||
delivery.address.country | string | - | ||
delivery.address.zip | string | - | ||
vehicle_snapshot | object | - | The sold vehicle, captured on the document (full view only). This is the detail for the line flagged vehicle:true. | |
vehicle_snapshot.id | integer or null | - | Vehicle id, or null. | 85460 |
vehicle_snapshot.tag | string | - | Vehicle tag. | 8CdYme7L |
vehicle_snapshot.stock_number | string | - | Stock id/number. | 00002468 |
vehicle_snapshot.registration | string | - | Registration plate. | P70GMW |
vehicle_snapshot.vin | string | - | VIN. | WDC2539092F047615 |
vehicle_snapshot.make | string | - | Make. | Mercedes-Benz |
vehicle_snapshot.model | string | - | Model. | GLC |
vehicle_snapshot.derivative | string | - | Derivative. | 2.1 GLC250d AMG Line (Premium) SUV 5dr |
vehicle_snapshot.colour | string | - | Colour. | White |
vehicle_snapshot.mileage | integer or null | - | Mileage, or null. | 12345 |
vehicle_snapshot.year | string | - | Model/registration year. | 2016 |
payment | object | - | Payment terms and the recorded payments (full view only). | |
payment.terms | string | - | Payment terms, if set. | |
payment.payments | array of object | - | Recorded payments (always an array; empty when none). | |
finance | object | - | Finance and deposit detail behind the finance/deposit totals (full view only). | |
finance.provider | object | - | Finance provider funding the sale. | |
finance.provider.id | integer or null | - | Finance provider contact id, or null. | 77869 |
finance.provider.name | string | - | Provider name (resolved from the provider record when not set explicitly). | ABC Finance |
finance.provider.amount | number | - | Amount funded by the provider. | 10000 |
finance.deposit | object | - | Finance deposit. | |
finance.deposit.amount | number | - | Deposit amount. | 500 |
finance.deposit.paid_by | string | - | Who paid the deposit. | Customer |
esign | object | - | E-signature request status (full view only). | |
esign.required | boolean | - | Whether the document requires e-signature. | true |
esign.signed | boolean | - | Whether it has been signed. | false |
esign.name | string | - | Signatory name, if signed. | |
esign.date | string | - | Signature date, if signed. | |
accounting | object | - | Accounting integration state (full view only, read-only). Only the keys present on the document are returned. | |
accounting.nominal | string | - | Nominal code mapping for the document. | |
accounting.tax | string | - | Tax/VAT accounting detail. | |
accounting.sent | string | - | Whether/when the document was sent to the accounting integration. | |
accounting.sync | string | - | Synchronisation state with the accounting integration. | |
accounting.ledger | string | - | Ledger reference in the accounting integration. | |
lines | array of object | - | Line items (full view only). The sold vehicle appears as a line with vehicle:true (id CMVEHICL); its full detail is in vehicle_snapshot. | |
part_exchange | array of object | - | Part-exchange (trade-in) vehicles taken against the sale (full view only). Each row carries the traded vehicle inline. | |
adjustments | array of object | - | Named value adjustments (surcharges/credits), full view only. Version 1 and 2 documents only: version 3 documents have none, so use a line for an admin fee or delivery charge and part_exchange[].settlement for outstanding finance. | |
discounts | array of object | - | Named invoice-level discounts (full view only). Version 1 documents only - version 2 documents carry discounts per line (lines[].discount) and this array is always empty for them. | |
vat_summary | array of object | - | VAT breakdown grouped by canonical category (full view only): net and VAT per category. Entries are bucketed by type so zero-rated, exempt and no-VAT are reported separately even though they share a 0/null rate. The margin-scheme entry has type=margin, rate=null, margin=true and vat=null. | |
credit_notes | array of object | - | Credit notes raised against the document (full view only). | |
linked_purchase | string or null | - | Document number of the purchase invoice auto-generated from a part-exchange, or null. | 000689 |
{
"id": 11589,
"type": "invoice",
"number": "001956",
"contact": 25174,
"vehicle": 0,
"additional_cost_vehicle": 0,
"lead": 0,
"aftersale": 0,
"status": {
"id": 2,
"name": "paid"
},
"version": 3,
"totals": {
"sub_total": 500,
"exchange": 0,
"settlement": 0,
"adjustment": 0,
"discount": 0,
"tax": 25,
"finance": 0,
"deposit": 0,
"total": 525,
"total_sale": 525,
"total_due": 525,
"credit_sub_total": 0,
"credit_tax": 0,
"credit_total": 0
},
"scheme": "margin",
"currency": "GBP",
"settlement_outstanding": 0,
"paid_date": "2026-06-02",
"paid": 1780394814,
"created": 1780394800,
"updated": 1780394814,
"reference": "",
"nominal": "",
"invoice_date": 1779962100,
"supply_date": 1781827200,
"notes": "<p><strong>some notes</strong></p>",
"terms": "",
"options": {
"hide_vat": false,
"hide_registration": false,
"payment_online": true,
"review": false,
"eu_goods_services": false
},
"contact_snapshot": {
"id": 25174,
"name": "New Customer",
"company": "Test Ltd.",
"email": "",
"telephone": "",
"mobile": "",
"address": {
"line1": "333 Oxford Street",
"line2": "",
"line3": "",
"city": "London",
"state": "Greater London",
"country": "United Kingdom",
"zip": "W1C 2HY"
}
},
"delivery": {
"name": "",
"telephone": "",
"address": {
"line1": "",
"line2": "",
"line3": "",
"city": "",
"state": "",
"country": "",
"zip": ""
}
},
"vehicle_snapshot": {
"id": 85460,
"tag": "8CdYme7L",
"stock_number": "00002468",
"registration": "P70GMW",
"vin": "WDC2539092F047615",
"make": "Mercedes-Benz",
"model": "GLC",
"derivative": "2.1 GLC250d AMG Line (Premium) SUV 5dr",
"colour": "White",
"mileage": 12345,
"year": "2016"
},
"payment": {
"terms": "",
"payments": [
{
"date": 1779926400,
"amount": 2000,
"method": "Bank Transfer",
"reference": "",
"notes": "",
"payee": 0
}
]
},
"finance": {
"provider": {
"id": 77869,
"name": "ABC Finance",
"amount": 10000
},
"deposit": {
"amount": 500,
"paid_by": "Customer"
}
},
"esign": {
"required": true,
"signed": false,
"name": "",
"date": ""
},
"accounting": {
"nominal": "",
"tax": "",
"sent": "",
"sync": "",
"ledger": ""
},
"lines": [
{
"id": "CMVEHICL",
"key": "CMVEHICL",
"code": "",
"name": "Mercedes-Benz GLC 2.1 GLC250d AMG Line",
"description": "",
"quantity": 1,
"price": 23771,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": "",
"options": [
{
"key": "1",
"name": "Wheel Protection",
"description": "",
"price": 100,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
}
}
],
"custom": true,
"constant": true,
"vehicle": 85460,
"discount": {},
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"part_exchange": [
{
"vehicle": "Skoda Fabia 1.2 TSI SE Estate 5dr",
"registration": "AY65YRL",
"vin": "TMBKN6NJ1GZ049678",
"mileage": 35000,
"math": "minus",
"value": 9011.81,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"purchase": "Done",
"add": "Yes",
"appraisal_id": 85461,
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"adjustments": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"discounts": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"vat_summary": [
{
"type": "standard",
"rate": 20,
"margin": false,
"net": 500,
"vat": 25
}
],
"credit_notes": [
{
"id": "000007",
"date": 0,
"note": "",
"sub_total": 208.33,
"tax": 41.67,
"total": 250,
"lines": [
{
"name": "Transfer of Vehicle Reservation Payment",
"description": "",
"quantity": 1,
"amount": 208.33,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"total": 250,
"source": ""
}
]
}
],
"linked_purchase": "000689"
}GET /2.0/invoices · scope invoices:read
| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
page | query | integer | - | Page number for offset pagination. | |
per_page | query | integer | - | Results per page (max 500). | |
view | query | enum | - | simple (default for lists) or full. | |
contact | query | integer | - | Filter by contact id. | |
vehicle | query | integer | - | Filter by vehicle id. | |
lead | query | integer | - | Filter by lead id. | |
aftersale | query | integer | - | Filter by aftersale id. | |
number | query | integer | - | Filter by document number. Accepts the number with or without leading zeros (e.g. 1956 or 001956); the padding is display-only. | |
status | query | integer | - | Filter by status code: 0 draft, 1 issued, 2 paid, 3 cancelled. | |
created | query | string | - | Unix timestamp exact match, or a two-element array [from, to] for a range. An empty bound is open-ended. | |
updated | query | string | - | Unix timestamp exact match, or a two-element array [from, to] for a range. An empty bound is open-ended. | |
paid | query | string | - | Unix timestamp exact match, or a two-element array [from, to] for a range. An empty bound is open-ended. | |
cursor | query | string | - | Keyset pagination cursor from a previous response's meta.pagination.next_cursor. When supplied, page/total are not returned. | |
fields | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. |
| Status | Description |
|---|---|
200 OK | Paginated invoices |
Failures use the standard error responses (4xx/5xx) with the shared error envelope.
{
"success": true,
"data": [
{
"id": 11589,
"type": "invoice",
"number": "001956",
"contact": 25174,
"vehicle": 0,
"additional_cost_vehicle": 0,
"lead": 0,
"aftersale": 0,
"status": {
"id": 2,
"name": "paid"
},
"version": 3,
"totals": {
"sub_total": 500,
"exchange": 0,
"settlement": 0,
"adjustment": 0,
"discount": 0,
"tax": 25,
"finance": 0,
"deposit": 0,
"total": 525,
"total_sale": 525,
"total_due": 525,
"credit_sub_total": 0,
"credit_tax": 0,
"credit_total": 0
},
"scheme": "margin",
"currency": "GBP",
"settlement_outstanding": 0,
"paid_date": "2026-06-02",
"paid": 1780394814,
"created": 1780394800,
"updated": 1780394814,
"reference": "",
"nominal": "",
"invoice_date": 1779962100,
"supply_date": 1781827200,
"notes": "<p><strong>some notes</strong></p>",
"terms": "",
"options": {
"hide_vat": false,
"hide_registration": false,
"payment_online": true,
"review": false,
"eu_goods_services": false
},
"contact_snapshot": {
"id": 25174,
"name": "New Customer",
"company": "Test Ltd.",
"email": "",
"telephone": "",
"mobile": "",
"address": {
"line1": "333 Oxford Street",
"line2": "",
"line3": "",
"city": "London",
"state": "Greater London",
"country": "United Kingdom",
"zip": "W1C 2HY"
}
},
"delivery": {
"name": "",
"telephone": "",
"address": {
"line1": "",
"line2": "",
"line3": "",
"city": "",
"state": "",
"country": "",
"zip": ""
}
},
"vehicle_snapshot": {
"id": 85460,
"tag": "8CdYme7L",
"stock_number": "00002468",
"registration": "P70GMW",
"vin": "WDC2539092F047615",
"make": "Mercedes-Benz",
"model": "GLC",
"derivative": "2.1 GLC250d AMG Line (Premium) SUV 5dr",
"colour": "White",
"mileage": 12345,
"year": "2016"
},
"payment": {
"terms": "",
"payments": [
{
"date": 1779926400,
"amount": 2000,
"method": "Bank Transfer",
"reference": "",
"notes": "",
"payee": 0
}
]
},
"finance": {
"provider": {
"id": 77869,
"name": "ABC Finance",
"amount": 10000
},
"deposit": {
"amount": 500,
"paid_by": "Customer"
}
},
"esign": {
"required": true,
"signed": false,
"name": "",
"date": ""
},
"accounting": {
"nominal": "",
"tax": "",
"sent": "",
"sync": "",
"ledger": ""
},
"lines": [
{
"id": "CMVEHICL",
"key": "CMVEHICL",
"code": "",
"name": "Mercedes-Benz GLC 2.1 GLC250d AMG Line",
"description": "",
"quantity": 1,
"price": 23771,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": "",
"options": [
{
"key": "1",
"name": "Wheel Protection",
"description": "",
"price": 100,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
}
}
],
"custom": true,
"constant": true,
"vehicle": 85460,
"discount": {},
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"part_exchange": [
{
"vehicle": "Skoda Fabia 1.2 TSI SE Estate 5dr",
"registration": "AY65YRL",
"vin": "TMBKN6NJ1GZ049678",
"mileage": 35000,
"math": "minus",
"value": 9011.81,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"purchase": "Done",
"add": "Yes",
"appraisal_id": 85461,
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"adjustments": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"discounts": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"vat_summary": [
{
"type": "standard",
"rate": 20,
"margin": false,
"net": 500,
"vat": 25
}
],
"credit_notes": [
{
"id": "000007",
"date": 0,
"note": "",
"sub_total": 208.33,
"tax": 41.67,
"total": 250,
"lines": [
{
"name": "Transfer of Vehicle Reservation Payment",
"description": "",
"quantity": 1,
"amount": 208.33,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"total": 250,
"source": ""
}
]
}
],
"linked_purchase": "000689"
}
],
"meta": {
"pagination": {
"page": 0,
"per_page": 0,
"total": 0,
"total_pages": 0,
"next_cursor": ""
}
}
}POST /2.0/invoices · scope invoices:write
Create a draft invoice. Supply the full document body (contact, lines, sold vehicle, part-exchanges, adjustments, discounts, finance, notes/terms). Issue it separately to finalise.
| Attribute | Type | Required | Description | Example |
|---|---|---|---|---|
contact | integer or null | - | Customer contact id (supplier id for purchases). Required for invoices/orders; optional for purchases. | 25174 |
scheme | enum | - | VAT scheme. Defaults to vat. | vat |
date | string | - | Document date (YYYY-MM-DD or Unix timestamp). Defaults to now. | 2026-06-13 |
reference | string | - | Document reference (e.g. the supplier invoice number for purchases). | PO-1042 |
nominal | string | - | Document-level accounting nominal code override. | |
notes | string | - | Document notes (may contain HTML). | |
terms | string | - | Terms & conditions text (may contain HTML). | |
supply_date | integer | - | Time/date of supply (Unix timestamp). | |
payment_terms | string | - | Payment terms text. | |
options | object | - | Document output flags. | |
options.hide_vat | boolean | - | Hide the VAT breakdown on the document. | |
options.hide_registration | boolean | - | Hide the vehicle registration on the document. | |
options.payment_online | boolean | - | Offer online payment for the issued document. | |
options.eu_goods_services | boolean | - | Flag the document as an EU goods/services supply. | |
delivery | object | - | Delivery / collection party (separate from the billing contact). | |
delivery.name | string | - | Delivery contact name. | |
delivery.telephone | string | - | Delivery contact telephone. | |
delivery.address | object | - | Delivery address. | |
delivery.address.line1 | string | - | Address line 1. | |
delivery.address.line2 | string | - | Address line 2. | |
delivery.address.line3 | string | - | Address line 3. | |
delivery.address.city | string | - | Town / city. | |
delivery.address.state | string | - | County / state. | |
delivery.address.country | string | - | Country. | |
delivery.address.zip | string | - | Postcode / ZIP. | |
vehicle | object or null | - | The sold vehicle line (invoices/orders only). Identify by id or tag. Must be an in-stock vehicle in the for-sale status - the same rule as the dashboard's sale form; drafts, sold vehicles, appraisals and customer vehicles return 422. | |
vehicle.id | integer | - | Stock vehicle id. | 85460 |
vehicle.tag | string | - | Vehicle tag (alternative to id). | |
vehicle.mileage | integer | - | Sale mileage override. | |
vehicle.price | number | - | Sale price (net) override. | 13495 |
vehicle.vat | enum | - | VAT treatment of the vehicle line. | |
additional_cost_vehicle | object or null | - | Purchases only: link the WHOLE purchase to a vehicle as an additional cost (feeds the vehicle's Purchase & Costs and its profit). Lines without their own line vehicle feed this vehicle's additional-cost row (lines carrying a per-line vehicle feed that vehicle instead) - there is no per-line margin bundling on this document type. Identify by id or tag; null unlinks, a different vehicle re-targets (unlink and re-target are API-only and work on drafts). The vehicle can hold at most 50 cost rows. | |
additional_cost_vehicle.id | integer | - | Stock vehicle id. | 85460 |
additional_cost_vehicle.tag | string | - | Vehicle tag (alternative to id). | |
lines | array of object | - | Product and ad-hoc line items. On PATCH the supplied array replaces the existing lines; omit the field to keep them, or send an empty array to clear them. | |
part_exchange | array of object | - | Trade-in vehicles (max 5). | |
adjustments | array of object | - | Named value adjustments (max 5). Rejected on version 3 documents, which every new document now is: use a line for an admin fee or delivery charge, or part_exchange[].settlement for outstanding finance. | |
discounts | array of object | - | Named discounts (max 5). Version 1 documents only - version 2 documents (all new documents) take discounts per line via lines[].discount and reject this field. | |
finance | object or null | - | Finance provider funding the sale (invoices). | |
finance.provider | integer | - | Finance provider contact id. | |
finance.amount | number | - | Amount financed. | |
finance.generate | boolean | - | Auto-generate the finance invoice on issue. |
{
"contact": 25174,
"scheme": "vat",
"date": "2026-06-13",
"reference": "PO-1042",
"nominal": "",
"notes": "",
"terms": "",
"supply_date": 0,
"payment_terms": "",
"options": {
"hide_vat": false,
"hide_registration": false,
"payment_online": false,
"eu_goods_services": false
},
"delivery": {
"name": "",
"telephone": "",
"address": {
"line1": "",
"line2": "",
"line3": "",
"city": "",
"state": "",
"country": "",
"zip": ""
}
},
"vehicle": {
"id": 85460,
"tag": "",
"mileage": 0,
"price": 13495,
"vat": "vat"
},
"additional_cost_vehicle": {
"id": 85460,
"tag": ""
},
"lines": [
{
"product": 0,
"code": "",
"name": "Admin Fee",
"description": "",
"price": 199,
"vat": "standard",
"quantity": 1,
"options": [
""
],
"vehicle": 0,
"discount": {}
}
],
"part_exchange": [
{
"registration": "AY65YRL",
"mileage": 0,
"vin": "",
"value": 9000,
"math": "minus",
"type": "currency",
"vat": "standard",
"purchase": "Yes",
"add": "Yes",
"appraisal_id": 85461,
"settlement": {
"amount": 2000,
"finance_company": 4471,
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"adjustments": [
{
"name": "Delivery",
"value": 150,
"math": "plus",
"type": "currency",
"vat": "standard",
"nominal": ""
}
],
"discounts": [
{
"name": "Loyalty Discount",
"value": 250,
"math": "plus",
"type": "currency",
"vat": "standard",
"nominal": ""
}
],
"finance": {
"provider": 0,
"amount": 0,
"generate": false
}
}| Status | Description |
|---|---|
201 Created | Create Invoice |
Failures use the standard error responses (4xx/5xx) with the shared error envelope.
{
"success": true,
"data": {
"id": 11589,
"type": "invoice",
"number": "001956",
"contact": 25174,
"vehicle": 0,
"additional_cost_vehicle": 0,
"lead": 0,
"aftersale": 0,
"status": {
"id": 2,
"name": "paid"
},
"version": 3,
"totals": {
"sub_total": 500,
"exchange": 0,
"settlement": 0,
"adjustment": 0,
"discount": 0,
"tax": 25,
"finance": 0,
"deposit": 0,
"total": 525,
"total_sale": 525,
"total_due": 525,
"credit_sub_total": 0,
"credit_tax": 0,
"credit_total": 0
},
"scheme": "margin",
"currency": "GBP",
"settlement_outstanding": 0,
"paid_date": "2026-06-02",
"paid": 1780394814,
"created": 1780394800,
"updated": 1780394814,
"reference": "",
"nominal": "",
"invoice_date": 1779962100,
"supply_date": 1781827200,
"notes": "<p><strong>some notes</strong></p>",
"terms": "",
"options": {
"hide_vat": false,
"hide_registration": false,
"payment_online": true,
"review": false,
"eu_goods_services": false
},
"contact_snapshot": {
"id": 25174,
"name": "New Customer",
"company": "Test Ltd.",
"email": "",
"telephone": "",
"mobile": "",
"address": {
"line1": "333 Oxford Street",
"line2": "",
"line3": "",
"city": "London",
"state": "Greater London",
"country": "United Kingdom",
"zip": "W1C 2HY"
}
},
"delivery": {
"name": "",
"telephone": "",
"address": {
"line1": "",
"line2": "",
"line3": "",
"city": "",
"state": "",
"country": "",
"zip": ""
}
},
"vehicle_snapshot": {
"id": 85460,
"tag": "8CdYme7L",
"stock_number": "00002468",
"registration": "P70GMW",
"vin": "WDC2539092F047615",
"make": "Mercedes-Benz",
"model": "GLC",
"derivative": "2.1 GLC250d AMG Line (Premium) SUV 5dr",
"colour": "White",
"mileage": 12345,
"year": "2016"
},
"payment": {
"terms": "",
"payments": [
{
"date": 1779926400,
"amount": 2000,
"method": "Bank Transfer",
"reference": "",
"notes": "",
"payee": 0
}
]
},
"finance": {
"provider": {
"id": 77869,
"name": "ABC Finance",
"amount": 10000
},
"deposit": {
"amount": 500,
"paid_by": "Customer"
}
},
"esign": {
"required": true,
"signed": false,
"name": "",
"date": ""
},
"accounting": {
"nominal": "",
"tax": "",
"sent": "",
"sync": "",
"ledger": ""
},
"lines": [
{
"id": "CMVEHICL",
"key": "CMVEHICL",
"code": "",
"name": "Mercedes-Benz GLC 2.1 GLC250d AMG Line",
"description": "",
"quantity": 1,
"price": 23771,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": "",
"options": [
{
"key": "1",
"name": "Wheel Protection",
"description": "",
"price": 100,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
}
}
],
"custom": true,
"constant": true,
"vehicle": 85460,
"discount": {},
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"part_exchange": [
{
"vehicle": "Skoda Fabia 1.2 TSI SE Estate 5dr",
"registration": "AY65YRL",
"vin": "TMBKN6NJ1GZ049678",
"mileage": 35000,
"math": "minus",
"value": 9011.81,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"purchase": "Done",
"add": "Yes",
"appraisal_id": 85461,
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"adjustments": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"discounts": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"vat_summary": [
{
"type": "standard",
"rate": 20,
"margin": false,
"net": 500,
"vat": 25
}
],
"credit_notes": [
{
"id": "000007",
"date": 0,
"note": "",
"sub_total": 208.33,
"tax": 41.67,
"total": 250,
"lines": [
{
"name": "Transfer of Vehicle Reservation Payment",
"description": "",
"quantity": 1,
"amount": 208.33,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"total": 250,
"source": ""
}
]
}
],
"linked_purchase": "000689"
}
}GET /2.0/invoices/{id} · scope invoices:read
| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
id | path | string | Yes | Resource identifier in the path. | |
fields | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. |
| Status | Description |
|---|---|
200 OK | Invoice |
Failures use the standard error responses (4xx/5xx) with the shared error envelope.
{
"success": true,
"data": {
"id": 11589,
"type": "invoice",
"number": "001956",
"contact": 25174,
"vehicle": 0,
"additional_cost_vehicle": 0,
"lead": 0,
"aftersale": 0,
"status": {
"id": 2,
"name": "paid"
},
"version": 3,
"totals": {
"sub_total": 500,
"exchange": 0,
"settlement": 0,
"adjustment": 0,
"discount": 0,
"tax": 25,
"finance": 0,
"deposit": 0,
"total": 525,
"total_sale": 525,
"total_due": 525,
"credit_sub_total": 0,
"credit_tax": 0,
"credit_total": 0
},
"scheme": "margin",
"currency": "GBP",
"settlement_outstanding": 0,
"paid_date": "2026-06-02",
"paid": 1780394814,
"created": 1780394800,
"updated": 1780394814,
"reference": "",
"nominal": "",
"invoice_date": 1779962100,
"supply_date": 1781827200,
"notes": "<p><strong>some notes</strong></p>",
"terms": "",
"options": {
"hide_vat": false,
"hide_registration": false,
"payment_online": true,
"review": false,
"eu_goods_services": false
},
"contact_snapshot": {
"id": 25174,
"name": "New Customer",
"company": "Test Ltd.",
"email": "",
"telephone": "",
"mobile": "",
"address": {
"line1": "333 Oxford Street",
"line2": "",
"line3": "",
"city": "London",
"state": "Greater London",
"country": "United Kingdom",
"zip": "W1C 2HY"
}
},
"delivery": {
"name": "",
"telephone": "",
"address": {
"line1": "",
"line2": "",
"line3": "",
"city": "",
"state": "",
"country": "",
"zip": ""
}
},
"vehicle_snapshot": {
"id": 85460,
"tag": "8CdYme7L",
"stock_number": "00002468",
"registration": "P70GMW",
"vin": "WDC2539092F047615",
"make": "Mercedes-Benz",
"model": "GLC",
"derivative": "2.1 GLC250d AMG Line (Premium) SUV 5dr",
"colour": "White",
"mileage": 12345,
"year": "2016"
},
"payment": {
"terms": "",
"payments": [
{
"date": 1779926400,
"amount": 2000,
"method": "Bank Transfer",
"reference": "",
"notes": "",
"payee": 0
}
]
},
"finance": {
"provider": {
"id": 77869,
"name": "ABC Finance",
"amount": 10000
},
"deposit": {
"amount": 500,
"paid_by": "Customer"
}
},
"esign": {
"required": true,
"signed": false,
"name": "",
"date": ""
},
"accounting": {
"nominal": "",
"tax": "",
"sent": "",
"sync": "",
"ledger": ""
},
"lines": [
{
"id": "CMVEHICL",
"key": "CMVEHICL",
"code": "",
"name": "Mercedes-Benz GLC 2.1 GLC250d AMG Line",
"description": "",
"quantity": 1,
"price": 23771,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": "",
"options": [
{
"key": "1",
"name": "Wheel Protection",
"description": "",
"price": 100,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
}
}
],
"custom": true,
"constant": true,
"vehicle": 85460,
"discount": {},
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"part_exchange": [
{
"vehicle": "Skoda Fabia 1.2 TSI SE Estate 5dr",
"registration": "AY65YRL",
"vin": "TMBKN6NJ1GZ049678",
"mileage": 35000,
"math": "minus",
"value": 9011.81,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"purchase": "Done",
"add": "Yes",
"appraisal_id": 85461,
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"adjustments": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"discounts": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"vat_summary": [
{
"type": "standard",
"rate": 20,
"margin": false,
"net": 500,
"vat": 25
}
],
"credit_notes": [
{
"id": "000007",
"date": 0,
"note": "",
"sub_total": 208.33,
"tax": 41.67,
"total": 250,
"lines": [
{
"name": "Transfer of Vehicle Reservation Payment",
"description": "",
"quantity": 1,
"amount": 208.33,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"total": 250,
"source": ""
}
]
}
],
"linked_purchase": "000689"
}
}PATCH /2.0/invoices/{id} · scope invoices:write
Update a draft invoice. Only draft (status 0) invoices can be edited, and fields apply only when supplied. The sold vehicle and the lines form one collection: a body carrying lines and/or vehicle rebuilds that collection from exactly what is supplied (send both to keep both), while a body carrying neither leaves the existing vehicle and lines untouched. Exchanges, adjustments and discounts replace their existing sets when supplied.
| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
id | path | string | Yes | Resource identifier in the path. |
| Attribute | Type | Required | Description | Example |
|---|---|---|---|---|
contact | integer or null | - | Customer contact id (supplier id for purchases). Required for invoices/orders; optional for purchases. | 25174 |
scheme | enum | - | VAT scheme. Defaults to vat. | vat |
date | string | - | Document date (YYYY-MM-DD or Unix timestamp). Defaults to now. | 2026-06-13 |
reference | string | - | Document reference (e.g. the supplier invoice number for purchases). | PO-1042 |
nominal | string | - | Document-level accounting nominal code override. | |
notes | string | - | Document notes (may contain HTML). | |
terms | string | - | Terms & conditions text (may contain HTML). | |
supply_date | integer | - | Time/date of supply (Unix timestamp). | |
payment_terms | string | - | Payment terms text. | |
options | object | - | Document output flags. | |
options.hide_vat | boolean | - | Hide the VAT breakdown on the document. | |
options.hide_registration | boolean | - | Hide the vehicle registration on the document. | |
options.payment_online | boolean | - | Offer online payment for the issued document. | |
options.eu_goods_services | boolean | - | Flag the document as an EU goods/services supply. | |
delivery | object | - | Delivery / collection party (separate from the billing contact). | |
delivery.name | string | - | Delivery contact name. | |
delivery.telephone | string | - | Delivery contact telephone. | |
delivery.address | object | - | Delivery address. | |
delivery.address.line1 | string | - | Address line 1. | |
delivery.address.line2 | string | - | Address line 2. | |
delivery.address.line3 | string | - | Address line 3. | |
delivery.address.city | string | - | Town / city. | |
delivery.address.state | string | - | County / state. | |
delivery.address.country | string | - | Country. | |
delivery.address.zip | string | - | Postcode / ZIP. | |
vehicle | object or null | - | The sold vehicle line (invoices/orders only). Identify by id or tag. Must be an in-stock vehicle in the for-sale status - the same rule as the dashboard's sale form; drafts, sold vehicles, appraisals and customer vehicles return 422. | |
vehicle.id | integer | - | Stock vehicle id. | 85460 |
vehicle.tag | string | - | Vehicle tag (alternative to id). | |
vehicle.mileage | integer | - | Sale mileage override. | |
vehicle.price | number | - | Sale price (net) override. | 13495 |
vehicle.vat | enum | - | VAT treatment of the vehicle line. | |
additional_cost_vehicle | object or null | - | Purchases only: link the WHOLE purchase to a vehicle as an additional cost (feeds the vehicle's Purchase & Costs and its profit). Lines without their own line vehicle feed this vehicle's additional-cost row (lines carrying a per-line vehicle feed that vehicle instead) - there is no per-line margin bundling on this document type. Identify by id or tag; null unlinks, a different vehicle re-targets (unlink and re-target are API-only and work on drafts). The vehicle can hold at most 50 cost rows. | |
additional_cost_vehicle.id | integer | - | Stock vehicle id. | 85460 |
additional_cost_vehicle.tag | string | - | Vehicle tag (alternative to id). | |
lines | array of object | - | Product and ad-hoc line items. On PATCH the supplied array replaces the existing lines; omit the field to keep them, or send an empty array to clear them. | |
part_exchange | array of object | - | Trade-in vehicles (max 5). | |
adjustments | array of object | - | Named value adjustments (max 5). Rejected on version 3 documents, which every new document now is: use a line for an admin fee or delivery charge, or part_exchange[].settlement for outstanding finance. | |
discounts | array of object | - | Named discounts (max 5). Version 1 documents only - version 2 documents (all new documents) take discounts per line via lines[].discount and reject this field. | |
finance | object or null | - | Finance provider funding the sale (invoices). | |
finance.provider | integer | - | Finance provider contact id. | |
finance.amount | number | - | Amount financed. | |
finance.generate | boolean | - | Auto-generate the finance invoice on issue. |
{
"contact": 25174,
"scheme": "vat",
"date": "2026-06-13",
"reference": "PO-1042",
"nominal": "",
"notes": "",
"terms": "",
"supply_date": 0,
"payment_terms": "",
"options": {
"hide_vat": false,
"hide_registration": false,
"payment_online": false,
"eu_goods_services": false
},
"delivery": {
"name": "",
"telephone": "",
"address": {
"line1": "",
"line2": "",
"line3": "",
"city": "",
"state": "",
"country": "",
"zip": ""
}
},
"vehicle": {
"id": 85460,
"tag": "",
"mileage": 0,
"price": 13495,
"vat": "vat"
},
"additional_cost_vehicle": {
"id": 85460,
"tag": ""
},
"lines": [
{
"product": 0,
"code": "",
"name": "Admin Fee",
"description": "",
"price": 199,
"vat": "standard",
"quantity": 1,
"options": [
""
],
"vehicle": 0,
"discount": {}
}
],
"part_exchange": [
{
"registration": "AY65YRL",
"mileage": 0,
"vin": "",
"value": 9000,
"math": "minus",
"type": "currency",
"vat": "standard",
"purchase": "Yes",
"add": "Yes",
"appraisal_id": 85461,
"settlement": {
"amount": 2000,
"finance_company": 4471,
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"adjustments": [
{
"name": "Delivery",
"value": 150,
"math": "plus",
"type": "currency",
"vat": "standard",
"nominal": ""
}
],
"discounts": [
{
"name": "Loyalty Discount",
"value": 250,
"math": "plus",
"type": "currency",
"vat": "standard",
"nominal": ""
}
],
"finance": {
"provider": 0,
"amount": 0,
"generate": false
}
}| Status | Description |
|---|---|
200 OK | Update Invoice |
Failures use the standard error responses (4xx/5xx) with the shared error envelope.
{
"success": true,
"data": {
"id": 11589,
"type": "invoice",
"number": "001956",
"contact": 25174,
"vehicle": 0,
"additional_cost_vehicle": 0,
"lead": 0,
"aftersale": 0,
"status": {
"id": 2,
"name": "paid"
},
"version": 3,
"totals": {
"sub_total": 500,
"exchange": 0,
"settlement": 0,
"adjustment": 0,
"discount": 0,
"tax": 25,
"finance": 0,
"deposit": 0,
"total": 525,
"total_sale": 525,
"total_due": 525,
"credit_sub_total": 0,
"credit_tax": 0,
"credit_total": 0
},
"scheme": "margin",
"currency": "GBP",
"settlement_outstanding": 0,
"paid_date": "2026-06-02",
"paid": 1780394814,
"created": 1780394800,
"updated": 1780394814,
"reference": "",
"nominal": "",
"invoice_date": 1779962100,
"supply_date": 1781827200,
"notes": "<p><strong>some notes</strong></p>",
"terms": "",
"options": {
"hide_vat": false,
"hide_registration": false,
"payment_online": true,
"review": false,
"eu_goods_services": false
},
"contact_snapshot": {
"id": 25174,
"name": "New Customer",
"company": "Test Ltd.",
"email": "",
"telephone": "",
"mobile": "",
"address": {
"line1": "333 Oxford Street",
"line2": "",
"line3": "",
"city": "London",
"state": "Greater London",
"country": "United Kingdom",
"zip": "W1C 2HY"
}
},
"delivery": {
"name": "",
"telephone": "",
"address": {
"line1": "",
"line2": "",
"line3": "",
"city": "",
"state": "",
"country": "",
"zip": ""
}
},
"vehicle_snapshot": {
"id": 85460,
"tag": "8CdYme7L",
"stock_number": "00002468",
"registration": "P70GMW",
"vin": "WDC2539092F047615",
"make": "Mercedes-Benz",
"model": "GLC",
"derivative": "2.1 GLC250d AMG Line (Premium) SUV 5dr",
"colour": "White",
"mileage": 12345,
"year": "2016"
},
"payment": {
"terms": "",
"payments": [
{
"date": 1779926400,
"amount": 2000,
"method": "Bank Transfer",
"reference": "",
"notes": "",
"payee": 0
}
]
},
"finance": {
"provider": {
"id": 77869,
"name": "ABC Finance",
"amount": 10000
},
"deposit": {
"amount": 500,
"paid_by": "Customer"
}
},
"esign": {
"required": true,
"signed": false,
"name": "",
"date": ""
},
"accounting": {
"nominal": "",
"tax": "",
"sent": "",
"sync": "",
"ledger": ""
},
"lines": [
{
"id": "CMVEHICL",
"key": "CMVEHICL",
"code": "",
"name": "Mercedes-Benz GLC 2.1 GLC250d AMG Line",
"description": "",
"quantity": 1,
"price": 23771,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": "",
"options": [
{
"key": "1",
"name": "Wheel Protection",
"description": "",
"price": 100,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
}
}
],
"custom": true,
"constant": true,
"vehicle": 85460,
"discount": {},
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"part_exchange": [
{
"vehicle": "Skoda Fabia 1.2 TSI SE Estate 5dr",
"registration": "AY65YRL",
"vin": "TMBKN6NJ1GZ049678",
"mileage": 35000,
"math": "minus",
"value": 9011.81,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"purchase": "Done",
"add": "Yes",
"appraisal_id": 85461,
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"adjustments": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"discounts": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"vat_summary": [
{
"type": "standard",
"rate": 20,
"margin": false,
"net": 500,
"vat": 25
}
],
"credit_notes": [
{
"id": "000007",
"date": 0,
"note": "",
"sub_total": 208.33,
"tax": 41.67,
"total": 250,
"lines": [
{
"name": "Transfer of Vehicle Reservation Payment",
"description": "",
"quantity": 1,
"amount": 208.33,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"total": 250,
"source": ""
}
]
}
],
"linked_purchase": "000689"
}
}DELETE /2.0/invoices/{id} · scope invoices:delete
Delete a draft invoice. Only draft (status 0) invoices can be deleted.
| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
id | path | string | Yes | Resource identifier in the path. |
| Status | Description |
|---|---|
200 OK | Delete Invoice |
Failures use the standard error responses (4xx/5xx) with the shared error envelope.
{
"success": true,
"data": {
"id": 0,
"deleted": false
}
}POST /2.0/invoices/{id}/issue · scope invoices:write
Issue a draft invoice (draft -> issued). Assigns the document number and runs the full side-effects: a part-exchange purchase invoice and finance invoice are auto-created where configured, the vehicle is queued for archive, and stock is decremented. Accounting sync fires automatically. Optional body { email: true, recipient?: "addr" } emails the issued invoice in the same call (the recipient is validated before issuing).
| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
id | path | string | Yes | Resource identifier in the path. |
| Attribute | Type | Required | Description | Example |
|---|---|---|---|---|
email | boolean | - | Email the document to its contact immediately after issuing. The recipient is validated before the document is issued. | true |
recipient | string | - | Override recipient when email is true. Defaults to the document contact's email. | customer@example.com |
{
"email": true,
"recipient": "customer@example.com"
}| Status | Description |
|---|---|
200 OK | Issue Invoice |
Failures use the standard error responses (4xx/5xx) with the shared error envelope.
{
"success": true,
"data": {
"id": 11589,
"type": "invoice",
"number": "001956",
"contact": 25174,
"vehicle": 0,
"additional_cost_vehicle": 0,
"lead": 0,
"aftersale": 0,
"status": {
"id": 2,
"name": "paid"
},
"version": 3,
"totals": {
"sub_total": 500,
"exchange": 0,
"settlement": 0,
"adjustment": 0,
"discount": 0,
"tax": 25,
"finance": 0,
"deposit": 0,
"total": 525,
"total_sale": 525,
"total_due": 525,
"credit_sub_total": 0,
"credit_tax": 0,
"credit_total": 0
},
"scheme": "margin",
"currency": "GBP",
"settlement_outstanding": 0,
"paid_date": "2026-06-02",
"paid": 1780394814,
"created": 1780394800,
"updated": 1780394814,
"reference": "",
"nominal": "",
"invoice_date": 1779962100,
"supply_date": 1781827200,
"notes": "<p><strong>some notes</strong></p>",
"terms": "",
"options": {
"hide_vat": false,
"hide_registration": false,
"payment_online": true,
"review": false,
"eu_goods_services": false
},
"contact_snapshot": {
"id": 25174,
"name": "New Customer",
"company": "Test Ltd.",
"email": "",
"telephone": "",
"mobile": "",
"address": {
"line1": "333 Oxford Street",
"line2": "",
"line3": "",
"city": "London",
"state": "Greater London",
"country": "United Kingdom",
"zip": "W1C 2HY"
}
},
"delivery": {
"name": "",
"telephone": "",
"address": {
"line1": "",
"line2": "",
"line3": "",
"city": "",
"state": "",
"country": "",
"zip": ""
}
},
"vehicle_snapshot": {
"id": 85460,
"tag": "8CdYme7L",
"stock_number": "00002468",
"registration": "P70GMW",
"vin": "WDC2539092F047615",
"make": "Mercedes-Benz",
"model": "GLC",
"derivative": "2.1 GLC250d AMG Line (Premium) SUV 5dr",
"colour": "White",
"mileage": 12345,
"year": "2016"
},
"payment": {
"terms": "",
"payments": [
{
"date": 1779926400,
"amount": 2000,
"method": "Bank Transfer",
"reference": "",
"notes": "",
"payee": 0
}
]
},
"finance": {
"provider": {
"id": 77869,
"name": "ABC Finance",
"amount": 10000
},
"deposit": {
"amount": 500,
"paid_by": "Customer"
}
},
"esign": {
"required": true,
"signed": false,
"name": "",
"date": ""
},
"accounting": {
"nominal": "",
"tax": "",
"sent": "",
"sync": "",
"ledger": ""
},
"lines": [
{
"id": "CMVEHICL",
"key": "CMVEHICL",
"code": "",
"name": "Mercedes-Benz GLC 2.1 GLC250d AMG Line",
"description": "",
"quantity": 1,
"price": 23771,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": "",
"options": [
{
"key": "1",
"name": "Wheel Protection",
"description": "",
"price": 100,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
}
}
],
"custom": true,
"constant": true,
"vehicle": 85460,
"discount": {},
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"part_exchange": [
{
"vehicle": "Skoda Fabia 1.2 TSI SE Estate 5dr",
"registration": "AY65YRL",
"vin": "TMBKN6NJ1GZ049678",
"mileage": 35000,
"math": "minus",
"value": 9011.81,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"purchase": "Done",
"add": "Yes",
"appraisal_id": 85461,
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"adjustments": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"discounts": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"vat_summary": [
{
"type": "standard",
"rate": 20,
"margin": false,
"net": 500,
"vat": 25
}
],
"credit_notes": [
{
"id": "000007",
"date": 0,
"note": "",
"sub_total": 208.33,
"tax": 41.67,
"total": 250,
"lines": [
{
"name": "Transfer of Vehicle Reservation Payment",
"description": "",
"quantity": 1,
"amount": 208.33,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"total": 250,
"source": ""
}
]
}
],
"linked_purchase": "000689"
}
}POST /2.0/invoices/{id}/cancel · scope invoices:write
Cancel a draft or issued invoice (cannot cancel a paid invoice).
| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
id | path | string | Yes | Resource identifier in the path. |
| Status | Description |
|---|---|
200 OK | Cancel Invoice |
Failures use the standard error responses (4xx/5xx) with the shared error envelope.
{
"success": true,
"data": {
"id": 11589,
"type": "invoice",
"number": "001956",
"contact": 25174,
"vehicle": 0,
"additional_cost_vehicle": 0,
"lead": 0,
"aftersale": 0,
"status": {
"id": 2,
"name": "paid"
},
"version": 3,
"totals": {
"sub_total": 500,
"exchange": 0,
"settlement": 0,
"adjustment": 0,
"discount": 0,
"tax": 25,
"finance": 0,
"deposit": 0,
"total": 525,
"total_sale": 525,
"total_due": 525,
"credit_sub_total": 0,
"credit_tax": 0,
"credit_total": 0
},
"scheme": "margin",
"currency": "GBP",
"settlement_outstanding": 0,
"paid_date": "2026-06-02",
"paid": 1780394814,
"created": 1780394800,
"updated": 1780394814,
"reference": "",
"nominal": "",
"invoice_date": 1779962100,
"supply_date": 1781827200,
"notes": "<p><strong>some notes</strong></p>",
"terms": "",
"options": {
"hide_vat": false,
"hide_registration": false,
"payment_online": true,
"review": false,
"eu_goods_services": false
},
"contact_snapshot": {
"id": 25174,
"name": "New Customer",
"company": "Test Ltd.",
"email": "",
"telephone": "",
"mobile": "",
"address": {
"line1": "333 Oxford Street",
"line2": "",
"line3": "",
"city": "London",
"state": "Greater London",
"country": "United Kingdom",
"zip": "W1C 2HY"
}
},
"delivery": {
"name": "",
"telephone": "",
"address": {
"line1": "",
"line2": "",
"line3": "",
"city": "",
"state": "",
"country": "",
"zip": ""
}
},
"vehicle_snapshot": {
"id": 85460,
"tag": "8CdYme7L",
"stock_number": "00002468",
"registration": "P70GMW",
"vin": "WDC2539092F047615",
"make": "Mercedes-Benz",
"model": "GLC",
"derivative": "2.1 GLC250d AMG Line (Premium) SUV 5dr",
"colour": "White",
"mileage": 12345,
"year": "2016"
},
"payment": {
"terms": "",
"payments": [
{
"date": 1779926400,
"amount": 2000,
"method": "Bank Transfer",
"reference": "",
"notes": "",
"payee": 0
}
]
},
"finance": {
"provider": {
"id": 77869,
"name": "ABC Finance",
"amount": 10000
},
"deposit": {
"amount": 500,
"paid_by": "Customer"
}
},
"esign": {
"required": true,
"signed": false,
"name": "",
"date": ""
},
"accounting": {
"nominal": "",
"tax": "",
"sent": "",
"sync": "",
"ledger": ""
},
"lines": [
{
"id": "CMVEHICL",
"key": "CMVEHICL",
"code": "",
"name": "Mercedes-Benz GLC 2.1 GLC250d AMG Line",
"description": "",
"quantity": 1,
"price": 23771,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": "",
"options": [
{
"key": "1",
"name": "Wheel Protection",
"description": "",
"price": 100,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
}
}
],
"custom": true,
"constant": true,
"vehicle": 85460,
"discount": {},
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"part_exchange": [
{
"vehicle": "Skoda Fabia 1.2 TSI SE Estate 5dr",
"registration": "AY65YRL",
"vin": "TMBKN6NJ1GZ049678",
"mileage": 35000,
"math": "minus",
"value": 9011.81,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"purchase": "Done",
"add": "Yes",
"appraisal_id": 85461,
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"adjustments": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"discounts": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"vat_summary": [
{
"type": "standard",
"rate": 20,
"margin": false,
"net": 500,
"vat": 25
}
],
"credit_notes": [
{
"id": "000007",
"date": 0,
"note": "",
"sub_total": 208.33,
"tax": 41.67,
"total": 250,
"lines": [
{
"name": "Transfer of Vehicle Reservation Payment",
"description": "",
"quantity": 1,
"amount": 208.33,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"total": 250,
"source": ""
}
]
}
],
"linked_purchase": "000689"
}
}POST /2.0/invoices/{id}/payments · scope invoices:payment
Record a payment against an issued invoice. When cumulative payments settle the balance the invoice is marked paid, marking the vehicle sold, adding part-exchange vehicles to stock and transferring any reserve deposit. A partial payment leaves it issued.
| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
id | path | string | Yes | Resource identifier in the path. |
| Attribute | Type | Required | Description | Example |
|---|---|---|---|---|
amount | number | Yes | Payment amount. | 525 |
method | string | Yes | Payment method (e.g. Bank Transfer, Card, Cash, Online Payment). | Bank Transfer |
date | integer | - | Payment date (Unix timestamp). Defaults to now. | |
reference | string | - | Transaction id / reference. | TXN-90187 |
payee | integer or null | - | Purchases only: the contact the money went to when not the supplier - a lender receiving a finance settlement (method "Finance Settlement"). Omit when the supplier was paid. | 4471 |
{
"amount": 525,
"method": "Bank Transfer",
"date": 0,
"reference": "TXN-90187",
"payee": 4471
}| Status | Description |
|---|---|
200 OK | Record an Invoice Payment |
Failures use the standard error responses (4xx/5xx) with the shared error envelope.
{
"success": true,
"data": {
"id": 11589,
"type": "invoice",
"number": "001956",
"contact": 25174,
"vehicle": 0,
"additional_cost_vehicle": 0,
"lead": 0,
"aftersale": 0,
"status": {
"id": 2,
"name": "paid"
},
"version": 3,
"totals": {
"sub_total": 500,
"exchange": 0,
"settlement": 0,
"adjustment": 0,
"discount": 0,
"tax": 25,
"finance": 0,
"deposit": 0,
"total": 525,
"total_sale": 525,
"total_due": 525,
"credit_sub_total": 0,
"credit_tax": 0,
"credit_total": 0
},
"scheme": "margin",
"currency": "GBP",
"settlement_outstanding": 0,
"paid_date": "2026-06-02",
"paid": 1780394814,
"created": 1780394800,
"updated": 1780394814,
"reference": "",
"nominal": "",
"invoice_date": 1779962100,
"supply_date": 1781827200,
"notes": "<p><strong>some notes</strong></p>",
"terms": "",
"options": {
"hide_vat": false,
"hide_registration": false,
"payment_online": true,
"review": false,
"eu_goods_services": false
},
"contact_snapshot": {
"id": 25174,
"name": "New Customer",
"company": "Test Ltd.",
"email": "",
"telephone": "",
"mobile": "",
"address": {
"line1": "333 Oxford Street",
"line2": "",
"line3": "",
"city": "London",
"state": "Greater London",
"country": "United Kingdom",
"zip": "W1C 2HY"
}
},
"delivery": {
"name": "",
"telephone": "",
"address": {
"line1": "",
"line2": "",
"line3": "",
"city": "",
"state": "",
"country": "",
"zip": ""
}
},
"vehicle_snapshot": {
"id": 85460,
"tag": "8CdYme7L",
"stock_number": "00002468",
"registration": "P70GMW",
"vin": "WDC2539092F047615",
"make": "Mercedes-Benz",
"model": "GLC",
"derivative": "2.1 GLC250d AMG Line (Premium) SUV 5dr",
"colour": "White",
"mileage": 12345,
"year": "2016"
},
"payment": {
"terms": "",
"payments": [
{
"date": 1779926400,
"amount": 2000,
"method": "Bank Transfer",
"reference": "",
"notes": "",
"payee": 0
}
]
},
"finance": {
"provider": {
"id": 77869,
"name": "ABC Finance",
"amount": 10000
},
"deposit": {
"amount": 500,
"paid_by": "Customer"
}
},
"esign": {
"required": true,
"signed": false,
"name": "",
"date": ""
},
"accounting": {
"nominal": "",
"tax": "",
"sent": "",
"sync": "",
"ledger": ""
},
"lines": [
{
"id": "CMVEHICL",
"key": "CMVEHICL",
"code": "",
"name": "Mercedes-Benz GLC 2.1 GLC250d AMG Line",
"description": "",
"quantity": 1,
"price": 23771,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": "",
"options": [
{
"key": "1",
"name": "Wheel Protection",
"description": "",
"price": 100,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
}
}
],
"custom": true,
"constant": true,
"vehicle": 85460,
"discount": {},
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"part_exchange": [
{
"vehicle": "Skoda Fabia 1.2 TSI SE Estate 5dr",
"registration": "AY65YRL",
"vin": "TMBKN6NJ1GZ049678",
"mileage": 35000,
"math": "minus",
"value": 9011.81,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"purchase": "Done",
"add": "Yes",
"appraisal_id": 85461,
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"adjustments": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"discounts": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"vat_summary": [
{
"type": "standard",
"rate": 20,
"margin": false,
"net": 500,
"vat": 25
}
],
"credit_notes": [
{
"id": "000007",
"date": 0,
"note": "",
"sub_total": 208.33,
"tax": 41.67,
"total": 250,
"lines": [
{
"name": "Transfer of Vehicle Reservation Payment",
"description": "",
"quantity": 1,
"amount": 208.33,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"total": 250,
"source": ""
}
]
}
],
"linked_purchase": "000689"
}
}POST /2.0/invoices/{id}/send · scope invoices:write
Email an issued invoice to its contact (or an explicit address). Sends a real email using the invoice template (or the e-sign template when e-signature is enabled).
| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
id | path | string | Yes | Resource identifier in the path. |
| Attribute | Type | Required | Description | Example |
|---|---|---|---|---|
email | string | - | Override recipient email address. Defaults to the document contact's email. | customer@example.com |
{
"email": "customer@example.com"
}| Status | Description |
|---|---|
200 OK | Email an Invoice |
Failures use the standard error responses (4xx/5xx) with the shared error envelope.
{
"success": true,
"data": {
"id": 0,
"number": "001959",
"sent": true,
"recipient": "customer@example.com",
"esign": false
}
}POST /2.0/invoices/{id}/finance-invoice · scope invoices:write
Generate the finance provider's draft invoice for a sale issued without one - the late path for the dashboard's Generate Finance Provider Invoice option (issuing a draft with finance.generate set still creates it automatically). The sale must be issued or paid, carry a finance provider contact and a finance amount, not be fully credited, and not already have a finance provider invoice. Creates the lender's draft from the sale's own stored data, links it to the sale, and marks the sale as part funded by the provider. Finance provider invoices are a MotorDesk-only document for the finance company and are not sent to accounting software. Returns the new draft invoice.
| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
id | path | string | Yes | Resource identifier in the path. |
| Status | Description |
|---|---|
201 Created | Generate Finance Provider Invoice |
Failures use the standard error responses (4xx/5xx) with the shared error envelope.
{
"success": true,
"data": {
"id": 11589,
"type": "invoice",
"number": "001956",
"contact": 25174,
"vehicle": 0,
"additional_cost_vehicle": 0,
"lead": 0,
"aftersale": 0,
"status": {
"id": 2,
"name": "paid"
},
"version": 3,
"totals": {
"sub_total": 500,
"exchange": 0,
"settlement": 0,
"adjustment": 0,
"discount": 0,
"tax": 25,
"finance": 0,
"deposit": 0,
"total": 525,
"total_sale": 525,
"total_due": 525,
"credit_sub_total": 0,
"credit_tax": 0,
"credit_total": 0
},
"scheme": "margin",
"currency": "GBP",
"settlement_outstanding": 0,
"paid_date": "2026-06-02",
"paid": 1780394814,
"created": 1780394800,
"updated": 1780394814,
"reference": "",
"nominal": "",
"invoice_date": 1779962100,
"supply_date": 1781827200,
"notes": "<p><strong>some notes</strong></p>",
"terms": "",
"options": {
"hide_vat": false,
"hide_registration": false,
"payment_online": true,
"review": false,
"eu_goods_services": false
},
"contact_snapshot": {
"id": 25174,
"name": "New Customer",
"company": "Test Ltd.",
"email": "",
"telephone": "",
"mobile": "",
"address": {
"line1": "333 Oxford Street",
"line2": "",
"line3": "",
"city": "London",
"state": "Greater London",
"country": "United Kingdom",
"zip": "W1C 2HY"
}
},
"delivery": {
"name": "",
"telephone": "",
"address": {
"line1": "",
"line2": "",
"line3": "",
"city": "",
"state": "",
"country": "",
"zip": ""
}
},
"vehicle_snapshot": {
"id": 85460,
"tag": "8CdYme7L",
"stock_number": "00002468",
"registration": "P70GMW",
"vin": "WDC2539092F047615",
"make": "Mercedes-Benz",
"model": "GLC",
"derivative": "2.1 GLC250d AMG Line (Premium) SUV 5dr",
"colour": "White",
"mileage": 12345,
"year": "2016"
},
"payment": {
"terms": "",
"payments": [
{
"date": 1779926400,
"amount": 2000,
"method": "Bank Transfer",
"reference": "",
"notes": "",
"payee": 0
}
]
},
"finance": {
"provider": {
"id": 77869,
"name": "ABC Finance",
"amount": 10000
},
"deposit": {
"amount": 500,
"paid_by": "Customer"
}
},
"esign": {
"required": true,
"signed": false,
"name": "",
"date": ""
},
"accounting": {
"nominal": "",
"tax": "",
"sent": "",
"sync": "",
"ledger": ""
},
"lines": [
{
"id": "CMVEHICL",
"key": "CMVEHICL",
"code": "",
"name": "Mercedes-Benz GLC 2.1 GLC250d AMG Line",
"description": "",
"quantity": 1,
"price": 23771,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": "",
"options": [
{
"key": "1",
"name": "Wheel Protection",
"description": "",
"price": 100,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
}
}
],
"custom": true,
"constant": true,
"vehicle": 85460,
"discount": {},
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"part_exchange": [
{
"vehicle": "Skoda Fabia 1.2 TSI SE Estate 5dr",
"registration": "AY65YRL",
"vin": "TMBKN6NJ1GZ049678",
"mileage": 35000,
"math": "minus",
"value": 9011.81,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"purchase": "Done",
"add": "Yes",
"appraisal_id": 85461,
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"adjustments": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"discounts": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"vat_summary": [
{
"type": "standard",
"rate": 20,
"margin": false,
"net": 500,
"vat": 25
}
],
"credit_notes": [
{
"id": "000007",
"date": 0,
"note": "",
"sub_total": 208.33,
"tax": 41.67,
"total": 250,
"lines": [
{
"name": "Transfer of Vehicle Reservation Payment",
"description": "",
"quantity": 1,
"amount": 208.33,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"total": 250,
"source": ""
}
]
}
],
"linked_purchase": "000689"
}
}POST /2.0/invoices/{id}/credit-notes · scope invoices:credit
Raise a credit note against an issued/paid invoice: full=true credits the whole document by VAT rate, or supply explicit lines.
| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
id | path | string | Yes | Resource identifier in the path. |
| Attribute | Type | Required | Description | Example |
|---|---|---|---|---|
full | boolean | - | Credit the entire document by VAT rate. | false |
name | string | - | Line name for a full credit (defaults to "Credit"). | |
note | string | - | Credit note free-text note. | Goodwill refund |
lines | array of object | - | Explicit credit lines (used when full is not set). |
{
"full": false,
"name": "",
"note": "Goodwill refund",
"lines": [
{
"name": "Refund: detailing",
"description": "",
"amount": 100,
"quantity": 1,
"vat": "standard",
"source": "CMVEHICL"
}
]
}| Status | Description |
|---|---|
200 OK | Raise an Invoice Credit Note |
Failures use the standard error responses (4xx/5xx) with the shared error envelope.
{
"success": true,
"data": {
"id": 11589,
"type": "invoice",
"number": "001956",
"contact": 25174,
"vehicle": 0,
"additional_cost_vehicle": 0,
"lead": 0,
"aftersale": 0,
"status": {
"id": 2,
"name": "paid"
},
"version": 3,
"totals": {
"sub_total": 500,
"exchange": 0,
"settlement": 0,
"adjustment": 0,
"discount": 0,
"tax": 25,
"finance": 0,
"deposit": 0,
"total": 525,
"total_sale": 525,
"total_due": 525,
"credit_sub_total": 0,
"credit_tax": 0,
"credit_total": 0
},
"scheme": "margin",
"currency": "GBP",
"settlement_outstanding": 0,
"paid_date": "2026-06-02",
"paid": 1780394814,
"created": 1780394800,
"updated": 1780394814,
"reference": "",
"nominal": "",
"invoice_date": 1779962100,
"supply_date": 1781827200,
"notes": "<p><strong>some notes</strong></p>",
"terms": "",
"options": {
"hide_vat": false,
"hide_registration": false,
"payment_online": true,
"review": false,
"eu_goods_services": false
},
"contact_snapshot": {
"id": 25174,
"name": "New Customer",
"company": "Test Ltd.",
"email": "",
"telephone": "",
"mobile": "",
"address": {
"line1": "333 Oxford Street",
"line2": "",
"line3": "",
"city": "London",
"state": "Greater London",
"country": "United Kingdom",
"zip": "W1C 2HY"
}
},
"delivery": {
"name": "",
"telephone": "",
"address": {
"line1": "",
"line2": "",
"line3": "",
"city": "",
"state": "",
"country": "",
"zip": ""
}
},
"vehicle_snapshot": {
"id": 85460,
"tag": "8CdYme7L",
"stock_number": "00002468",
"registration": "P70GMW",
"vin": "WDC2539092F047615",
"make": "Mercedes-Benz",
"model": "GLC",
"derivative": "2.1 GLC250d AMG Line (Premium) SUV 5dr",
"colour": "White",
"mileage": 12345,
"year": "2016"
},
"payment": {
"terms": "",
"payments": [
{
"date": 1779926400,
"amount": 2000,
"method": "Bank Transfer",
"reference": "",
"notes": "",
"payee": 0
}
]
},
"finance": {
"provider": {
"id": 77869,
"name": "ABC Finance",
"amount": 10000
},
"deposit": {
"amount": 500,
"paid_by": "Customer"
}
},
"esign": {
"required": true,
"signed": false,
"name": "",
"date": ""
},
"accounting": {
"nominal": "",
"tax": "",
"sent": "",
"sync": "",
"ledger": ""
},
"lines": [
{
"id": "CMVEHICL",
"key": "CMVEHICL",
"code": "",
"name": "Mercedes-Benz GLC 2.1 GLC250d AMG Line",
"description": "",
"quantity": 1,
"price": 23771,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": "",
"options": [
{
"key": "1",
"name": "Wheel Protection",
"description": "",
"price": 100,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
}
}
],
"custom": true,
"constant": true,
"vehicle": 85460,
"discount": {},
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"part_exchange": [
{
"vehicle": "Skoda Fabia 1.2 TSI SE Estate 5dr",
"registration": "AY65YRL",
"vin": "TMBKN6NJ1GZ049678",
"mileage": 35000,
"math": "minus",
"value": 9011.81,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"purchase": "Done",
"add": "Yes",
"appraisal_id": 85461,
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"adjustments": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"discounts": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"vat_summary": [
{
"type": "standard",
"rate": 20,
"margin": false,
"net": 500,
"vat": 25
}
],
"credit_notes": [
{
"id": "000007",
"date": 0,
"note": "",
"sub_total": 208.33,
"tax": 41.67,
"total": 250,
"lines": [
{
"name": "Transfer of Vehicle Reservation Payment",
"description": "",
"quantity": 1,
"amount": 208.33,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"total": 250,
"source": ""
}
]
}
],
"linked_purchase": "000689"
}
}DELETE /2.0/invoices/{id}/credit-notes/{credit_id} · scope invoices:credit
Remove a credit note by its number.
| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
id | path | string | Yes | Resource identifier in the path. | |
credit_id | path | string | Yes | Resource identifier in the path. |
| Status | Description |
|---|---|
200 OK | Remove an Invoice Credit Note |
Failures use the standard error responses (4xx/5xx) with the shared error envelope.
{
"success": true,
"data": {
"id": 11589,
"type": "invoice",
"number": "001956",
"contact": 25174,
"vehicle": 0,
"additional_cost_vehicle": 0,
"lead": 0,
"aftersale": 0,
"status": {
"id": 2,
"name": "paid"
},
"version": 3,
"totals": {
"sub_total": 500,
"exchange": 0,
"settlement": 0,
"adjustment": 0,
"discount": 0,
"tax": 25,
"finance": 0,
"deposit": 0,
"total": 525,
"total_sale": 525,
"total_due": 525,
"credit_sub_total": 0,
"credit_tax": 0,
"credit_total": 0
},
"scheme": "margin",
"currency": "GBP",
"settlement_outstanding": 0,
"paid_date": "2026-06-02",
"paid": 1780394814,
"created": 1780394800,
"updated": 1780394814,
"reference": "",
"nominal": "",
"invoice_date": 1779962100,
"supply_date": 1781827200,
"notes": "<p><strong>some notes</strong></p>",
"terms": "",
"options": {
"hide_vat": false,
"hide_registration": false,
"payment_online": true,
"review": false,
"eu_goods_services": false
},
"contact_snapshot": {
"id": 25174,
"name": "New Customer",
"company": "Test Ltd.",
"email": "",
"telephone": "",
"mobile": "",
"address": {
"line1": "333 Oxford Street",
"line2": "",
"line3": "",
"city": "London",
"state": "Greater London",
"country": "United Kingdom",
"zip": "W1C 2HY"
}
},
"delivery": {
"name": "",
"telephone": "",
"address": {
"line1": "",
"line2": "",
"line3": "",
"city": "",
"state": "",
"country": "",
"zip": ""
}
},
"vehicle_snapshot": {
"id": 85460,
"tag": "8CdYme7L",
"stock_number": "00002468",
"registration": "P70GMW",
"vin": "WDC2539092F047615",
"make": "Mercedes-Benz",
"model": "GLC",
"derivative": "2.1 GLC250d AMG Line (Premium) SUV 5dr",
"colour": "White",
"mileage": 12345,
"year": "2016"
},
"payment": {
"terms": "",
"payments": [
{
"date": 1779926400,
"amount": 2000,
"method": "Bank Transfer",
"reference": "",
"notes": "",
"payee": 0
}
]
},
"finance": {
"provider": {
"id": 77869,
"name": "ABC Finance",
"amount": 10000
},
"deposit": {
"amount": 500,
"paid_by": "Customer"
}
},
"esign": {
"required": true,
"signed": false,
"name": "",
"date": ""
},
"accounting": {
"nominal": "",
"tax": "",
"sent": "",
"sync": "",
"ledger": ""
},
"lines": [
{
"id": "CMVEHICL",
"key": "CMVEHICL",
"code": "",
"name": "Mercedes-Benz GLC 2.1 GLC250d AMG Line",
"description": "",
"quantity": 1,
"price": 23771,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": "",
"options": [
{
"key": "1",
"name": "Wheel Protection",
"description": "",
"price": 100,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
}
}
],
"custom": true,
"constant": true,
"vehicle": 85460,
"discount": {},
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"part_exchange": [
{
"vehicle": "Skoda Fabia 1.2 TSI SE Estate 5dr",
"registration": "AY65YRL",
"vin": "TMBKN6NJ1GZ049678",
"mileage": 35000,
"math": "minus",
"value": 9011.81,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"purchase": "Done",
"add": "Yes",
"appraisal_id": 85461,
"settlement": {
"amount": 2000,
"finance_company": 4471,
"finance_company_name": "Close Brothers Motor Finance",
"reference": "AG-12345",
"valid_until": "2026-09-06"
}
}
],
"adjustments": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"discounts": [
{
"name": "Admin Fee",
"math": "plus",
"value": 99,
"type": "currency",
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"nominal": ""
}
],
"vat_summary": [
{
"type": "standard",
"rate": 20,
"margin": false,
"net": 500,
"vat": 25
}
],
"credit_notes": [
{
"id": "000007",
"date": 0,
"note": "",
"sub_total": 208.33,
"tax": 41.67,
"total": 250,
"lines": [
{
"name": "Transfer of Vehicle Reservation Payment",
"description": "",
"quantity": 1,
"amount": 208.33,
"vat": {
"category": "reduced",
"label": "5% VAT",
"rate": 5
},
"total": 250,
"source": ""
}
]
}
],
"linked_purchase": "000689"
}
}