Read and manage purchases - filter and page through records with compact or full response views, and create, edit, issue, pay and cancel 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/purchases · scope purchases: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. | |
settlement_outstanding | query | boolean | - | true lists only purchases whose expected finance settlement has not yet been fully recorded as paid to the lender. The paid side reads the payment projection (payments recorded with the "Finance Settlement" method, or to a named payee); each document's own settlement_outstanding field remains the authoritative figure. | |
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 purchases |
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/purchases · scope purchases:write
Create a draft purchase (supplier invoice). The contact is the supplier and is optional; no sold-vehicle line. Pass additional_cost_vehicle to link the purchase to a vehicle as an additional cost (the default for every line), and/or a per-line vehicle on individual lines to attribute those lines to other vehicles - each vehicle receives its own cost row (no per-line margin bundling on purchases).
| 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 Purchase |
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/purchases/{id} · scope purchases: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 | Purchase |
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/purchases/{id} · scope purchases:write
Update a draft purchase. Draft (status 0) only; fields apply only when supplied - omitting lines keeps the existing lines (send lines: [] to clear them), so a link-only body changes additional_cost_vehicle without touching the document. An additional-cost vehicle link is preserved (and its cost row re-synced) unless additional_cost_vehicle changes it: null unlinks the vehicle only, a different vehicle re-targets. Purchases linked to a vehicle ACQUISITION return 409 purchase_acquisition_linked - manage those from the dashboard.
| 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 Purchase |
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/purchases/{id} · scope purchases:delete
Delete a draft purchase. Draft (status 0) only. A linked vehicle additional-cost is unwound first.
| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
id | path | string | Yes | Resource identifier in the path. |
| Status | Description |
|---|---|
200 OK | Delete Purchase |
Failures use the standard error responses (4xx/5xx) with the shared error envelope.
{
"success": true,
"data": {
"id": 0,
"deleted": false
}
}POST /2.0/purchases/{id}/issue · scope purchases:write
Issue a draft purchase (draft -> issued). Optional body { email: true, recipient?: "addr" } emails it in the same call.
| 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 Purchase |
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/purchases/{id}/cancel · scope purchases:write
Cancel a purchase (unwinds any linked vehicle additional-cost).
| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
id | path | string | Yes | Resource identifier in the path. |
| Status | Description |
|---|---|
200 OK | Cancel Purchase |
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/purchases/{id}/payments · scope purchases:payment
Record a payment against an issued purchase (supplier payment).
| 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 a Purchase 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/purchases/{id}/send · scope purchases:write
Email an issued purchase to its supplier (or an explicit address).
| 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 a Purchase |
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
}
}GET /2.0/purchases/pending · scope purchases:read
List supplier-invoice files uploaded to the pending purchases queue, awaiting review inside MotorDesk.
| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
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 | List Pending Purchases |
Failures use the standard error responses (4xx/5xx) with the shared error envelope.
{
"success": true,
"data": [
{
"pending": [
{
"id": 4821,
"filename": "supplier-invoice.pdf",
"extension": "pdf",
"source": "upload",
"uploaded": 1771027200
}
],
"count": 3
}
],
"meta": {
"pagination": {
"page": 0,
"per_page": 0,
"total": 0,
"total_pages": 0,
"next_cursor": ""
}
}
}POST /2.0/purchases/pending · scope purchases:write
Upload a supplier-invoice file (base64 JPG, PNG or PDF) to the pending purchases queue. The file is held for the dealer to review and turn into a purchase inside MotorDesk, where the OCR/auto-read runs. The API performs no OCR.
| Attribute | Type | Required | Description | Example |
|---|---|---|---|---|
file | string | Yes | Base64 file data (optionally a data: URL). | data:application/pdf;base64,JVBERi0xLjQK... |
filename | string | - | Original filename (used for display and to infer the extension). | supplier-invoice.pdf |
extension | enum | - | File extension when not derivable from the filename. | pdf |
{
"file": "data:application/pdf;base64,JVBERi0xLjQK...",
"filename": "supplier-invoice.pdf",
"extension": "pdf"
}| Status | Description |
|---|---|
200 OK | Upload a Pending Purchase |
Failures use the standard error responses (4xx/5xx) with the shared error envelope.
{
"success": true,
"data": {
"id": 4821,
"filename": "supplier-invoice.pdf",
"extension": "pdf",
"source": "upload",
"uploaded": 1771027200
}
}DELETE /2.0/purchases/pending/{pending_id} · scope purchases:delete
Remove a pending purchase from the queue and delete its uploaded file.
| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
pending_id | path | string | Yes | Resource identifier in the path. |
| Status | Description |
|---|---|
200 OK | Remove a Pending Purchase |
Failures use the standard error responses (4xx/5xx) with the shared error envelope.
{
"success": true,
"data": {
"id": 0,
"deleted": false
}
}