> For the complete documentation index, see [llms.txt](https://docs.gem-suite.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gem-suite.com/api-reference/resources/purchases.md).

# Purchases

## List all purchases

<mark style="color:blue;">`GET`</mark> `https://app.gem-books.com/api/purchases`

This endpoint allows you to get the list of your purchases. \
The transactions are returned sorted by most recent number.

#### Headers

| Name                                             | Type   | Description                  |
| ------------------------------------------------ | ------ | ---------------------------- |
| Authentication<mark style="color:red;">\*</mark> | string | Bearer Token                 |
| Accept                                           | string | Should be `application/json` |

{% tabs %}
{% tab title="200: OK " %}

```json
{
  "data": [
    {
      "id": 27,
      "purchase_number": 37,
      "invoice_number": null,
      "internal_number": "",
      "external_number": "",
      "quote_number": null,
      "provider_id": 1,
      "active": 1,
      "date": "2024-12-27",
      "contact_name": "",
      "contact_email": null,
      "contact_phone": null,
      "contact_address": "",
      "contact_city": "",
      "contact_state": "QC",
      "contact_zip": "",
      "arrondissement": "",
      "contact_facturation": null,
      "contact_facturation_email": null,
      "contact_facturation_phone": null,
      "facturation1": "",
      "facturation2": null,
      "facturation_ville": null,
      "facturation_pays": 1,
      "facturation_prov": "QC",
      "facturation_cp": null,
      "livraison_id": 0,
      "delivery_name": null,
      "livraison_client_id": 0,
      "delivery_email": null,
      "delivery_phone": null,
      "delivery_address": "",
      "delivery_city": null,
      "delivery_state": "QC",
      "delivery_zip": null,
      "date_rec": null,
      "date_liv": null,
      "responsible": null,
      "seller_id": 230,
      "expediteur": null,
      "expediteur_ref": null,
      "tags": 0,
      "invoice_receive": 0,
      "subtotal": "0.00",
      "total": "0.00",
      "currency": 1,
      "options": null,
      "branch_id": 1,
      "has_cc": 0,
      "sale_id": 0,
      "products_lines": [],
      "documents": [],
      "system_id": 99217
    },
    {
      "id": 26,
      "purchase_number": 36,
      "invoice_number": null,
      "internal_number": "",
      "external_number": "",
      "quote_number": null,
      "provider_id": 1,
      "active": 1,
      "date": "2024-12-27",
      "contact_name": "",
      "contact_email": null,
      "contact_phone": null,
      "contact_address": "",
      "contact_city": "",
      "contact_state": "QC",
      "contact_zip": "",
      "arrondissement": "",
      "contact_facturation": null,
      "contact_facturation_email": null,
      "contact_facturation_phone": null,
      "facturation1": "",
      "facturation2": null,
      "facturation_ville": null,
      "facturation_pays": 1,
      "facturation_prov": "QC",
      "facturation_cp": null,
      "livraison_id": 0,
      "delivery_name": null,
      "livraison_client_id": 0,
      "delivery_email": null,
      "delivery_phone": null,
      "delivery_address": "",
      "delivery_city": null,
      "delivery_state": "QC",
      "delivery_zip": null,
      "date_rec": null,
      "date_liv": null,
      "responsible": null,
      "seller_id": 230,
      "expediteur": null,
      "expediteur_ref": null,
      "tags": 0,
      "invoice_receive": 0,
      "subtotal": "0.00",
      "total": "0.00",
      "currency": 1,
      "options": null,
      "branch_id": 1,
      "has_cc": 0,
      "sale_id": 0,
      "products_lines": [],
      "documents": [],
      "system_id": 99217
    },
      "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 500,
    "total": 2
  },
  "success": true
}
```

{% endtab %}
{% endtabs %}

## List a specific purchase

<mark style="color:blue;">`GET`</mark> `https://app.gem-books.com/api/purchases/:id`

This endpoint allows you to get one specific purchase.&#x20;

#### Headers

| Name                                             | Type   | Description                  |
| ------------------------------------------------ | ------ | ---------------------------- |
| Authentication<mark style="color:red;">\*</mark> | string | Bearer Token                 |
| Accept                                           | string | Should be `application/json` |

{% tabs %}
{% tab title="200: OK " %}

```json
{
  "data": {
    "id": 26,
    "purchase_number": 36,
    "invoice_number": null,
    "internal_number": "",
    "external_number": "",
    "quote_number": null,
    "provider_id": 1,
    "active": 1,
    "date": "2024-12-27",
    "contact_name": "",
    "contact_email": null,
    "contact_phone": null,
    "contact_address": "",
    "contact_city": "",
    "contact_state": "QC",
    "contact_zip": "",
    "arrondissement": "",
    "contact_facturation": null,
    "contact_facturation_email": null,
    "contact_facturation_phone": null,
    "facturation1": "",
    "facturation2": null,
    "facturation_ville": null,
    "facturation_pays": 1,
    "facturation_prov": "QC",
    "facturation_cp": null,
    "livraison_id": 0,
    "delivery_name": null,
    "livraison_client_id": 0,
    "delivery_email": null,
    "delivery_phone": null,
    "delivery_address": "",
    "delivery_city": null,
    "delivery_state": "QC",
    "delivery_zip": null,
    "date_rec": null,
    "date_liv": null,
    "responsible": null,
    "seller_id": 230,
    "expediteur": null,
    "expediteur_ref": null,
    "tags": 0,
    "invoice_receive": 0,
    "subtotal": "0.00",
    "total": "0.00",
    "currency": 1,
    "options": null,
    "branch_id": 1,
    "has_cc": 0,
    "sale_id": 0,
    "products_lines": [],
    "documents": [],
    "system_id": 99217
  },
  "success": true
}
```

{% endtab %}
{% endtabs %}

## Create a purchase

<mark style="color:green;">`POST`</mark> `https://app.gem-books.com/api/purchases`

#### Headers

| Name           | Type    | Description                                                                                             |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| Authentication | string  | Bearer Token                                                                                            |
| Accept         | string  | Should be `application/json`                                                                            |
| branch\_id     | integer | Value  by default is 1 corresponding to the head office. Otherwise the branch must exist and be active. |

{% tabs %}
{% tab title="200: OK " %}

```json
{
  "data": {
    "id": 27,
    "purchase_number": 37,
    "invoice_number": null,
    "internal_number": "",
    "external_number": "",
    "quote_number": null,
    "provider_id": 1,
    "active": 1,
    "date": "2024-12-27",
    "contact_name": "",
    "contact_email": null,
    "contact_phone": null,
    "contact_address": "",
    "contact_city": "",
    "contact_state": "QC",
    "contact_zip": "",
    "arrondissement": "",
    "contact_facturation": null,
    "contact_facturation_email": null,
    "contact_facturation_phone": null,
    "facturation1": "",
    "facturation2": null,
    "facturation_ville": null,
    "facturation_pays": 1,
    "facturation_prov": "QC",
    "facturation_cp": null,
    "livraison_id": 0,
    "delivery_name": null,
    "livraison_client_id": 0,
    "delivery_email": null,
    "delivery_phone": null,
    "delivery_address": "",
    "delivery_city": null,
    "delivery_state": "QC",
    "delivery_zip": null,
    "date_rec": null,
    "date_liv": null,
    "responsible": null,
    "seller_id": 230,
    "expediteur": null,
    "expediteur_ref": null,
    "tags": 0,
    "invoice_receive": 0,
    "subtotal": "0.00",
    "total": "0.00",
    "currency": 1,
    "options": null,
    "branch_id": 1,//Branch must exist
    "has_cc": 0,
    "sale_id": 0,
    "products_lines": [],
    "documents": [],
    "system_id": 99217
  },
  "success": true
}
```

{% endtab %}
{% endtabs %}

#### Body Example

```
{
    "invoice_number": "1001234",
    "date": "2024-12-27",
    "contact_name": "John Smith",
    "contact_email": "jsmith@company.com"
}
```

## Update a purchase

<mark style="color:orange;">`PUT`</mark> `https://app.gem-books.com/api/purchase/:id`

#### Headers

| Name           | Type    | Description                                                                                             |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| Authentication | string  | Bearer Token                                                                                            |
| Accept         | string  | Should be `application/json`                                                                            |
| branch\_id     | integer | Value  by default is 1 corresponding to the head office. Otherwise the branch must exist and be active. |

{% tabs %}
{% tab title="200: OK " %}

```json
{
  "data": {
    "id": 27,
    "purchase_number": 37,
    "invoice_number": null,
    "internal_number": "",
    "external_number": "",
    "quote_number": null,
    "provider_id": 1,
    "active": 1,
    "date": "2024-12-28",
    "contact_name": "John Smith",
    "contact_email": null,
    "contact_phone": null,
    "contact_address": "",
    "contact_city": "",
    "contact_state": "QC",
    "contact_zip": "",
    "arrondissement": "",
    "contact_facturation": null,
    "contact_facturation_email": null,
    "contact_facturation_phone": null,
    "facturation1": "",
    "facturation2": null,
    "facturation_ville": null,
    "facturation_pays": 1,
    "facturation_prov": "QC",
    "facturation_cp": null,
    "livraison_id": 0,
    "delivery_name": null,
    "livraison_client_id": 0,
    "delivery_email": null,
    "delivery_phone": null,
    "delivery_address": "",
    "delivery_city": null,
    "delivery_state": "QC",
    "delivery_zip": null,
    "date_rec": null,
    "date_liv": null,
    "responsible": null,
    "seller_id": 230,
    "expediteur": null,
    "expediteur_ref": null,
    "tags": 0,
    "invoice_receive": 0,
    "subtotal": "0.00",
    "total": "0.00",
    "currency": 1,
    "options": null,
    "branch_id": 1,
    "has_cc": 0,
    "sale_id": 0,
    "products_lines": [],
    "documents": [],
    "system_id": 99217
  },
  "success": true
}
```

{% endtab %}
{% endtabs %}

#### Body Example

```json
{
    "date": "2024-12-28",
    "contact_name": "John Smith"
}
```