# Create a Purchase Order

Creates a purchase order. It starts in the draft status.
- You don't need to send amount, sub_total, total or line_number. Sortly works
  them out from the lines.
- Leave out purchase_order_number and Sortly generates one. - Every line needs an item_id from this company. An unknown item or unit of measure
  returns 404.
- Use the status endpoint to move the order on.

Endpoint: POST /api/v1/purchase_orders
Security: BearerAuth

## Request fields (application/json):

  - `purchase_order_number` (string)
    Must be unique within the company. Max 20 characters. Omit to have Sortly generate one.

  - `vendor` (object)
    The vendor the order is placed with, captured on the purchase order itself.

  - `vendor.name` (string)
    Max 50 characters.

  - `vendor.email` (string)
    Max 190 characters.

  - `vendor.line1` (string)

  - `vendor.line2` (string)

  - `vendor.city` (string)

  - `vendor.state` (string)

  - `vendor.zip_code` (string)

  - `vendor.country` (string)

  - `vendor.phone` (string)
    Max 22 characters.

  - `ship_to` (object)
    Shipping address, captured on the purchase order itself.

  - `ship_to.name` (string)

  - `bill_to` (object)
    Billing address, captured on the purchase order itself.

  - `notes` (string)
    Max 4000 characters.

  - `terms` (string)
    Max 4000 characters.

  - `currency_code` (string, required)
    3-letter ISO 4217 currency code, e.g. USD.

  - `charges` (object)
    Order-level charges as decimal strings. Each defaults to 0. total is sub_total + tax + shipping_cost - discount, so a discount larger than the rest of the order is rejected with 400.

  - `charges.discount` (string)

  - `charges.tax` (string)

  - `charges.shipping_cost` (string)

  - `expected_delivery_date` (string)
    When the order is expected to arrive, as an ISO 8601 timestamp.

  - `line_items` (array)
    Lines to put on the purchase order, up to 100.

  - `line_items.item_id` (number, required)
    ID of the Sortly item to order. Must exist in this company.

  - `line_items.name` (string, required)
    Name to record on the line. Max 191 characters.

  - `line_items.item_number` (string)
    Max 25 characters.

  - `line_items.quantity` (string, required)
    Decimal string, e.g. "10" or "2.5".

  - `line_items.unit_rate` (string)
    Price per unit as a decimal string. Omit for a line with no price.

  - `line_items.unit_of_measure` (object, required)

  - `line_items.unit_of_measure.name` (string, required)
    Abbreviation of one of the company's units of measure, e.g. units, ft, kg. An abbreviation the company does not have is rejected with 404.

  - `line_items.variant_options` (array)
    Up to 3 options.

  - `line_items.variant_options.value` (string, required)

  - `line_items.notes` (string)
    Max 314 characters.

## Response 201 fields (application/json):

  - `data` (object)

  - `data.id` (number)

  - `data.purchase_order_number` (string)

  - `data.status` (string)

  - `data.currency_code` (string)

  - `data.charges` (object)

  - `data.charges.discount` (string)

  - `data.charges.tax` (string)

  - `data.charges.shipping_cost` (string)

  - `data.sub_total` (string)
    Sum of every line's amount, computed by Sortly

  - `data.total` (string)
    sub_total plus tax plus shipping_cost minus discount, computed by Sortly

  - `data.line_items` (array)

  - `data.line_items.item_id` (number,null)
    ID of the Sortly item this line orders. Deleting that item in Sortly leaves this id untouched, so it can name an item GET /api/v1/items/{item_id} no longer returns. It is null only for a line whose item has been purged from Sortly altogether.

  - `data.line_items.name` (string)

  - `data.line_items.item_number` (string,null)

  - `data.line_items.quantity` (string)

  - `data.line_items.received_quantity` (string)
    How much of quantity has been received against this line

  - `data.line_items.unit_of_measure` (object)

  - `data.line_items.unit_of_measure.type` (string)

  - `data.line_items.unit_rate` (string,null)

  - `data.line_items.amount` (string)
    quantity multiplied by unit_rate, computed by Sortly

  - `data.line_items.line_number` (number)
    Assigned by Sortly from the order of the array

  - `data.line_items.variant_options` (array)

  - `data.line_items.variant_options.value` (string)

  - `data.line_items.notes` (string,null)

  - `data.vendor` (object,null)

  - `data.vendor.email` (string,null)

  - `data.vendor.line1` (string,null)

  - `data.vendor.line2` (string,null)

  - `data.vendor.city` (string,null)

  - `data.vendor.state` (string,null)

  - `data.vendor.zip_code` (string,null)

  - `data.vendor.country` (string,null)

  - `data.vendor.phone` (string,null)

  - `data.ship_to` (object,null)

  - `data.bill_to` (object,null)

  - `data.terms` (string,null)

  - `data.expected_delivery_date` (string,null)
    When the order is expected to arrive

  - `data.submitted_date` (string,null)

  - `data.submitted_by` (string,null)

  - `data.approved_date` (string,null)

  - `data.approved_by` (string,null)

  - `data.ordered_date` (string,null)
    Recorded by Sortly on the move to ordered

  - `data.ordered_by` (string,null)

  - `data.received_date` (string,null)

  - `data.received_by` (string,null)

  - `data.created_by` (string)

  - `data.created_at` (string)

  - `data.updated_by` (string)

  - `data.updated_at` (string)

  - `data.version` (number)
    Send this back when updating. A stale version is rejected with 409.

## Response 400 fields (application/json):

  - `message` (string)

  - `errors` (object,null)
    Field-level messages, present only on some validation failures

## Response 401 fields (application/json):

  - `message` (string)

  - `errors` (object,null)
    Field-level messages, present only on some validation failures

## Response 402 fields (application/json):

  - `message` (string)

  - `errors` (object,null)
    Field-level messages, present only on some validation failures

## Response 404 fields (application/json):

  - `message` (string)

  - `errors` (object,null)
    Field-level messages, present only on some validation failures

## Response 409 fields (application/json):

  - `message` (string)

  - `errors` (object,null)
    Field-level messages, present only on some validation failures