[← API v2 Overview](https://motordesk.com/api-docs/v2/)

# Deals

Read checkout/deal records for reporting, integrations, and status checks.

## The Deal Object

Generated from the OpenAPI schema. Always matches the live API.

**Fields (19)**

| Attribute | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `id` | integer | - | Deal id. |  |
| `deal` | string | - | Deal number. |  |
| `reference` | string | - | Deal reference. |  |
| `contact` | integer or null | - | Contact id, or null. |  |
| `vehicle` | integer or null | - | Vehicle id, or null. |  |
| `stage` | object | - | Current deal stage. |  |
| `stage.name` | string | - | Stage key. |  |
| `stage.label` | string | - | Human-readable stage label. |  |
| `source` | string | - | Deal source. |  |
| `channel` | string | - | Originating channel. |  |
| `created` | integer | - | Unix timestamp the deal was created. |  |
| `updated` | integer | - | Unix timestamp the deal was last updated. |  |
| `sections` | object | - | Which deal sections are present (full view only). |  |
| `sections.part_exchange` | boolean | - | Whether a part-exchange section is present. |  |
| `sections.product` | boolean | - | Whether a product section is present. |  |
| `sections.delivery_collection` | boolean | - | Whether a delivery/collection section is present. |  |
| `sections.finance` | boolean | - | Whether a finance section is present. |  |
| `sections.payment` | boolean | - | Whether a payment section is present. |  |
| `summary` | object | - | Whitelisted scalar summary of the part_exchange, delivery_collection, and finance sections (full view only). |  |

**Example object**

```json
{
    "id": 0,
    "deal": "",
    "reference": "",
    "contact": 0,
    "vehicle": 0,
    "stage": {
        "name": "",
        "label": ""
    },
    "source": "",
    "channel": "",
    "created": 0,
    "updated": 0,
    "sections": {
        "part_exchange": false,
        "product": false,
        "delivery_collection": false,
        "finance": false,
        "payment": false
    },
    "summary": {}
}
```

## Endpoints

### GET List Deals

`GET /2.0/deals` · scope `deals:read`

List deals with pagination and optional filters (stage, source, channel, created/updated range).

**Parameters (12)**

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `page` | query | integer | - | Page number, starting at 1 (offset pagination). |  |
| `per_page` | query | integer | - | Results per page (maximum 500). |  |
| `view` | query | enum | - | Response detail: "simple" for a compact object or "full" for the complete object. |  |
| `contact` | query | integer | - | Filter by contact id. |  |
| `vehicle` | query | integer | - | Filter by vehicle id. |  |
| `stage` | query | string | - | Filter by stage. |  |
| `channel` | query | string | - | Filter by channel. |  |
| `reference` | query | string | - | Filter by reference. |  |
| `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. |  |
| `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 deals |

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,
            "deal": "",
            "reference": "",
            "contact": 0,
            "vehicle": 0,
            "stage": {
                "name": "",
                "label": ""
            },
            "source": "",
            "channel": "",
            "created": 0,
            "updated": 0,
            "sections": {
                "part_exchange": false,
                "product": false,
                "delivery_collection": false,
                "finance": false,
                "payment": false
            },
            "summary": {}
        }
    ],
    "meta": {
        "pagination": {
            "page": 0,
            "per_page": 0,
            "total": 0,
            "total_pages": 0,
            "next_cursor": ""
        }
    }
}
```

### GET Get Deal

`GET /2.0/deals/{id}` · scope `deals:read`

Retrieve a single deal by id, including its customer, vehicle, and stage.

**Parameters (3)**

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `id` | path | string | Yes | Resource identifier in the path. |  |
| `view` | query | enum | - | Response detail: "simple" for a compact object or "full" for the complete object. |  |
| `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. |  |

**Responses**

| Status | Description |
| --- | --- |
| `200` OK | Deal |

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,
        "deal": "",
        "reference": "",
        "contact": 0,
        "vehicle": 0,
        "stage": {
            "name": "",
            "label": ""
        },
        "source": "",
        "channel": "",
        "created": 0,
        "updated": 0,
        "sections": {
            "part_exchange": false,
            "product": false,
            "delivery_collection": false,
            "finance": false,
            "payment": false
        },
        "summary": {}
    }
}
```