Create or Update a Purchase Order

AppZen

Updated On: July 13, 2023 11:46

To create a new purchase order or update an existing one in the AppZen System. This returns the uuid, the unique identifier, for this purchase order.

If there already exists a purchase order, with the given purchase_order_number body parameter, then the existing purchase order will be updated. The status in the response shows as UPDATED.
For a newly created purchase order, the status shows as CREATED.

Request URI

POST https://api.appzen.com/dictionary-data-services/
     purchase-order

Header Parameters

Name	Type	Description	Required
x-api-key	String	The x-api-key provided to authorize the request.	Yes
customer-id	String	The Customer ID provided to authorize the request.	Yes
customer-key	String	The Customer Key provided to authorize the request.	Yes

Body Parameters

Name	Type	Description	Required
purchase_order_number	String	The Purchase Order(PO) Number from your system example:193-994K	Yes
entity_id	String	The unique organization identifier in your system.	Yes
supplier_id	String	The unique supplier identifier in your system .	Yes
gl_code	String	The code value of the segments. example:1002.369.922.0000.0000	No
payment_term_id	String	The payment_term_id in your System.	No
comments	String	Comments you wish to add.	No
exchange_rate	Number	This is the root field that holds the information on the exchange rate.	No
conversion_rate	Number	The conversion rate from the transactional currency to the functional currency.	No
from_currency_code	String	The currency code of the transactional currency.	No
to_currency_code	String	The currency code of the functional currency.	No
start_date	String	The date when the purchase order has been issued to a vendor. Example:2020-11-01	No
end_date	String	The date for which delivery of any Product is stated in a Purchase Order and confirmed by Supplier. Example:2020-11-01	No
total_amount	Number	The root field that holds the information on the total amount of the purchase order.	No
amount	Number	The total amount of the Purchase Order.	No
currency	String	The currency of the total amount. Example USD.	No
amount_limit	NA	This is the root field to hold the information on the amount limit.	No
amount	Number	The maximum allowed amount of the Purchase Order.	No
currency	String	The currency of the maximum allowed amount of the Purchase Order. Example: USD.	No
min_release_amount	NA	This is the root field to hold the information about the minimum allowable amount of the Purchase Order.	No
amount	Number	The minimum allowed amount of the Purchase Order.	No
currency	String	The currency of the minimum allowed amount of the Purchase Order. Example: USD.	No
email_address	String	The email address on the Purchase Order.	No
purchase_requisition_id	String	The purchase requisition id related to this Purchase Order.	No
purchase_order_type	String	Type of purchase order like Blanket/Standard/Contract	No
purchase_order_status	String	This status value should contain the purchase order (header level) status as shown in your system.	Yes
appzen_purchase_order_status	String	It is a mapping from the customer’s purchase_order_status to AppZen’s defined purchase order status values as PO_ISSUED, PO_CLOSED.	Yes
ship_to_location	String	The location to which the Purchase Order is shipped	No
ship_to_location_id	String	The location id to which the Purchase Order is shipped.	No
requester	String	The person requesting the Purchase Order.	No
custom_json	NA	For storing any custom key value pairs needed by your system.	No
purchase_order_lines	NA	This is the root field to contain the info about the Purchase Order lines	Yes
po_line_id	String	The unique identifier of the po line from your system.	No
line_number	Number	The reference of the line in the Purchase Order.	No
gl_code	String	The code value of the segments.	Yes
line_item_code	String	It refers to the external item id in Purchase Order.	No
line_description	String	The description of the item in Purchase Order.	No
quantity	Number	The quantity of goods and services provided by the supplier. It should be assigned value of 1 if value is missing.	Yes
unit_price	NA	This is the root field to hold the info about the unit price of goods or services.	Yes
amount	Number	The price you charge per unit of goods or services.	No
unit_price: currency	String	The currency of the unit price amount. Example USD.	No
amount	Number	This is the root field to hold the information about the amount of the Purchase order.	Yes
amount	Number	The line amount of the purchase order.	No
currency	String	The currency of the line amount.	No
line_vat_amount	Number	The root field holds the information about the VAT.	No
amount	Number	The total line VAT amount of the Purchase Order Line.	No
currency	String	The currency of the VAT amount.	No
line_vat_breakdown	Number	The breakdown of VAT amount for the Purchase Order line.	No
code	String	Tax code.	No
rate	Number Minimum:0 exclusiveMinimum: True	Tax rate in percentage	No
vat_amount	Number	The Vat Amout	No
amount	Number Default:0	VAT amount for the Purchase order line	No
currency	String	Currency of the VAT amount	No
contractor_name	String	The Purchase Order contractor name	No
contractor_start_date	String	The start date of the Contractor on the Purchase order. The date should be in UTC format. Format:yyyy-mm-ddTHH:mm:ssZ	No
closed_flag	Boolean	This shows whether the Purchase Order is closed or not. Example: true	No
closed_by	String	The person who closed the Purchase Order	No
closed_date	String	The date on which Purchase Order was closed. The date should be in UTC format. Format:yyyy-mm-ddTHH:mm:ssZ	No
closed_reason	String	The reason for closing the Purchase Order.	No
cancel_flag	Boolean	This shows if the Purchase Order is canceled. Example: true, false, or ""	No
cancel_date	String	Date on which the Purchase Order was cancelled. format:yyyy-mm-ddTHH:mm:ssZ	No
cancel_reason	String	The reason for cancellation.	No
taxable_flag	Boolean	This shows if the Purchase Order is taxable.	No
tax_code_id	String	The tax code Id of the purchase order.	No
tax_name	String	The tax name on the purchase order.	No
type_1099	String	It will have value Type of 1099 tax code with distribution line.	No
committed_amount	NA	This is root field to contain the information about the Committed amount of Purchase order.	No
amount	Number	The committed amount per the Purchase Order	No
currency	String	The currency of the committed amount in the Purchase Order. Example: USD.	No
amount_limit	NA	This is the root field to hold the information about the amount limit on the Purchase order.	No
amount	Number	The limit on the amount per the Purchase Order line.	No
currency	String	The currency of the amount limit of the line. Example: USD.	No
unit_list_price	NA	This is the root field to hold the information about the unit list price of goods or services.	No
amount	Number	The unit list price you charge per unit of goods or services.	No
currency	String	The currency of the unit list price. Example USD.	No
base_list_price	NA	This is root field to hold the information about the. base list price of goods or services	No
amount	Number	The base list price per the Purchase Order line item.	No
currency	String	The currency of the base list price Example: USD.	No
uninvoiced_amount	Number	Balance left in the Purchase order line	Yes
amount	Number	The amount left in the Purchase Order line	No
currency	String	The currency of the un-invoiced amount in a Purchase Order. Example: USD.	No
received_amount	Number	This is the root field to hold the information about the received amount of the Purchase order.	No
amount	Number	The received Amount in the Purchase order line.	No
currency	String	The currency of the received amount. Example: USD	No
progress_payment_rate	Number	The progress payment rate in a purchase order.	No
item_category	String	The category of the item.	No
item_category_id	String	The category id of the item.	No
hazard_class_id	String	The unique id assigned - is applicable for goods or material like radioactive, or chemical which is hazardous in nature.	No
unit_of_measure	String	The unit of measure for the line item. Example: each, pallet, package.etc	No
committed_quantity	Number	The mandatory quantity that is to be provided in a purchase order.	No
ordered_quantity	Number	The ordered quantity to be provided.	No
received_quantity	Number	The ordered quantity actually received.	No
service_line_start_date	String	The start date of the service in the Purchase Order. Date should be in UTC format. Format:yyyy-mm-ddTHH:mm:ssZ	No
service_line_end_date	String	The end date of the service in the Purchase Order. Date should be in UTC format. Format:yyyy-mm-ddTHH:mm:ssZ	No
match_basis	String	The basis of matching the purchase order. Example: AMOUNT, QUANTITY	No
match_type	String	The match type in the purchase order. Example: PO_POLICY_TWO_WAY_MATCH, PO_POLICY_THREE_WAY_MATCH	No
line_type	String	The type of line. Example: GOODS, SERVICE	No
purchase_order_line_status	String	This status value contains the purchase order line status as shown in your system	Yes
appzen_purchase_order_line_status	String	Mapping from customer’s purchase order line status to AppZen’s defined purchase order line status values as PO_ISSUED, PO_CLOSED.	Yes
purchase_requisition_id	String	The purchase requisition id related to this Purchase order.	No
buyer	String	Information of the buyer.	No
custom_json	NA	For storing any custom key-value pairs needed by your system.	No
purchase_order_date	String	The Purchase Order Date. The date should be in UTC format.	No

Sample Request

curl -X POST "https://api.appzen.com/dictionary-data-services/purchase-order" 
-H "accept: application/json" 
-H "x-api-key: R7wsFxxxx" 
-H "customer-id: 1004xxxx" 
-H "customer-key: 15d1xxxx"
-H "Content-Type: application/json" 
-d "{
  "purchase_order_number": "193-994K",
  "entity_id": "1002",
  "supplier_id": "3009293",
  "gl_code": "1002.369.922.0000.0000",
  "payment_term_id": "8900012",
  "external_unique_id": "XP-1234-01",
  "comments": "string",
  "exchange_rate": {
    "conversion_rate": 0,
    "from_currency_code": "",
    "to_currency_code": ""
  },
  "start_date": "2020-11-01",
  "end_date": "2020-11-01",
  "total_amount": {
    "amount": 1.5,
    "currency": "USD"
  },
  "amount_limit": {
    "amount": 1.5,
    "currency": "USD"
  },
  "min_release_amount": {
    "amount": 1.5,
    "currency": "USD"
  },
  "email_address": "john.doe@acme.org",
  "purchase_requisition_id": null,
  "purchase_order_type": "string",
  "purchase_order_status": "Issued",
  "appzen_purchase_order_status": "PO_ISSUED",
  "ship_to_location": "string",
  "ship_to_location_id": "string",
  "requester": "string",
  "custom_json": {},
  "purchase_order_lines": [
    {
      "po_line_id": "string",
      "line_number": 0,
      "gl_code": "string",
      "line_item_code": "string",
      "line_description": "string",
      "quantity": 0,
      "unit_price": {
        "amount": 1.5,
        "currency": "USD"
      },
      "amount": {
        "amount": 1.5,
        "currency": "USD"
      },
      "line_vat_amount": {
        "amount": 1.5,
        "currency": "USD"
      },
      "line_vat_breakdown": [
        {
          "code": "GST",
          "rate": 20.5,
          "vat_amount": {
            "amount": 1.5,
            "currency": "USD"
          }
        }
      ],
      "contractor_name": "string",
      "contractor_start_date": "2020-11-01",
      "closed_flag": true,
      "closed_by": "string",
      "closed_date": "2020-11-01",
      "closed_reason": "string",
      "cancel_flag": true,
      "cancel_date": "2020-11-01",
      "cancel_reason": "string",
      "taxable_flag": true,
      "tax_code_id": "string",
      "tax_name": "string",
      "type_1099": "string",
      "committed_amount": {
        "amount": 1.5,
        "currency": "USD"
      },
      "amount_limit": {
        "amount": 1.5,
        "currency": "USD"
      },
      "unit_list_price": {
        "amount": 1.5,
        "currency": "USD"
      },
      "base_list_price": {
        "amount": 1.5,
        "currency": "USD"
      },
      "uninvoiced_amount": {
        "amount": 1.5,
        "currency": "USD"
      },
      "received_amount": {
        "amount": 1.5,
        "currency": "USD"
      },
      "progress_payment_rate": 0,
      "item_category": "string",
      "item_category_id": "string",
      "hazard_class_id": "string",
      "unit_of_measure": "string",
      "committed_quantity": 0,
      "ordered_quantity": 0,
      "received_quantity": 0,
      "service_line_start_date": "2020-11-01",
      "service_line_end_date": "2020-11-01",
      "match_basis": "NONE_MATCH_BASIS",
      "match_type": "PO_NONE_MATCH_TYPE",
      "line_type": "NONE_LINE_TYPE",
      "purchase_order_line_status": "string",
      "appzen_purchase_order_line_status": "PO_ISSUED",
      "purchase_requisition_id": "string",
      "buyer": "string",
      "custom_json": {}
    }
  ],
  "purchase_order_date": "2020-11-01"
}"

Sample Response

Success

{
  "uuid": "5fc03087-d265-11e7-b8c6-83e29cd24f4c",
  "status": "CREATED"
}

Failure

The request fails if you enter an invalid URL.

{
  "timestamp": "2019-01-17T16:12:45.977+0000",
  "status": 404,
  "error": "Not Found",
  "message": "Error code : 17e3338d - The resource you specified cannot be not found"
}

Response Code

Response Code	Description
200	The request is successful. (Updated)
201	The request is successful. (Created)
400	The request failed due to a malformed request syntax. Check the requested URL, including the parameters.
401	The request failed due to an authorization issue. For example, the Customer Key could be missing or invalid.
403	The request failed due to a permission issue. The x-api key may not have permission to perform the request.
404	The request failed as the resource is not found. Check the requested URL.
500	The request failed due to an AppZen server issue.

See Also