some notes
` | | `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` | **Example object** ```json { "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": "some notes
", "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" } ``` ## Endpoints ### GET List Orders `GET /2.0/orders` · scope `orders:read` **Parameters (14)** | 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. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Paginated orders | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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": "some notes
", "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 Create Order `POST /2.0/orders` · scope `orders:write` Create a draft order (offer/quote). Same body as invoices; orders convert to invoices. **Request body** | 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. | | ```json { "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 } } ``` **Responses** | Status | Description | | --- | --- | | `201` Created | Create Order | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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": "some notes
", "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 Get Order `GET /2.0/orders/{id}` · scope `orders:read` **Parameters (2)** | 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. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Order | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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": "some notes
", "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 Update Order `PATCH /2.0/orders/{id}` · scope `orders:write` Update a draft order. Draft (status 0) only; fields apply only when supplied. A body carrying lines and/or vehicle rebuilds the line collection from exactly what is supplied; a body carrying neither leaves the existing lines untouched. **Parameters (1)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Request body** | 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. | | ```json { "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 } } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Update Order | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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": "some notes
", "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 Delete Order `DELETE /2.0/orders/{id}` · scope `orders:delete` Delete a draft order. Draft (status 0) only. **Parameters (1)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Delete Order | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "success": true, "data": { "id": 0, "deleted": false } } ``` ### Issue ### POST Issue Order `POST /2.0/orders/{id}/issue` · scope `orders:write` Issue a draft order (draft -> issued). Optional body { email: true, recipient?: "addr" } emails it in the same call. **Parameters (1)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Request body** | 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` | ```json { "email": true, "recipient": "customer@example.com" } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Issue Order | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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": "some notes
", "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" } } ``` ### Cancel ### POST Cancel Order `POST /2.0/orders/{id}/cancel` · scope `orders:write` Cancel a draft or issued order. **Parameters (1)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Cancel Order | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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": "some notes
", "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" } } ``` ### Convert ### POST Convert Order to Invoice `POST /2.0/orders/{id}/convert` · scope `orders:write` Convert an issued order into a new draft invoice. The order is marked converted; the new invoice is returned. **Parameters (1)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Convert Order to Invoice | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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": "some notes
", "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" } } ``` ### Send ### POST Email an Order `POST /2.0/orders/{id}/send` · scope `orders:write` Email an issued order to its contact (or an explicit address). **Parameters (1)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `email` | string | - | Override recipient email address. Defaults to the document contact's email. | `customer@example.com` | ```json { "email": "customer@example.com" } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Email an Order | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "success": true, "data": { "id": 0, "number": "001959", "sent": true, "recipient": "customer@example.com", "esign": false } } ```