# Purchase Order API

## Get Purchase Orders

Retrieve purchase orders for an organization.

**Endpoint:** `POST https://api.quick.myquickapp.com/quick_purchase_orders`

### Request Headers

```
Authorization: Bearer {api_key}
Content-Type: application/json
language: en
```

### Request Body - List Purchase Orders

```json
{
  "org_id": "12345",
  "userid": "123"
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {
    "Access-Control-Allow-Origin": "*",
    "Access-Control-Allow-Headers": "*",
    "Access-Control-Allow-Methods": "GET,POST,OPTIONS"
  },
  "body": {
    "purchase_orders": [
      {
        "id": 30001,
        "orgid": 12345,
        "purchase_order_number": "PO-2024-0001",
        "vendor": {
          "id": 917020,
          "partnername": "Vendor Name",
          "display_name": "Vendor Name"
        },
        "po_status": "draft",
        "po_date": "2024-03-10T10:00:00",
        "expected_date": "2024-03-15",
        "subtotal": 5000.00,
        "tax_amount": 750.00,
        "po_total": 5750.00,
        "warehouse_id": "wh_1",
        "comments": "Purchase order for office supplies",
        "created_at": "2024-03-10T10:30:00"
      }
    ],
    "pagination": {
      "page_number": 1,
      "page_size": 25,
      "total_items": 1,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    }
  }
}
```

---

## Create Purchase Order

Create a new purchase order.

**Endpoint:** `POST https://api.quick.myquickapp.com/quick_purchase_orders`

### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "create",
  "vendor": "917020",
  "purchase_order_number": "PO-2024-0001",
  "po_status": "draft",
  "po_date": "2024-03-10T10:00:00",
  "expected_date": "2024-03-15",
  "warehouse_id": "wh_1",
  "comments": "Purchase order for office supplies",
  "payment_terms": "Net 30",
  "currency": "ZAR",
  "line_items": [
    {
      "product_id": 201,
      "product_name": "Product Name",
      "description": "Product description",
      "quantity": 100,
      "price": 50.00,
      "discount": 0,
      "tax_rate": 15.0,
      "tax_included": true,
      "subtotal": 5000.00,
      "tax_amount": 750.00,
      "total": 5750.00,
      "warehouse_id": "wh_1",
      "location_id": "loc_1"
    }
  ]
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "Purchase order created successfully",
    "purchase_order": {
      "id": 30001,
      "orgid": 12345,
      "purchase_order_number": "PO-2024-0001",
      "vendor": "917020",
      "po_status": "draft",
      "po_date": "2024-03-10T10:00:00",
      "expected_date": "2024-03-15",
      "subtotal": 5000.00,
      "tax_amount": 750.00,
      "po_total": 5750.00,
      "warehouse_id": "wh_1",
      "created_at": "2024-03-10T10:30:00"
    }
  }
}
```

---

## Edit Purchase Order

Update an existing purchase order.

### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "edit",
  "purchase_order_id": 30001,
  "po_status": "sent",
  "expected_date": "2024-03-20",
  "comments": "Updated purchase order"
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "Purchase order updated successfully",
    "purchase_order": {
      "id": 30001,
      "po_status": "sent",
      "expected_date": "2024-03-20",
      "comments": "Updated purchase order"
    }
  }
}
```

---

## Send Purchase Order to Vendor

Send a purchase order to the vendor (email).

### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "send_email",
  "purchase_order_id": 30001,
  "email": "vendor@example.com",
  "subject": "Purchase Order PO-2024-0001",
  "message": "Please find attached purchase order."
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "Purchase order email sent successfully",
    "email_id": "email_123"
  }
}
```

---

## Receive Purchase Order Items

Receive items against a purchase order (create stock move).

### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "receive",
  "purchase_order_id": 30001,
  "receipt_items": [
    {
      "product_id": 201,
      "quantity_received": 100,
      "price": 50.00,
      "warehouse_id": "wh_1",
      "location_id": "loc_1"
    }
  ],
  "receipt_date": "2024-03-15T10:00:00"
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "Purchase order received successfully",
    "stock_move_id": "move_12345",
    "received_items": [
      {
        "product_id": 201,
        "product_name": "Product Name",
        "quantity_ordered": 100,
        "quantity_received": 100,
        "quantity_remaining": 0
      }
    ],
    "stock_updated": true
  }
}
```

---

## Cancel Purchase Order

Cancel a purchase order.

### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "cancel",
  "purchase_order_id": 30001
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "Purchase order cancelled successfully"
  }
}
```

---

## Create Bill from Purchase Order

Create a bill (purchase invoice) from a purchase order.

### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "create_bill",
  "purchase_order_id": 30001,
  "invoicetype": "invoicein",
  "bill_date": "2024-03-15T10:00:00",
  "bill_status": "draft"
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "Bill created from purchase order successfully",
    "invoice": {
      "id": 50001,
      "orgid": 12345,
      "invoicenumber": "BILL-2024-0001",
      "invoicetype": "invoicein",
      "partner": "917020",
      "invoicestatus": "draft",
      "subtotal": 5000.00,
      "tax_amount": 750.00,
      "invoicetotal": 5750.00
    }
  }
}
```

---

## Purchase Order Status

| Status | Description |
|--------|-------------|
| `draft` | Purchase order is being created |
| `sent` | Purchase order has been sent to vendor |
| `received` | Items have been received |
| `billed` | Bill has been created |
| `paid` | Bill has been paid |
| `cancelled` | Purchase order has been cancelled |

---

## Purchase Order Types

| Type | Description |
|------|-------------|
| `standard` | Standard purchase order |
| `drop_ship` | Drop ship order |
| `direct` | Direct delivery order |

---

## Purchase Order Fields

### Header Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `vendor` | string | Yes | Vendor ID |
| `purchase_order_number` | string | No | PO number (auto-generated if empty) |
| `po_status` | string | Yes | `draft`, `sent`, `received`, etc. |
| `po_date` | datetime | Yes | Date of PO |
| `expected_date` | date | Yes | Expected delivery date |
| `warehouse_id` | string | Yes | Warehouse for delivery |
| `comments` | string | No | Notes |
| `payment_terms` | string | No | Payment terms |
| `currency` | string | No | Currency code |

### Line Item Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | Product ID |
| `quantity` | decimal | Yes | Quantity ordered |
| `price` | decimal | Yes | Unit price |
| `discount` | decimal | No | Discount percentage |
| `tax_rate` | decimal | Yes | Tax rate |
| `warehouse_id` | string | Yes | Warehouse for delivery |
| `location_id` | string | Yes | Location for delivery |

---

## Search Purchase Orders

### Search by Number

```json
{
  "org_id": "12345",
  "search_key": "PO-2024"
}
```

### Search by Vendor

```json
{
  "org_id": "12345",
  "search_key": "Vendor Name"
}
```

---

## Purchase Order Totals

### Get Purchase Order Total

```json
{
  "org_id": "12345",
  "purchase_order_id": 30001,
  "calculate_total": true
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "purchase_order_id": 30001,
    "subtotal": 5000.00,
    "tax_amount": 750.00,
    "discount_total": 0,
    "po_total": 5750.00,
    "currency": "ZAR"
  }
}
```

---

## Purchase Order Receiving

### Partial Receipt

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "receive",
  "purchase_order_id": 30001,
  "receipt_items": [
    {
      "product_id": 201,
      "quantity_received": 50,
      "price": 50.00,
      "warehouse_id": "wh_1",
      "location_id": "loc_1"
    }
  ],
  "receipt_date": "2024-03-15T10:00:00"
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "Partial receipt recorded successfully",
    "received_items": [
      {
        "product_id": 201,
        "quantity_ordered": 100,
        "quantity_received": 50,
        "quantity_remaining": 50
      }
    ]
  }
}
```