# Receive Items Against a Purchase Order

Records how much of the ordered quantity has arrived on the lines you name, and unless receive_config.update_strategy says otherwise adds that quantity to the matching Sortly items.
Key considerations:
- The work happens in the background. A successful call returns 202 straight away
  with the receive pending. Poll
  GET /api/v1/purchase_orders/{purchase_order_id}/receive/status until it reads
  completed or failed.
- One receive at a time per order. Nothing needs carrying between the two calls;
  starting a second while the first is pending returns 409.
- Lines can fail individually while the call succeeds. Read the ids out of
  received_line_item_ids and errors rather than trusting the HTTP status.
- The order must be ordered or partially_received. Receiving is what moves it on
  to partially_received and then received, which is why neither can be set through
  the status endpoint.
- A line must still be linked to a Sortly item, and no two lines in one request may
  point at the same item.

Endpoint: POST /api/v1/purchase_orders/{purchase_order_id}/receive
Security: BearerAuth

## Path parameters:

  - `purchase_order_id` (number, required)
    ID of the purchase order
    Example: "506"

## Header parameters:

  - `Accept` (string)
    e.g. application/json
    Example: "application/json"

  - `Authorization` (string)
    e.g. Bearer
    Example: "Bearer <Enter Secret Key Here>"

## Request fields (application/json):

  - `line_items` (array, required)
    The lines being received, and how much of each has arrived. 1 to 100 lines.

  - `line_items.line_item_id` (number, required)
    id of the line being received, taken from the purchase order's line_items.

  - `line_items.received_quantity` (string, required)
    How much of this line has arrived now, on top of anything received against it before. Must be greater than zero and no more than the line's quantity less its received_quantity.

  - `line_items.folder_id` (number,null)
    Folder to receive the items into. Defaults to wherever the item already sits.

  - `line_items.received_price` (string,null)
    Price to record on the received item. Only used when update_strategy is with_item_update_no_clone, and ignored under the other two. Defaults to the line's unit_rate.

  - `action` (object)

  - `action.reason_id` (string)
    uid of the transaction reason to attribute this receive to. Optional: leave action out entirely and the receive still runs. No endpoint lists the reasons, so the uid has to come from the Sortly app, which is why it is not required.

  - `action.notes` (string,null)
    Note to keep against this receive. Max 4000 characters, and must not be blank if given.

  - `receive_config` (object)

  - `receive_config.update_strategy` (string)
    with_item_update (the default) adds the received quantity to the item; if folder_id names a folder other than the one the item is in, or another item there would merge with it, a copy is made in that folder carrying the line's unit_rate. with_item_update_no_clone adds the quantity to the existing item where it already is and sets its price to received_price, copying it only if it is not in the target folder at all. without_item_update records the receipt on the purchase order and leaves inventory alone.

## Response 202 fields (application/json):

  - `data` (object)

  - `data.status` (string)
    pending while lines are still being applied, completed once all of them went through, failed if any did not.

  - `data.received_line_item_ids` (array)
    Lines that were received

  - `data.pending_line_item_ids` (array)
    Lines the receive has not applied. While status is pending they are still to come. If status is failed they were never applied and never will be: the receive stopped before reaching them, and error says why. Stop polling on status, not on this list emptying.

  - `data.errors` (array)
    Lines that failed, each with its reason

  - `data.errors.line_item_id` (number)

  - `data.errors.name` (string,null)
    Name of the item on the line, to save looking it up

  - `data.errors.error` (string)
    What went wrong, in words. Meant for a person reading it, so do not match on the text; it can change.

  - `data.error` (string,null)
    Set when the receive as a whole failed rather than particular lines, in which case errors is empty.

  - `data.created_at` (string)
    When the receive was started

  - `data.updated_at` (string)
    When it last changed, which is the time it finished once it has

## 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