Documenting your REST API

Title

<Additional information about your API call. Try to use verbs that match both request type (fetching vs modifying) and plurality (one vs multiple).>

URL

<The URL Structure (path only, no root url)>
Method:

<The request type>

GET | POST | DELETE | PUT

**URL Params**

<_If URL params exist, specify them in accordance with name mentioned in URL section. Separate into optional and required. Document data constraints._>

Required:
- id=[integer]
Optional:
- photo_id=[alphanumeric]

**Data Params**

<_If making a post request, what should the body payload look like? URL Params rules apply here too._>

**Sample Call**

<_Just a sample call to your endpoint in a runnable format ($.ajax call or a curl request) - this makes life easier and more predictable._>

**Success Response**

<_What should the status code be on success and is there any returned data? This is useful when people need to to know what their callbacks should expect!_>

Code: 200
Content:
```
{ "id" : 12 }
```

**Error Response**

<_Most endpoints will have many ways they can fail. From unauthorized access, to wrongful parameters etc. All of those should be liste d here. It might seem repetitive, but it helps prevent assumptions from being made where they should be._>

Code: 401 UNAUTHORIZED
Content:
```
{ "error" : "Log in" }
```

Code: 422 UNPROCESSABLE ENTRY
Content:
```
{ "error" : "Email Invalid" }
```

**Notes**

<_This is where all uncertainties, commentary, discussion etc. can go. I recommend timestamping and identifying oneself when leaving comments here._>

Cancel Orders

API for cancellation of order. Order can only be cancelled if the products have not been shipped. Cancellation can be for the entire order or specific item in the order

URL

/control/cancelOrderOrOrderItem
Method:

POST

**URL/POST Params**

- **Required:** + `orderId=[alphanumeric]` *Order id to be canceled* + `refundType=[string]` - `"storecredit"` or `"manualrefund"` *Method of order amount refund*

Optional:
- orderItemSeqId=[string] Order item sequence id of order item to be cancelled
- cancelQuantity=[number] Specific number of quantity to be cancelled

**Sample Call**

```bash curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \ -d 'orderId=BY861380&refundType=storecredit' \ "https://www.example.com/control/cancelOrderOrOrderItem"

curl -X POST -H "Content-Type: application/x-www-form-urlencoded"
-d 'orderId=BY861325&refundType=storecredit&orderItemSeqId=00002&cancelQuantity=1'
"https://www.example.com/control/cancelOrderOrOrderItem"

</details>

<details>
    <summary>**Success Response**</summary>
* **Code:** 200 OK <br />
  **Content:**
  ```json
  {
    "result": "success",
    "cancellationSucess": "Y",
    "refundType": "storecredit",
    "comments": "Order cancelled successfully"
  }

Code: 200 OK
Content:

{
  "result": "success",
  "cancellationSucess": "Y",
  "refundType": "storecredit",
  "comments": "Order item cancelled successfully"
}

**Error Response**

* **Code:** 200 OK
**Reason:** User not logged in
**Content:** ```json { "result": "error", "ERR_CODE": "1002", "message": "Unauthorised request. Please login with your credentials." }


OR

* **Code:** 200 OK <br />
**Reason:** If the order does not belong to the logged in user <br />
**Content:**
```json
{
  "errorMessage": "You do not have permission to change this order's status.",
  "result": "error",
  "cancellationSucess": "N",
  "comments": "Order could not be cancelled"
}

Code: 200 OK
Reason: If the order does not exist
Content:

{
  "errorMessage": "Order not found with orderId [BY861380]",
  "result": "error",
  "cancellationSucess": "N",
  "comments": "Order could not be cancelled"
}

Code: 200 OK
Reason: Cancel quantity more than originally bought
Content:

{
  "errorMessage": "Invalid cancel quantity; cannot cancel 2",
  "result": "error",
  "cancellationSucess": "N",
  "comments": "Order item could not be cancelled"
}

**Notes**

- This request can also be made with `GET` method using query parameters but this is not recommended. - Repeated calls to the endpoint with valid parameters will result in successful request. It will not indicate that the order was already cancelled. - Invalid item sequence id is not validated and request will be successful.

suhas-karanth/API.md

Title

Cancel Orders