# Stock Movement Items

## Create

### Request
```
$ curl -b cookies.txt -X POST -H "Content-Type: application/json" \
-d @addStockMovementItem.json \
https://openboxes.ngrok.io/openboxes/api/stockMovements/ff808181644d5e5b01644e5007500001|jsonlint
```
### Post Body (addStockMovementItem.json)
```
{
	"id": "ff808181644d5e5b01644e5007500001",
	"name": "my new stock movement",
	"description": "",
	"identifier": "483ZSA",
	"origin.id": "2",
	"destination.id": "1",
	"dateRequested": "06/23/2018",
	"requestedBy.id": "1",
	"lineItems": [{
		"product.id": "ff8081816407132d0164071eec250001",
		"quantityRequested": "100",
		"sortOrder": 0,
		"recipient.id": "1"
	}]
}
```
### Response
```
{
  "data": {
    "id": "ff808181644d5e5b01644e5007500001",
    "name": "my new stock movement",
    "description": "",
    "identifier": "483ZSA",
    "origin": {
      "id": "2",
      "name": "Miami Warehouse"
    },
    "destination": {
      "id": "1",
      "name": "Boston Headquarters"
    },
    "dateRequested": "06/23/2018",
    "requestedBy": {
      "id": "1",
      "name": "Mr Administrator",
      "firstName": "Mr",
      "lastName": "Administrator",
      "email": "admin@pih.org",
      "username": "admin"
    },
    "lineItems": [
      {
        "id": "ff808181644e51a401644e85891b0006",
        "productCode": "BK71",
        "product": {
          "id": "ff8081816407132d0164071eec250001",
          "productCode": "BK71",
          "name": "product 1+",
          "description": "This is the penultimate product",
          "category": {
            "id": "ROOT",
            "name": "ROOT"
          }
        },
        "palletName": null,
        "boxName": null,
        "statusCode": "PENDING",
        "quantityRequested": 100,
        "quantityAllowed": null,
        "quantityAvailable": null,
        "quantityCanceled": null,
        "quantityRevised": null,
        "reasonCode": null,
        "comments": null,
        "recipient": null,
        "sortOrder": null
      }
    ]
  }
}
```


## Update 
This is used to change the quantity or product associated with an item, as well as 
other changes like sort order. This is a direct change to the requisition item. 

If you're looking to record a new quantity and want to keep the originally requested 
information, then you'll likely want to use the Revise Stock Movement Item example below
This will allow you to keep the originally requested quantity and product information, 
record the new quantity, as well as a reason for the revision 
(see next section for more information)

```
$ curl -b cookies.txt -X POST -H "Content-Type: application/json" \
-d @updateStockMovementItem.json \
https://openboxes.ngrok.io/openboxes/api/stockMovements/ff808181644d5e5b01644e5007500001|jsonlint
```

### Request Body (updateStockMovementItem.json)
```
{
	"id": "ff808181644d5e5b01644e5007500001",
	"name": "my new stock movement",
	"description": "",
	"identifier": "483ZSA",
	"origin.id": "2",
	"destination.id": "1",
	"dateRequested": "06/23/2018",
	"requestedBy.id": "1",
	"lineItems": [{
		"id": "ff808181644e51a401644e85891b0006",
		"product.id": "ff80818155df9de40155df9e31000001",
		"quantityRequested": "500",
		"sortOrder": 0
	}]
}
```
### Response 
```
{
  "data": {
    "id": "ff808181644d5e5b01644e5007500001",
    "name": "my new stock movement",
    "description": "my new stock movement",
    "identifier": "483ZSA",
    "origin": {
      "id": "2",
      "name": "Miami Warehouse"
    },
    "destination": {
      "id": "1",
      "name": "Boston Headquarters"
    },
    "dateRequested": "06/23/2018",
    "requestedBy": {
      "id": "1",
      "name": "Mr Administrator",
      "firstName": "Mr",
      "lastName": "Administrator",
      "email": "admin@pih.org",
      "username": "admin"
    },
    "lineItems": [
      {
        "id": "ff808181644e51a401644e85891b0006",
        "productCode": "00001",
        "product": {
          "id": "ff80818155df9de40155df9e31000001",
          "productCode": "00001",
          "name": "Ibuprofen 200mg",
          "description": null,
          "category": {
            "id": "1",
            "name": "Medicines"
          }
        },
        "palletName": null,
        "boxName": null,
        "statusCode": "PENDING",
        "quantityRequested": 500,
        "quantityAllowed": null,
        "quantityAvailable": null,
        "quantityCanceled": 0,
        "quantityRevised": null,
        "reasonCode": null,
        "comments": null,
        "recipient": null,
        "sortOrder": null
      }
    ]
  }
}
```

## Revise 
This is used to record a revision to the quantity requested. This requires the user to 
choose a reason code (i.e. STOCKOUT) and optionally add comments that may help provide
more context for the revision.

### Request
```
$ curl -b cookies.txt -X POST -H "Content-Type: application/json" \
-d @reviseStockMovementItem.json \
https://openboxes.ngrok.io/openboxes/api/stockMovements/ff808181644d5e5b01644e5007500001|jsonlint
```
### Post Body (reviseStockMovementItem.json)
```
{
    "id": "ff808181644d5e5b01644e5007500001",
    "name": "my new stock movement",
    "description": "",
    "identifier": "483ZSA",
    "origin.id": "2",
    "destination.id": "1",
    "dateRequested": "06/23/2018",
    "requestedBy.id": "1",
    "lineItems": [
      {
        "id":"ff808181644e51a401644e85891b0006",
        "quantityRevised":200,
        "reasonCode":"BECAUSE",
        "comments":"because i said so",
        
      }
    ]
  }
```
### Response
```
{
  "data": {
    "id": "ff808181644d5e5b01644e5007500001",
    "name": "my new stock movement",
    "description": "my new stock movement",
    "identifier": "483ZSA",
    "origin": {
      "id": "2",
      "name": "Miami Warehouse"
    },
    "destination": {
      "id": "1",
      "name": "Boston Headquarters"
    },
    "dateRequested": "06/23/2018",
    "requestedBy": {
      "id": "1",
      "name": "Mr Administrator",
      "firstName": "Mr",
      "lastName": "Administrator",
      "email": "admin@pih.org",
      "username": "admin"
    },
    "lineItems": [
      {
        "id": "ff808181644e51a401644e85891b0006",
        "productCode": "BK71",
        "product": {
          "id": "ff8081816407132d0164071eec250001",
          "productCode": "BK71",
          "name": "product 1+",
          "description": "This is the penultimate product",
          "category": {
            "id": "ROOT",
            "name": "ROOT"
          }
        },
        "palletName": null,
        "boxName": null,
        "statusCode": "CHANGED",
        "quantityRequested": 100,
        "quantityAllowed": null,
        "quantityAvailable": null,
        "quantityCanceled": 100,
        "quantityRevised": 200,
        "reasonCode": "BECAUSE",
        "comments": "because i said so",
        "recipient": null,
        "sortOrder": null
      }
    ]
  }
}
```
## Substitute
This is used to record a substitution for an stock movement item. This requires the user to 
enter a new product and quantity, as well as choose a reason code (i.e. STOCKOUT) and optionally add a comment that may 
help provide more context for the substitution.

### Request
```
$ curl -b cookies.txt -X POST -H "Content-Type: application/json" \
-d @substituteStockMovementItem.json \
https://openboxes.ngrok.io/openboxes/api/stockMovements/ff808181644d5e5b01644e5007500001|jsonlint
```
### Post Body (substituteStockMovementItem.json)
```
{
	"id": "ff808181644d5e5b01644e5007500001",
	"name": "my new stock movement",
	"description": "",
	"identifier": "483ZSA",
	"origin.id": "2",
	"destination.id": "1",
	"dateRequested": "06/23/2018",
	"requestedBy.id": "1",
	"lineItems": [{
		"id": "ff808181644e51a401644e85891b0006",
		"substitute": "true",
		"newProduct.id":"ff80818155df9de40155df9e3312000d",
		"newQuantity":100,
		"reasonCode":"CLINICAL",
		"comments":"A clinical decision that is none of your business",
	}]
}  
```
NOTE: You can add multiple substitutions by adding another line item with the same ID along with 
the `substitute` instruction.

### Response
```
{
  "data": {
    "id": "ff808181644d5e5b01644e5007500001",
    "name": "my new stock movement",
    "description": "my new stock movement",
    "identifier": "483ZSA",
    "origin": {
      "id": "2",
      "name": "Miami Warehouse"
    },
    "destination": {
      "id": "1",
      "name": "Boston Headquarters"
    },
    "dateRequested": "06/23/2018",
    "requestedBy": {
      "id": "1",
      "name": "Mr Administrator",
      "firstName": "Mr",
      "lastName": "Administrator",
      "email": "admin@pih.org",
      "username": "admin"
    },
    "lineItems": [
      {
        "id": "ff808181644e51a401644e85891b0006",
        "productCode": "BK71",
        "product": {
          "id": "ff8081816407132d0164071eec250001",
          "productCode": "BK71",
          "name": "product 1+",
          "description": "This is the penultimate product",
          "category": {
            "id": "ROOT",
            "name": "ROOT"
          }
        },
        "palletName": null,
        "boxName": null,
        "statusCode": "SUBSTITUTED",
        "quantityRequested": 100,
        "quantityAllowed": null,
        "quantityAvailable": null,
        "quantityCanceled": 100,
        "quantityRevised": null,
        "substitutions": [
          {
            "id": "ff8081816458c881016458d22b5f0002",
            "productCode": "00005",
            "product": {
              "id": "ff80818155df9de40155df9e33930011",
              "productCode": "00005",
              "name": "Similac Advance low iron 400g",
              "description": null,
              "category": {
                "id": "1",
                "name": "Medicines"
              }
            },
            "palletName": null,
            "boxName": null,
            "statusCode": "APPROVED",
            "quantityRequested": 100,
            "quantityAllowed": null,
            "quantityAvailable": null,
            "quantityCanceled": null,
            "quantityRevised": null,
            "substitutions": [],
            "reasonCode": null,
            "comments": null,
            "recipient": null,
            "sortOrder": null
          }
        ],
        "reasonCode": "CLINICAL",
        "comments": "A clinical decision that is none of your business",
        "recipient": null,
        "sortOrder": null
      }
    ]
  }
}

```
**IMPORTANT**: If you want to make changes to an existing substitution item, the request body should include 
an instruction to revert the changes along with the modified substitution items. You can also modify 
ANY stock movement item by editing it's corresponding requisition item through the Requisition Item API endpoint
(currently `/api/generic/requisitionItem/:id`). Substitutions and modifications are just children requisition items
under the original requisition item.
```
{
    "id": "ff808181644d5e5b01644e5007500001",
    "name": "my new stock movement",
    "description": "",
    "identifier": "483ZSA",
    "origin.id": "2",
    "destination.id": "1",
    "dateRequested": "06/23/2018",
    "requestedBy.id": "1",
    "lineItems": [{
        "id": "ff8081816458c881016458ca819e0001",
        "revert": "true"
    },	
    {
        "id": "ff8081816458c881016458ca819e0001",
        "substitute": "true",
        "newProduct.id":"ff80818155df9de40155df9e33930011",
        "newQuantity":1000,
        "reasonCode":"CLINICAL",
        "comments":"A clinical decision that is none of your business", 
    },
    {
        "id": "ff8081816458c881016458ca819e0001",
        "substitute": "true",
        "newProduct.id":"ff80818155df9de40155df9e3312000d",
        "newQuantity":500,
        "reasonCode":"CLINICAL",
        "comments":"A clinical decision that is none of your business",	
    }]
}
```
### Exceptions
Cannot substitute a product that is not in the original product's list of available substitutions. 
See the Substitutions API.
```
{
  "errorCode": 500,
  "errorMessage": "Product 00004 General Pain Reliever is not a valid substitution of BK71 product 1+"
}
```
You also cannot substitute the product for itself.
```
{
  "errorCode": 500,
  "errorMessage": "Product BK71 product 1+ is not a valid substitution of BK71 product 1+"
}

```

## Cancel 
Similar to a revision, this operation allows you to cancel the stock movement item.

### Request
```
$ curl -b cookies.txt -X POST -H "Content-Type: application/json" \
-d @cancelStockMovementItem.json \
https://openboxes.ngrok.io/openboxes/api/stockMovements/ff808181644d5e5b01644e5007500001|jsonlint
```
### Post Body (cancelStockMovementItem.json)
```
{
    "id": "ff808181644d5e5b01644e5007500001",
    "name": "my new stock movement",
    "description": "",
    "identifier": "483ZSA",
    "origin.id": "2",
    "destination.id": "1",
    "dateRequested": "06/23/2018",
    "requestedBy.id": "1",
    "lineItems": [
      {
        "id":"ff808181644e51a401644e85891b0006",
        "cancel":"true",
        "reasonCode":"BECAUSE",
        "comments":"more information since BECAUSE is not a good reason"
      }
    ]
}
```

### Response
```
{
  "data": {
    "id": "ff808181644d5e5b01644e5007500001",
    "name": "my new stock movement",
    "description": "my new stock movement",
    "identifier": "483ZSA",
    "origin": {
      "id": "2",
      "name": "Miami Warehouse"
    },
    "destination": {
      "id": "1",
      "name": "Boston Headquarters"
    },
    "dateRequested": "06/23/2018",
    "requestedBy": {
      "id": "1",
      "name": "Mr Administrator",
      "firstName": "Mr",
      "lastName": "Administrator",
      "email": "admin@pih.org",
      "username": "admin"
    },
    "lineItems": [
      {
        "id": "ff808181644e51a401644e85891b0006",
        "productCode": "BK71",
        "product": {
          "id": "ff8081816407132d0164071eec250001",
          "productCode": "BK71",
          "name": "product 1+",
          "description": "This is the penultimate product",
          "category": {
            "id": "ROOT",
            "name": "ROOT"
          }
        },
        "palletName": null,
        "boxName": null,
        "statusCode": "CANCELED",
        "quantityRequested": 100,
        "quantityAllowed": null,
        "quantityAvailable": null,
        "quantityCanceled": 100,
        "quantityRevised": null,
        "reasonCode": "BECAUSE",
        "comments": "more information since BECAUSE is not a good reason",
        "recipient": null,
        "sortOrder": null
      }
    ]
  }
}
```

## Revert 
This allows you to revert any changes made to the stock movement item (including revisions, cancellations, 
and substitutions). However it does not allow you to revert deletes and updates.

### Request
```
$ curl -b cookies.txt -X POST -H "Content-Type: application/json" \
-d @revertStockMovementItem.json \
https://openboxes.ngrok.io/openboxes/api/stockMovements/ff808181644d5e5b01644e5007500001|jsonlint
```
### Post Body (revertStockMovementItem.json)
```
{
    "id": "ff808181644d5e5b01644e5007500001",
    "name": "my new stock movement",
    "description": "",
    "identifier": "483ZSA",
    "origin.id": "2",
    "destination.id": "1",
    "dateRequested": "06/23/2018",
    "requestedBy.id": "1",
    "lineItems": [
      {
        "id":"ff808181644e51a401644e85891b0006",
        "revert":"true"        
      }
    ]
}
```
### Response
```
{
  "data": {
    "id": "ff808181644d5e5b01644e5007500001",
    "name": "my new stock movement",
    "description": "my new stock movement",
    "identifier": "483ZSA",
    "origin": {
      "id": "2",
      "name": "Miami Warehouse"
    },
    "destination": {
      "id": "1",
      "name": "Boston Headquarters"
    },
    "dateRequested": "06/23/2018",
    "requestedBy": {
      "id": "1",
      "name": "Mr Administrator",
      "firstName": "Mr",
      "lastName": "Administrator",
      "email": "admin@pih.org",
      "username": "admin"
    },
    "lineItems": [
      {
        "id": "ff808181644e51a401644e85891b0006",
        "productCode": "BK71",
        "product": {
          "id": "ff8081816407132d0164071eec250001",
          "productCode": "BK71",
          "name": "product 1+",
          "description": "This is the penultimate product",
          "category": {
            "id": "ROOT",
            "name": "ROOT"
          }
        },
        "palletName": null,
        "boxName": null,
        "statusCode": "PENDING",
        "quantityRequested": 100,
        "quantityAllowed": null,
        "quantityAvailable": null,
        "quantityCanceled": 0,
        "quantityRevised": null,
        "reasonCode": null,
        "comments": null,
        "recipient": null,
        "sortOrder": null
      }
    ]
  }
}
```

## Delete 
This operation allows you to delete the stock movement item completely. 

### Request
```
$ curl -b cookies.txt -X POST -H "Content-Type: application/json" \
-d @deleteStockMovementItem.json \
https://openboxes.ngrok.io/openboxes/api/stockMovements/ff808181644d5e5b01644e5007500001|jsonlint
```
### Post Body (deleteStockMovementItem.json)
```
{
    "id": "ff808181644d5e5b01644e5007500001",
    "name": "my new stock movement",
    "description": "",
    "identifier": "483ZSA",
    "origin.id": "2",
    "destination.id": "1",
    "dateRequested": "06/23/2018",
    "requestedBy.id": "1",
    "lineItems": [
      {
        "id":"ff808181644e51a401644e85891b0006",
        "delete":"true",
      }
    ]
}
```

### Response
```
{
  "data": {
    "id": "ff808181644d5e5b01644e5007500001",
    "name": "my new stock movement",
    "description": "my new stock movement",
    "identifier": "483ZSA",
    "origin": {
      "id": "2",
      "name": "Miami Warehouse"
    },
    "destination": {
      "id": "1",
      "name": "Boston Headquarters"
    },
    "dateRequested": "06/23/2018",
    "requestedBy": {
      "id": "1",
      "name": "Mr Administrator",
      "firstName": "Mr",
      "lastName": "Administrator",
      "email": "admin@pih.org",
      "username": "admin"
    },
    "lineItems": []
  }
}
```

### Exceptions
This operation 
cannot be performed on a stock movement item that has been revised (due to a bug with 
foreign key constraints). 
```
{
  "errorCode": 500,
  "errorMessage": "Cannot delete or update a parent row: a foreign key constraint fails (`openboxes_integration`.`requisition_item`, CONSTRAINT `FK5358E4D6405AC22D` FOREIGN KEY (`modification_item_id`) REFERENCES `requisition_item` (`id`))"
}
```
Therefore you must revert all changes to the stock movement 
item before deleting.


## Picking

### Request
```
curl  -b cookies.txt -X POST -H "Content-Type: application/json" \
-d @pickStockMovementItems.json \
https://openboxes.ngrok.io/openboxes/api/stockMovementItems/ff808181646b260401646b5bf4cb002b
```
### Post Body (pickStockMovementItem.json)
```
{
	"picklistItems":[{
        "id": "ff80818164787ed10164788a0f190022",
	    "inventoryItem.id": "ff8081816473166d0164731d419f000c",
	    "binLocation.id": "ff808181646d3ec101646d5e8e3e0003",
	    "quantityPicked":"10"
	}]
}

```

NOTE: To create a pick list item, remove the ID field from the post body (value can also be empty string).
To edit an existing picklist item, specify the ID from the `picklistItems` array. To delete the picklist item
assign a value of 0 to the `quantityPicked` field.


### Exceptions
This operation might fail if the quantity picked of the selected item is greater than
the quantity on hand of that item in stock.