> For the complete documentation index, see [llms.txt](https://doc.blowhorn.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.blowhorn.com/api-docs/wms-inbound/purchase-orders.md).

# Purchase Orders

Purchase Order is the build of materials / request list of inventory to be fulfilled by the warehouse

## Fetch Purchase Order(s)

<mark style="color:blue;">`GET`</mark> `/wms/purchase-order`

Use this api to get the details of the Purchase Order Receipt providing details on whether the warehouse management system was successful in receiving the requested quantity of each detail line on the PO. It chiefly contains the status, phone number and invoice number.

#### Query Parameters

| Name                  | Type   | Description                                                                                                                                                                                                                                                   |
| --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                    | String | id number of the purchase order returned at the time of purchase order creation.                                                                                                                                                                              |
| po\_number            | String | purchase order number                                                                                                                                                                                                                                         |
| supplier              | String | supplier id for the purchase order                                                                                                                                                                                                                            |
| supplier\_name        | String | supplier name for the purchase order                                                                                                                                                                                                                          |
| description           | String | Full or partial description text of matching purchase order                                                                                                                                                                                                   |
| site                  | String | site id to which purchase order was created for.                                                                                                                                                                                                              |
| site\_name            | String | site name to which purchase order was created for.                                                                                                                                                                                                            |
| status                | String | <p>Status of the purchase order. </p><p>Ex:New, In-Progress, Completed, Expired </p>                                                                                                                                                                          |
| delivery\_date\_start | String | <p>Start date which is inclusive to filter the result based on.</p><p><strong>Note:</strong> This works only if both <strong>delivery\_date\_start</strong> and <strong>delivery\_date\_end</strong> are provided. </p><p><strong>Ex:</strong> 2022-01-01</p> |
| delivery\_date\_end   | String | <p>End date which is inclusive to filter the result based on.</p><p><strong>Note:</strong> This works only if both <strong>delivery\_date\_start</strong> and <strong>delivery\_date\_end</strong> are provided.</p><p><strong>Ex:</strong> 2022-01-01</p>    |
| expiry\_date\_start   | String | <p>Start date which is inclusive to filter the result based on.</p><p><strong>Note:</strong> This works only if both <strong>expiry\_date\_start</strong> and <strong>expiry\_date\_end</strong> are provided.</p><p><strong>Ex:</strong> 2022-01-01</p>      |
| expiry\_date\_end     | String | <p>End date which is inclusive to filter the result based on.</p><p><strong>Note:</strong> This works only if both <strong>expiry\_date\_start</strong> and <strong>expiry\_date\_end</strong> are provided.</p><p><strong>Ex:</strong> 2022-01-01</p>        |
| invoice\_number       | String | Invoice number for the purchase order.                                                                                                                                                                                                                        |

#### Headers

| Name                                       | Type   | Description                              |
| ------------------------------------------ | ------ | ---------------------------------------- |
| API\_KEY<mark style="color:red;">\*</mark> | string | API key obtained by the Customer/Partner |

{% tabs %}
{% tab title="200 Successful Result" %}

```json
{
    "count": 1,
    "previous": null,
    "next": 0,
    "result": [
        {
            "id": 1,
            "sku_lines": [
                {
                    "id": 9,
                    "sku": "Sample 123456",
                    "pack_config": {
                        "id": 4,
                        "tracking_level": "Each",
                        "created_date": "2021-07-30T17:53:01.396745+05:30",
                        "modified_date": "2021-07-30T17:53:01.397988+05:30",
                        "name": "Box of 25",
                        "each_volume": 1,
                        "each_weight": 250,
                        "tag_volume": 1,
                        "use_each_volume": true,
                        "use_tag_volume": false,
                        "uom": null,
                        "created_by": 108434,
                        "modified_by": 108434,
                        "each_dimension": null,
                        "customer": 40082
                    },
                    "created_date": "2022-05-26T12:47:45.228470+05:30",
                    "modified_date": "2022-05-26T12:47:45.228611+05:30",
                    "status": "New",
                    "qty": 77.0,
                    "qty_received": 6.0,
                    "price_per_qty": 22.0,
                    "item_desc": "Nice quality",
                    "created_by": null,
                    "modified_by": null,
                    "purchase_order": 941,
                    "maximum_retail_price": 25.0,
                    "discount": 3.0,
                    "discount_percentage": 12.0
                }
            ],
            "created_date": "2021-09-18T18:24:56.142039+05:30",
            "modified_date": "2021-09-18T18:24:58.238885+05:30",
            "po_number": "180921125456141585",
            "receiving_number": "RN180921125456590192",
            "invoice_number": null,
            "description": null,
            "delivery_date": "2021-09-18T18:24:56.141581+05:30",
            "expiry_date": null,
            "status": "Completed",
            "total_price": 0,
            "batch": null,
            "serial_number": null,
            "file": "http://localhost/media/uploads/documents/wmss/purchaseorder_1/2021-09-18/1W4MYRU/RN180921125456590192.PDF",
            "created_by": 109050,
            "modified_by": 109050,
            "supplier": 4,
            "site": 7
        }
    ]
}
```

{% endtab %}

{% tab title="401 Unauthorised / Wrong api key" %}

```json
{
  "status": "FAIL",
  "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="500 Unexpected error" %}

```json
{
  "status": "FAIL",
  "message": "Unexpected error"
}
```

{% endtab %}

{% tab title="200: OK No data for the filter criteria" %}

```javascript
{
    "count": 1,
    "previous": null,
    "next": 0,
    "result": []
}
```

{% endtab %}
{% endtabs %}

## Create a Purchase Order

<mark style="color:green;">`POST`</mark> `/wms/purchase-order`

Use this api to create a purchase order. A purchase order is a commercial document with agreed prices between buyer and seller. It is usually sent by the warehouse manager post getting the goods as a receipt.

#### Headers

| Name                                       | Type   | Description                              |
| ------------------------------------------ | ------ | ---------------------------------------- |
| API\_KEY<mark style="color:red;">\*</mark> | string | API key obtained by the Customer/Partner |

#### Request Body

| Name                                             | Type   | Description                                                                                                                                                                                                         |
| ------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| po\_number<mark style="color:red;">\*</mark>     | String | Purchase Order number                                                                                                                                                                                               |
| supplier                                         | String | <p>Supplier id for the purchase order.</p><p><strong>Note:</strong> This field is conditionally optional. Either <strong>supplier</strong> or <strong>supplier\_name</strong> should be provided.</p>               |
| supplier\_name                                   | String | <p>Supplier name for the purchase order.</p><p><strong>Note:</strong> This field is conditionally optional. Either <strong>supplier</strong> or <strong>supplier\_name</strong> should be provided.</p>             |
| description                                      | String | Full or partial description text of matching purchase order                                                                                                                                                         |
| site                                             | String | <p>Site id to which purchase order was created for. </p><p><strong>Note:</strong> This field is conditionally optional. Either <strong>site</strong> or <strong>site\_name</strong> should be provided.</p>         |
| site\_name                                       | String | <p>Unique Site name to which purchase order was created for.</p><p><strong>Note:</strong> This field is conditionally optional. Either <strong>site</strong> or <strong>site\_name</strong> should be provided.</p> |
| status                                           | String | <p>Status of the purchase order. </p><p>Ex<strong>: New, In-Progress, Completed, Expired</strong> </p>                                                                                                              |
| delivery\_date                                   | String | <p>Delivery date of the purchase order.</p><p><strong>Ex:</strong>2022-01-01</p>                                                                                                                                    |
| expiry\_date                                     | String | <p>Expiry date of the purchase order.</p><p><strong>Ex:</strong>2022-01-01</p>                                                                                                                                      |
| total\_price                                     | String | total price of all the items of the same SKU                                                                                                                                                                        |
| batch                                            | String | Batch number                                                                                                                                                                                                        |
| serial\_number                                   | String | Serial Number                                                                                                                                                                                                       |
| sku\_lines<mark style="color:red;">\*</mark>     | String | Array containing SKUs information against those purchase order is created                                                                                                                                           |
| sku\_lines/sku\_name                             | String | SKU name which should be uniquely identifiable in Blowhorn system.                                                                                                                                                  |
| sku\_lines/status                                | String | ?                                                                                                                                                                                                                   |
| sku\_lines/qty<mark style="color:red;">\*</mark> | String | Total quantity of the same SKU                                                                                                                                                                                      |
| sku\_lines/price\_per\_qty                       | String | Price of the SKU per unit.                                                                                                                                                                                          |
| sku\_lines/item\_desc                            | String | SKU description.                                                                                                                                                                                                    |
| sku\_lines/maximum\_retail\_price                | String | Maximum retail price of the SKU.                                                                                                                                                                                    |
| sku\_lines/discount                              | String | Discount amount if any applied on the SKU.                                                                                                                                                                          |
| sku\_lines/discount\_percentage                  | String | What percentage of discount applied on the SKUs maximum retail price if any.                                                                                                                                        |
| invoice\_number                                  | String | Invoice number for the purchase order                                                                                                                                                                               |
| invoice\_date                                    | String | Invoice date for the purchase order                                                                                                                                                                                 |

{% tabs %}
{% tab title="200 Successful Result" %}

```json
{
    "status": "PASS",
    "message": {
        "id": 930,
        "po_number": "18052210123469767"
    }
}
```

{% endtab %}

{% tab title="401 Unauthorised / Wrong api key" %}

```json
{
  "status": "FAIL",
  "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="500 Unexpected error" %}

```json
{
  "status": "FAIL",
  "message": "Unexpected error"
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid Payload" %}

```json
{
    "status": "FAIL",
    "message": "Error when creating the PurchaseOrder. Reason: PurchaseOrder with po_number: 18052210123469766 already exists."
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Sample Value | Schema" %}

```json
{
    "po_number": "18052210123469767",
    "invoice_number", "1234567",
    "invoice_date": "2022-05-24"
    "description": "Purchase Order description",
    "delivery_date": "2022-05-24",
    "expiry_date": "2022-05-30",
    "status": "New",
    "total_price": 125.50,
    "batch": "yes",
    "serial_number": 54943,
    "supplier": 7,
    "supplier_name": "Default Supplier",
    "site": 7,
    "site_name": "Banashankari WH",
    "sku_lines": [
        {
            "sku_name": "Sample 123456",
            "status": "New",
            "qty": 77,
            "qty_received": 6,
            "price_per_qty": 22,
            "item_desc": "Nice quality",
            "maximum_retail_price": 25.0,
            "discount": 3.0,
            "discount_percentage": 12.0
        },
        {
            "sku_name": "Sample 123455",
            "status": "New",
            "qty": 55,
            "qty_received": 10,
            "price_per_qty": 11,
            "item_desc": "Good quality"
            "maximum_retail_price": null,
            "discount": null,
            "discount_percentage": null
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Update a Purchase Order

<mark style="color:orange;">`PUT`</mark> `/wms/purchase-order`

Updates the details of an existing purchase order. Note: Purchase order number or purchase order id is mandatory in order to proceed with updating the purchase order. check the documents for more details.

#### Headers

| Name                                       | Type   | Description                              |
| ------------------------------------------ | ------ | ---------------------------------------- |
| API\_KEY<mark style="color:red;">\*</mark> | string | API key obtained by the Customer/Partner |

#### Request Body

| Name                                             | Type   | Description                                                                                                                                                                                                         |
| ------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| po\_number<mark style="color:red;">\*</mark>     | String | Purchase Order number                                                                                                                                                                                               |
| supplier                                         | String | <p>Supplier id for the purchase order.</p><p><strong>Note:</strong> This field is conditionally optional. Either <strong>supplier</strong> or <strong>supplier\_name</strong> should be provided.</p>               |
| supplier\_name                                   | String | <p>Supplier name for the purchase order.</p><p><strong>Note:</strong> This field is conditionally optional. Either <strong>supplier</strong> or <strong>supplier\_name</strong> should be provided.</p>             |
| description                                      | String | Full or partial description text of matching purchase order                                                                                                                                                         |
| site                                             | String | <p>Site id to which purchase order was created for. </p><p><strong>Note:</strong> This field is conditionally optional. Either <strong>site</strong> or <strong>site\_name</strong> should be provided.</p>         |
| site\_name                                       | String | <p>Unique Site name to which purchase order was created for.</p><p><strong>Note:</strong> This field is conditionally optional. Either <strong>site</strong> or <strong>site\_name</strong> should be provided.</p> |
| status                                           | String | <p>Status of the purchase order. </p><p>Ex<strong>: New, In-Progress, Completed, Expired</strong> </p>                                                                                                              |
| delivery\_date                                   | String | <p>Delivery date of the purchase order.</p><p><strong>Ex:</strong>2022-01-01</p>                                                                                                                                    |
| expiry\_date                                     | String | <p>Expiry date of the purchase order.</p><p><strong>Ex:</strong>2022-01-01</p>                                                                                                                                      |
| total\_price                                     | String | total price of all the items of the same SKU                                                                                                                                                                        |
| batch                                            | String | Batch number                                                                                                                                                                                                        |
| serial\_number                                   | String | Serial Number                                                                                                                                                                                                       |
| sku\_lines<mark style="color:red;">\*</mark>     | String | Array containing SKUs information against those purchase order is created                                                                                                                                           |
| sku\_lines/sku\_name                             | String | SKU name which should be uniquely identifiable in Blowhorn system.                                                                                                                                                  |
| sku\_lines/status                                | String | Status of the inventory. i.e **Unlocked** or **Locked**                                                                                                                                                             |
| sku\_lines/qty<mark style="color:red;">\*</mark> | String | Total quantity of the same SKU                                                                                                                                                                                      |
| sku\_lines/price\_per\_qty                       | String | Price of the SKU per unit.                                                                                                                                                                                          |
| sku\_lines/item\_desc                            | String | SKU description.                                                                                                                                                                                                    |
| sku\_lines/maximum\_retail\_price                | String | Maximum retail price of the SKU.                                                                                                                                                                                    |
| sku\_lines/discount                              | String | Discount amount if any applied on the SKU.                                                                                                                                                                          |
| sku\_lines/discount\_percentage                  | String | What percentage of discount applied on the SKUs maximum retail price if any.                                                                                                                                        |

{% tabs %}
{% tab title="200 Successful Result" %}

```json
{
    "status": "PASS",
    "message": {
        "id": 930,
        "po_number": "18052210123469767"
    }
}
```

{% endtab %}

{% tab title="401 Unauthorised / Wrong api key" %}

```json
{
  "status": "FAIL",
  "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="500 Unexpected error" %}

```json
{
  "status": "FAIL",
  "message": "Unexpected error"
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid Payload" %}

```json
{
    "status": "FAIL",
    "message": "Error when updating the PurchaseOrder. Reason: PurchaseOrder with po_number: 18052210123469766 does not exists."
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Sample Schema 01" %}

```json
{
    "po_number": "18052210123469767",
    "description": "Purchase Order description"
}
```

{% endtab %}

{% tab title="Sample Schema 02" %}

```json
{
    "po_number": "18052210123469767",
    "delivery_date": "2022-05-24",
    "expiry_date": "2022-05-30",
    "status": "Completed",
}
```

{% endtab %}

{% tab title="Sample Schema 03" %}

```json
{
    "po_number": "18052210123469767",
    "sku_lines": [
        {
            "sku_name": "Sample 123456",
            "status": "New",
            "qty": 77,
            "qty_received": 6,
            "price_per_qty": 22,
            "item_desc": "Nice quality",
            "maximum_retail_price": 25.0,
            "discount": 3.0,
            "discount_percentage": 12.0
        }
    ]
}
```

{% endtab %}
{% endtabs %}