> For the complete documentation index, see [llms.txt](https://kb.logicerp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kb.logicerp.com/logic-erp-learning-hub-tutorials-and-best-practices/api-documentation/orders/push/save-a-purchase-order.md).

# Save a Purchase Order

Creates a new **purchase order** in Logic ERP – an order you place on a supplier for goods you want to buy. You send the supplier, the order prefix and the items with their quantities and rates; Logic ERP gives the order the next number for that prefix, works out discounts, taxes and totals with the purchase-order series chosen for your API site, and saves it as **pending** so that delivery notes and purchase vouchers can later be made against it.

To create a **purchase indent** (an internal request to buy) instead, use [Save a Purchase Indent](https://kb.logicerp.com/logic-erp-learning-hub-tutorials-and-best-practices/api-documentation/orders/push/save-a-purchase-indent.md) – it takes the same request. To read purchase orders back, use [Get Purchase Orders](https://kb.logicerp.com/logic-erp-learning-hub-tutorials-and-best-practices/api-documentation/orders/pull/get-purchase-orders.md).

### **Endpoint**

| Name          | Detail                                      |
| ------------- | ------------------------------------------- |
| Address       | `https://your-server/api/SavePurchaseOrder` |
| Method        | `POST`                                      |
| Authorization | Basic Auth                                  |

The response envelope, branches, dates, queueing and the common messages are explained in [How Every API Call Works](https://kb.logicerp.com/logic-erp-learning-hub-tutorials-and-best-practices/api-documentation/how-every-api-call-works.md).

### **Request fields**

Field names are not case-sensitive. Names and codes are matched as you send them – spaces in front of them are not removed (only `Tax_Region` and the item codes `LogicUser_Code` / `AddlItemCode` are trimmed). Capital and small letters do not matter.

| Field                                                               | Type   | Required                         | Default                   | Meaning                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------- | ------ | -------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Branch_Code`                                                       | number | **Yes** (or `Branch_Short_Name`) | `-1`                      | The branch the order is saved in (`Branch_Code` in [Get Branch Info](https://kb.logicerp.com/logic-erp-learning-hub-tutorials-and-best-practices/api-documentation/masters/pull/get-branch-info.md)). When it is left out (or `0` or less) and `Branch_Short_Name` is sent, the branch is found by its short name. With neither, the request is refused. |
| `Branch_Short_Name`                                                 | text   | No                               | empty                     | The branch by its short name. Used only when `Branch_Code` is left out, `0` or less. A short name that does not exist is refused.                                                                                                                                                                                                                        |
| `Party_User_code`                                                   | text   | Yes                              | empty                     | The supplier, by the party code shown in Logic ERP (`User_Code` in [Get Party Master](https://kb.logicerp.com/logic-erp-learning-hub-tutorials-and-best-practices/api-documentation/masters/pull/get-party-master.md)). A supplier or customer account is accepted.                                                                                      |
| `Order_Prefix`                                                      | text   | Yes                              | empty                     | The prefix of the order number, for example `PO`. The order gets the next free number for this prefix in the branch, and its number is the prefix, a hyphen and that number – for example `PO-128`.                                                                                                                                                      |
| `Order_Date`                                                        | date   | No                               | today                     | The order date, `yyyy-MM-dd`. It also decides the financial year.                                                                                                                                                                                                                                                                                        |
| `Valid_Till_Date`                                                   | date   | No                               | the order date            | The date the order is valid till. A value that cannot be read as a date is ignored.                                                                                                                                                                                                                                                                      |
| `Delivery_Date`                                                     | date   | No                               | none                      | The expected delivery date.                                                                                                                                                                                                                                                                                                                              |
| `Supplier_Order_No`                                                 | text   | No\*                             | empty                     | The supplier's own order reference. \*Required when the purchase-order series has **Do not allow duplicate Supp. Order No. for Same Supplier** ticked – see Rules.                                                                                                                                                                                       |
| `Quotation_No`                                                      | text   | No                               | empty                     | The supplier's quotation number.                                                                                                                                                                                                                                                                                                                         |
| `Quotation_Date`                                                    | date   | No                               | none                      | The supplier's quotation date. A value that cannot be read as a date is ignored.                                                                                                                                                                                                                                                                         |
| `Remarks`                                                           | text   | No                               | empty                     | Remarks of the order.                                                                                                                                                                                                                                                                                                                                    |
| `Tax_Region`                                                        | text   | No                               | the supplier's tax region | A tax region by name, exactly as in Logic ERP. Replaces the supplier's tax region for this order. `(NIL)` (or only spaces) means no tax region. A name that is not found is refused. See the known issue below.                                                                                                                                          |
| `Agent_Name`                                                        | text   | No                               | the supplier's agent      | An agent / broker by name, exactly as in Logic ERP. `(NIL)` means no agent. Left out, the order gets the supplier's default agent.                                                                                                                                                                                                                       |
| `Company_Name`                                                      | text   | No                               | none                      | A company (brand) by name, exactly as in Logic ERP's company master. `(NIL)` means none.                                                                                                                                                                                                                                                                 |
| `Transport_Name`                                                    | text   | No                               | none                      | A transporter by name, exactly as in Logic ERP. `(NIL)` means none.                                                                                                                                                                                                                                                                                      |
| `DepartmentName`                                                    | text   | No                               | none                      | A department by name, exactly as in Logic ERP.                                                                                                                                                                                                                                                                                                           |
| `Transfer_Party_UserCode`                                           | text   | No                               | none                      | A transfer party, by party code.                                                                                                                                                                                                                                                                                                                         |
| `Delivery_At`, `Delivery_Add_1`, `Delivery_Add_2`, `Delivery_Add_3` | text   | No                               | empty                     | The delivery place and three address lines.                                                                                                                                                                                                                                                                                                              |
| `Total_Other_Val_1` to `Total_Other_Val_5`                          | number | No                               | `0`                       | Amounts for "other value" 1 to 5 of the order, in ₹. Used only when the purchase-order series' calculation includes that other value; it is then added or deducted as the series says. `0` lets the series' default apply.                                                                                                                               |
| `ListItems`                                                         | list   | Yes                              | empty list                | The items ordered – see below.                                                                                                                                                                                                                                                                                                                           |
| `DisplayError`                                                      | text   | No                               | `"0"`                     | `"1"` = when the request fails, `Message` holds the full technical detail. Use only while testing.                                                                                                                                                                                                                                                       |

**`ListItems` – one entry per order line**

| Field                                           | Type   | Required                | Default | Meaning                                                                                                                                                                                            |
| ----------------------------------------------- | ------ | ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LogicUser_Code`                                | text   | One of the two          | empty   | The item code shown in Logic ERP (`UserCode` in [Get Item Master](https://kb.logicerp.com/logic-erp-learning-hub-tutorials-and-best-practices/api-documentation/masters/pull/get-item-master.md)). |
| `AddlItemCode`                                  | text   | One of the two          | empty   | The additional item code / barcode (`AddlItemCode` in Get Item Master). Used when `LogicUser_Code` is empty or not found. A code from the item's list of extra barcodes is accepted too.           |
| `Order_Qty`                                     | number | Yes                     | `0`     | Quantity ordered. Must be above `0`.                                                                                                                                                               |
| `Rate`                                          | number | No – but always send it | `0`     | Rate per unit, in ₹. See the known issue below.                                                                                                                                                    |
| `SPCD_P`                                        | number | No                      | `0`     | Discount percentage for the line. Used when the series' calculation has an item-wise discount.                                                                                                     |
| `Tax_Amount`                                    | number | No                      | `0`     | Despite its name, the **tax percentage** of the line, for example `12` for 12 %. See Rules and the known issue below.                                                                              |
| `Remarks`                                       | text   | No                      | empty   | Remarks of the line.                                                                                                                                                                               |
| `Lot_Number`                                    | text   | No                      | empty   | The lot number for the line. Replaced by the order number when the series has **Move PO Number to Lot Number** ticked.                                                                             |
| `Lot_QR_Code`, `Lot_Extra_1`, `Addl_Lot_Number` | text   | No                      | empty   | Saved on the lot only when the series is set to generate lots in advance (**Generate Lot As** is not *None*). Ignored otherwise.                                                                   |

**Ignored fields.** `Total_Other_Val_6`, `Total_Other_Val_7`, and in `ListItems`: `ItemDetCode`. Any other field you send is ignored. MRP comes from the item master; there is no free quantity, currency or exchange-rate field.

### **Rules Logic ERP applies**

* **Series.** The order is saved in the purchase-order series chosen as **Default Configuration** in your API site's settings for *LOGIC API PUSH - PURCHASE ORDER*. There is no request field for the series. Discounts, taxes, other values and rounding follow that series, as on Logic ERP's purchase-order screen.
* **Number.** The order gets the next number for `Order_Prefix` in the branch (highest existing number + 1), so numbers can differ from the series' own numbering. There is no request field for the number.
* **Supplier.** `Party_User_code` must be a supplier or customer account. Its tax region is used for the order (see Taxes). The supplier's default agent is used unless you send `Agent_Name` (`(NIL)` = no agent).
* **Items.** Each `ListItems` entry becomes one order line, in the order sent. The same item may appear on several lines. Every item code must exist; one unknown code stops the whole request. MRP is the item's MRP in the item master.
* **Ignore Invalid Item for Request Json.** When this API setting is ticked, entries whose `LogicUser_Code` is exactly `-1` are dropped before anything is checked. Other unknown codes are still refused.
* **Rates.** The `Rate` you send is used as it is. When it is `0` or left out, Logic ERP looks up a rate itself – see the known issue below.
* **Taxes.** The order's tax region is the one linked to the supplier for this branch, otherwise the supplier's own tax region, unless you send `Tax_Region`. When the series has **Retrieve Item Wise Purchase Tax Type Info** ticked and its tax is worked out item-wise, Logic ERP finds each item's GST rate for that region and your `Tax_Amount` is replaced. Otherwise `Tax_Amount` is used as the line's tax percentage.
* **Date checks.** The order date must be in a financial year that is open in Logic ERP. The rights of the Logic ERP user linked to your API site apply: back-dated orders (earlier than the branch's latest purchase order), post-dated orders and locked periods can be refused.
* **Supplier order number.** When the series has **Do not allow duplicate Supp. Order No. for Same Supplier** ticked, `Supplier_Order_No` must be sent and must not already exist on a purchase order of this supplier in the branch.
* **Lots.** When the series is set to generate lots in advance, a lot is created for each line, numbered with the order number (or with your `Lot_Number` when **Move PO Number to Lot Number** is not ticked).
* **Approval.** If your Logic ERP set-up requires new purchase orders to be approved, the order is saved as waiting for approval and the approvers are notified.
* **Duplicates.** There is no duplicate check on the request (apart from the supplier order number above). Sending the same request twice creates two orders – check `Status` before you resend.
* **All or nothing.** The order and all its lines are saved together. If anything fails, nothing is saved.
* **Switched off.** When this endpoint is switched off in your API site's settings, nothing is saved and the response has `Status: true` with the *In-Active* sentence in `Message`, as described in How Every API Call Works. The switch is read for the whole API site, not per branch.
* Your Logic ERP licence must include the purchase-order API.
* **Branch.** Send `Branch_Code` or `Branch_Short_Name`. With neither, nothing is saved and the request is refused with *Branch\_Code or Branch\_Short\_Name is required.*

> **Known issue – a missing `Rate` is not the purchase rate.** When `Rate` is `0` or left out, the line gets the supplier's rate for the item (the transfer party's, when you send `Transfer_Party_UserCode`) if the series has **Pick Supplier + Item Wise Rates** ticked and such a rate exists; otherwise it gets the item's **sale** rate (from the item master or from the item's latest lot, depending on the series). Always send the purchase rate.

> **Known issue – `Tax_Amount` is a percentage.** The value is used as the line's tax rate, not as a tax amount: `Tax_Amount: 180` on a ₹1,500 line adds ₹2,700 of tax. Send the tax percentage, or `0` when the series finds the taxes itself.

> **Known issue – the default tax region.** Without `Tax_Region`, the order takes the tax region linked to the supplier for **sales** in this branch, not the one linked for purchases. When the supplier has a different purchase tax region in this branch, send it in `Tax_Region`.

### **Example request**

```json
{
  "Branch_Code": 2,
  "Party_User_code": "S0412",
  "Order_Prefix": "PO",
  "Order_Date": "2026-10-30",
  "Valid_Till_Date": "2026-11-30",
  "Delivery_Date": "2026-11-10",
  "Supplier_Order_No": "SO/26-27/0881",
  "Remarks": "Winter stock – deliver to main godown",
  "Tax_Region": "CGST-SGST",
  "Transport_Name": "Shree Ganesh Roadways",
  "ListItems": [
    { "LogicUser_Code": "SHT1042", "Order_Qty": 24, "Rate": 450, "SPCD_P": 0, "Tax_Amount": 5, "Remarks": "" },
    { "LogicUser_Code": "TRS2210", "Order_Qty": 12, "Rate": 1150, "SPCD_P": 2, "Tax_Amount": 12, "Remarks": "Assorted sizes" }
  ]
}
```

### **Test it**

Send a request to the Logic ERP **sandbox** (a test company) from this page: open the block below, enter the sandbox user name and password (ask your Logic ERP support team), change the request if you like, and press **Test it**. This really saves in the sandbox, so use test values like the example. Each send creates one more test purchase order of the sandbox's test item `APITEST0001`; change `Supplier_Order_No` each time.

## Save a Purchase Order

> Creates a new purchase order in Logic ERP – an order you place on a supplier for goods you want to buy. You send the supplier, the order prefix and the items with their quantities and rates; Logic ERP gives the order the next number for that prefix, works out discounts, taxes and totals with the purchase-order series chosen for your API site, and saves it as pending so that delivery notes and purchase vouchers can later be made against it.

```json
{"openapi":"3.0.3","info":{"title":"Logic ERP API","version":"1.0"},"tags":[{"name":"Orders - Push"}],"servers":[{"url":"https://demo.logicerp.com/api","description":"Logic ERP sandbox (test company)"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic","description":"The user name and password of your API site."}}},"paths":{"/SavePurchaseOrder":{"post":{"tags":["Orders - Push"],"operationId":"SavePurchaseOrder","summary":"Save a Purchase Order","description":"Creates a new purchase order in Logic ERP – an order you place on a supplier for goods you want to buy. You send the supplier, the order prefix and the items with their quantities and rates; Logic ERP gives the order the next number for that prefix, works out discounts, taxes and totals with the purchase-order series chosen for your API site, and saves it as pending so that delivery notes and purchase vouchers can later be made against it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"Branch_Code":{"type":"integer","description":"The branch the order is saved in (`Branch_Code` in Get Branch Info). When it is left out (or `0` or less) and `Branch_Short_Name` is sent, the branch is found by its short name. With neither, the request is refused."},"Party_User_code":{"type":"string","description":"The supplier, by the party code shown in Logic ERP (`User_Code` in Get Party Master). A supplier or customer account is accepted."},"Order_Prefix":{"type":"string","description":"The prefix of the order number, for example `PO`. The order gets the next free number for this prefix in the branch, and its number is the prefix, a hyphen and that number – for example `PO-128`."},"Order_Date":{"type":"string","description":"The order date, `yyyy-MM-dd`. It also decides the financial year."},"Supplier_Order_No":{"type":"string","description":"The supplier's own order reference. *Required when the purchase-order series has Do not allow duplicate Supp. Order No. for Same Supplier ticked – see Rules."},"Remarks":{"type":"string","description":"Remarks of the order."},"ListItems":{"type":"array","items":{"type":"object","properties":{"LogicUser_Code":{"type":"string","description":"The item code shown in Logic ERP (`UserCode` in Get Item Master)."},"Order_Qty":{"type":"integer","description":"Quantity ordered. Must be above `0`."},"Rate":{"type":"integer","description":"Rate per unit, in ₹. See the known issue below."},"SPCD_P":{"type":"integer","description":"Discount percentage for the line. Used when the series' calculation has an item-wise discount."},"Tax_Amount":{"type":"integer","description":"Despite its name, the tax percentage of the line, for example `12` for 12 %. See Rules and the known issue below."},"Remarks":{"type":"string","description":"Remarks of the order."}}},"description":"The items ordered – see below."}}}}}},"responses":{"200":{"description":"Always HTTP 200. Check Status and Message.","content":{"application/json":{"schema":{"type":"object","properties":{"LastSavedDocNo":{"type":"string","description":"The order number – prefix, a hyphen and the number, for example `PO-128`. Empty (`null`) when not saved."},"Order_No":{"type":"string","nullable":true,"description":"Always `null`."},"ErrorCode":{"type":"string","description":"Always empty."},"Status":{"type":"boolean","description":"`true` when the order was saved."},"Message":{"type":"string","description":"Empty when saved; the reason when not saved."},"LastSavedCode":{"type":"integer","description":"Logic ERP's internal number of the new order; `0` when not saved."},"request_ID":{"type":"string","description":"The ID of this request – quote it to support."}}}}}},"401":{"description":"No login was sent."}}}}}}
```

### **Response**

| Field            | Type         | Meaning                                                                                                  |
| ---------------- | ------------ | -------------------------------------------------------------------------------------------------------- |
| `Status`         | true / false | `true` when the order was saved.                                                                         |
| `Message`        | text         | Empty when saved; the reason when not saved.                                                             |
| `LastSavedCode`  | number       | Logic ERP's internal number of the new order; `0` when not saved.                                        |
| `LastSavedDocNo` | text         | The order number – prefix, a hyphen and the number, for example `PO-128`. Empty (`null`) when not saved. |
| `Order_No`       | text         | Always `null`.                                                                                           |
| `ErrorCode`      | text         | Always empty.                                                                                            |
| `request_ID`     | text         | The ID of this request – quote it to support.                                                            |

### **Example response**

```json
{
  "LastSavedDocNo": "PO-128",
  "Order_No": null,
  "ErrorCode": "",
  "Status": true,
  "Message": "",
  "LastSavedCode": 4521,
  "request_ID": "8c41d2a7-5e93-4b0f-a1c6-2f7e9d3b6a15"
}
```

### **Messages you may see**

The checks run roughly in the order of this table, so the first problem found is the one reported. With `DisplayError` `"1"`, every message comes with technical detail around it – look for the reason in the first line.

| Message                                                                                                     | Meaning                                                                                                                         | What to do                                                              |
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| A message saying the text could not be converted to a date                                                  | `Order_Date` is not a date.                                                                                                     | Send dates as `yyyy-MM-dd`.                                             |
| `Default Purchase Order Configuration Not Selected!!`                                                       | No purchase-order series is chosen in your API site's settings.                                                                 | Ask your Logic ERP team to choose the Default Configuration.            |
| `Branch_Code or Branch_Short_Name is required.`                                                             | Neither branch field was sent. Nothing was saved.                                                                               | Send `Branch_Code` or `Branch_Short_Name`.                              |
| `Branch_Short_Name : … not exists.`                                                                         | No branch has that short name.                                                                                                  | Send the short name from Get Branch Info.                               |
| `No financial year covers the date …` (date as day/month/year)                                              | `Order_Date` lies outside every financial year set up in Logic ERP. Nothing was saved.                                          | Send a date inside a financial year.                                    |
| `Invalid Party User Code...`                                                                                | `Party_User_code` is missing or is not a supplier or customer account.                                                          | Send the supplier's party code.                                         |
| `Invalid Agent Name...` / `Invalid Company Name...` / `Invalid Transport Name...`                           | A name was not found.                                                                                                           | Send it exactly as in Logic ERP, or leave it out.                       |
| `LogicUserCode Or EAN Code Cannot Blank!!`                                                                  | An entry in `ListItems` has neither code (or both hold only spaces).                                                            | Send `LogicUser_Code` or `AddlItemCode`.                                |
| `Invalid LogicUserCode / EANCode : …`                                                                       | An item code was not found (the code is shown in capitals).                                                                     | Send the code exactly as in Logic ERP.                                  |
| `Quantity cannot be blank. Logic User Code : …`                                                             | `Order_Qty` is `0` or less.                                                                                                     | Send a quantity above `0`.                                              |
| `Entry not allowed in back date.......`                                                                     | The order date is earlier than the latest purchase order of the branch (or than today), and back-dated entries are not allowed. | Send a later `Order_Date`, or ask your Logic ERP team about the rights. |
| `Post Dated enteries are not allowed.......`                                                                | The order date is after today.                                                                                                  | Send today's date or earlier.                                           |
| `Entry/Modification is locked for this period....` / `Modification rights not available for this date.....` | The period of the order date is locked.                                                                                         | Send a date in an open period.                                          |
| `Invalid Order Prefix Entered...`                                                                           | `Order_Prefix` is empty.                                                                                                        | Send a prefix.                                                          |
| `No Item Found!!`                                                                                           | `ListItems` is empty (or every entry was dropped as `-1`).                                                                      | Send at least one item.                                                 |
| `Unable to found Department Name : …` / `Unable to found Transfer Party Name : …`                           | A department or transfer party was not found.                                                                                   | Send it exactly as in Logic ERP, or leave it out.                       |
| `Unable to found Tax Region : …`                                                                            | `Tax_Region` was not found. Nothing was saved.                                                                                  | Send it exactly as in Logic ERP, `(NIL)` for none, or leave it out.     |
| `Date not Within Financial Year` / `Order Date is not Within the Financial Year`                            | No financial year is open for the order date.                                                                                   | Send a date in an open financial year.                                  |
| `Supplier Order No. Cannot be blank.Please Check`                                                           | The series needs a supplier order number.                                                                                       | Send `Supplier_Order_No`.                                               |
| `Supplier Order No. already exists for same Supplier.Please Check`                                          | The supplier order number is already used for this supplier in the branch.                                                      | Send the correct number; do not resend an order that was saved.         |
| `The operation was canceled.`                                                                               | Saving was stopped inside Logic ERP; nothing was saved.                                                                         | Retry once; if it repeats, send the `request_ID` to support.            |
| Another technical error                                                                                     | Saving failed inside Logic ERP; nothing was saved.                                                                              | Retry once; if it repeats, send the `request_ID` to support.            |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://kb.logicerp.com/logic-erp-learning-hub-tutorials-and-best-practices/api-documentation/orders/push/save-a-purchase-order.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
