Cancel Order

Overview

The Cancel Order Endpoint is designed to allow users to cancel an order that has already been created but has not yet been shipped. This functionality provides greater flexibility in order management and ensures that users do not incur unnecessary costs for orders that are no longer needed.

This endpoint is particularly important for orders that use the Bank Transfer payment method. When an order is created with this payment method, the system automatically deducts the shipping cost from the user’s dashboard balance. If the order is later canceled, the system will refund the previously deducted balance, ensuring a fair and transparent process.

By implementing this endpoint, users can manage their orders efficiently, preventing unnecessary shipments and maintaining full control over their transactions.

Key Feature

✅ Flexibility: Users can cancel orders that are no longer needed before they are shipped.
✅ Automatic Refunds: If a Bank Transfer payment was used, the system will automatically return the deducted balance, reducing financial risk for the user.
✅ Transparency: The cancellation process ensures that users have full visibility into their order and financial status.
✅ Error Prevention: By canceling unnecessary orders early, users can avoid incorrect shipments and additional logistics costs.
✅ User-Friendly Process: The cancellation request is processed instantly, providing a seamless experience for users.

How it Works

Eligibility for Cancellation

1. Not all orders can be canceled. To be eligible for cancellation, an order must meet the following conditions:
   • Order Status Requirement
   • The order must be in “Created” or “Packing” status.
   • Orders in “Shipped”, “In Transit”, or “Delivered” status cannot be canceled.
   • If an order is already in the shipping process, cancellation is no longer possible, as the order is already being handled by the logistics provider.
2. Payment Method Considerations
   • Orders paid via Bank Transfer will have their shipping costs automatically deducted from the user’s dashboard balance at the time of order creation.
   • If such an order is canceled, the system will automatically refund the deducted balance back to the user’s account.
   • Orders paid using Cash on Delivery (COD) or other non-prepaid payment methods do not involve balance deductions, and therefore do not require a refund upon cancellation.
3. Cancellation Timeframe
   • Users must request cancellation before the order is shipped. Once the package has been handed over to the courier, the order can no longer be canceled.
   • The system will immediately validate the cancellation request and process it accordingly.

How the Cancellation Process Works

1. User Initiates Cancellation Request
   • The user sends a cancellation request via the Cancel Order Endpoint, including the order ID and relevant details.
   • The system checks the current status of the order to determine if it is eligible for cancellation.
2. System Validation
   • The system verifies whether the order is in “Created” or “Packing” status.
   • If the order is in a valid status, the system approves the cancellation request.
   • If the order has already been shipped or has an invalid status, the request is rejected, and an error message is returned.
3. Automatic Refund for Bank Transfer Payments
   • If the order was paid using Bank Transfer, the system automatically refunds the deducted balance to the user’s dashboard.
   • This ensures that the user does not lose funds on canceled orders.
4. Order Status Update
   • Once successfully canceled, the order status is updated to “Canceled”, preventing further processing or shipping.
   • The cancellation is recorded in the system for future reference.

Common Scenarios Where Order Cancellation is Useful

1. The buyer changes their mind : If the customer decides not to proceed with the order before it is shipped, the seller can cancel it immediately.
2. Incorrect order details : If the order contains incorrect shipping information, product details, or pricing errors, the user can cancel the order and create a new one with the correct details.
3. Out-of-stock products : If the seller realizes that a product is unavailable, they can cancel the order before processing it further.
4. Payment-related issues : If there was an issue with payment (e.g., insufficient balance or failed transaction), the order can be canceled to prevent further complications.
5. Accidental order creation : In cases where an order was placed by mistake, the cancellation feature allows users to correct the situation without unnecessary costs.

Request Body

cURL

curl --location --request PUT 'https://api-sandbox.collaborator.komerce.id/order/api/v1/orders/cancel' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-api-key: inputapikey' \
--data '{
  "order_no": "KOMXXXXXXXXXXXXXXXXX"
}'

JavaScript

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Accept", "application/json");
myHeaders.append("x-api-key", "inputapikey");

const raw = JSON.stringify({
  "order_no": "KOMXXXXXXXXXXXXXXXXX"
});

const requestOptions = {
  method: "PUT",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("https://api-sandbox.collaborator.komerce.id/order/api/v1/orders/cancel", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api-sandbox.collaborator.komerce.id/order/api/v1/orders/cancel',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_POSTFIELDS =>'{
  "order_no": "KOMXXXXXXXXXXXXXXXXX"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Accept: application/json',
    'x-api-key: inputapikey'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

GoLang

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "https://api-sandbox.collaborator.komerce.id/order/api/v1/orders/cancel"
  method := "PUT"

  payload := strings.NewReader(`{
  "order_no": "KOMXXXXXXXXXXXXXXXXX"
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("Accept", "application/json")
  req.Header.Add("x-api-key", "inputapikey")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := io.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

Node

const axios = require('axios');
let data = JSON.stringify({
  "order_no": "KOMXXXXXXXXXXXXXXXXX"
});

let config = {
  method: 'put',
  maxBodyLength: Infinity,
  url: 'https://api-sandbox.collaborator.komerce.id/order/api/v1/orders/cancel',
  headers: { 
    'Content-Type': 'application/json', 
    'Accept': 'application/json', 
    'x-api-key': 'inputapikey'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Query Parameter

Headers

Key	Type	Description
x-api-key*	string	this Value contain an secret APIKEY identic for Shipping API.

Body RAW

Key	Type	Description
order_no*	string	This value is requested according to the order number that will be canceled.

danger

For each header and parameter that has a * sign, it is a parameter that must be Required when making a request, otherwise there will be a system error that will warn the user regarding the request made.

Response

Response Structure

Key	Value (Description)
meta.message	Message indicating the result of the API request.
meta.code	HTTP status code representing the request status.
meta.status	Status of the API response (e.g., success or error).
data.null	Indicates a successful cancel status without any warning.
data.errors	Indicates a failed cancel status with a warning.

Success Respons for Canceling Order

{
    "meta": {
        "message": "success cancel order",
        "code": 200,
        "status": "success"
    },
    "data": null
}

Error Respons for Canceling Order

{
    "meta": {
        "message": "cancel order failed",
        "code": 422,
        "status": "error"
    },
    "data": {
        "errors": "Failed Cancel order, order status "
    }
}

Error Code

Code	Status	Description	How to Fix
400	Not Found	order_no not found	Check the order_no again, whether it matches the order number that was previously created.
401	Unauthorized	API key invalid or missing from parameter	Make sure your API key is valid using your Account
422	Failed	Failed Cancel order, order status	Check the order number to be canceled, whether it is registered or not. Or it could be because the order status has been canceled before
500	-	-	-

Tips to Avoid Error

1. Use a valid order_no: Ensure the order_no exists and is correctly written.
2. Provide a clear cancelation_reason : This field is required. Use reasons like “Customer changed mind” or “Wrong address”.
3. Check order status before canceling : Only orders that haven’t been shipped can be canceled.
4. Use correct JSON format : Make sure your payload is valid request body
5. Avoid duplicate cancel requests : Don’t send a cancel request again if the order is already canceled.
6. Use a valid API token : Make sure your apikey is active and authorized.