Skip to main content

Create Order

Overview​

The Store Order Endpoint allows users to create an order that will be validated and processed by Komerce. This endpoint integrates data obtained from previous steps:

  • Search Destination Endpoint → Provides origin & destination IDs.
  • Calculate Endpoint → Provides shipping cost details, including courier information.

Once an order is created, the system automatically deducts the shipping fee from the user’s dashboard balance (if using the Bank Transfer method). If the balance is insufficient, the order will not be processed, and an error response will be returned.

Key Features​

✅ Seamless Order Creation – Integrates with previous endpoints to streamline the process.
✅ Automated Balance Deduction – Ensures smooth transactions for prepaid orders.
✅ Strict Data Validation – Ensures correct phone number format & other required fields.
✅ Supports Multiple Payment Methods – Including COD and Bank Transfer.

How it Works​

Required Data for Order Creation​

Users must provide the following details:

  • Order Information → Order date, brand name, shipper & receiver details.
  • Shipping Details → Courier name, service type, shipping cost.
  • Payment Method → COD or Bank Transfer. Unfortunetly, we don't have invoicing method automaticly. But, you can use invoicing method if you contact our Business Development for request invoicing method.
  • Product Details → Name, variant, weight, dimensions, quantity.
warning
  • Phone numbers must start with 62 or 8 (e.g., 6281234567890, 81234567890), not start with 0 or +62.
  • An insufficient balance will prevent order processing if your balance is less than the value of the shipping charges to be made.
  • Ensure all required fields are formatted correctly to avoid errors.

Order Processing and Validation​

Once an order is submitted:

  1. The system validates the order details, including phone numbers, shipping cost, and payment method.
  2. If using Bank Transfer, the shipping cost is deducted from the user’s balance.
  3. If all data is valid, the order is sent to us for processing.
  4. The system returns a confirmation response, indicating the order has been successfully created.

Request Body​

curl --location 'https://api-sandbox.collaborator.komerce.id/order/api/v1/orders/store' \
--header 'x-api-key: inputapikey' \
--data-raw '{
    "order_date": "2025-05-21",
    "brand_name": "Xiaomi Official",
    "shipper_name": "XIAOMI",
    "shipper_phone": "82121669737",
    "shipper_destination_id": 5969,
    "shipper_address": "Alamat pengirim",
    "shipper_email": "garut@gmail.com",
    "origin_pin_point": "-7.274631, 109.207174"
    "receiver_name": "Buyer Bandung",
    "receiver_phone": "8123458282",
    "receiver_destination_id": 4956,
    "receiver_address": "Alamat penerima",
    "shipper_email": "admin@admin.com",
    "destination_pin_point": "-7.274631, 109.207174",
    "shipping": "JNE",
    "shipping_type": "REG23",
    "payment_method": "BANK TRANSFER",
    "shipping_cost": 16000,
    "shipping_cashback": 4000,
    "service_fee": 0,
    "additional_cost": 0,
    "grand_total": 516000,
    "cod_value": 0,
    "insurance_value": 5631.11,
    "order_details": [
        {
            "product_name": "Xiaomi Redmi Note 99",
            "product_variant_name": "Blue 8/256",
            "product_price": 315555,
            "product_weight": 1000,
            "product_width": 10,
            "product_height": 8,
            "product_length": 50,
            "qty": 1,
            "subtotal": 315555
        }
    ]
}'

Query Parameter​

Headers​

KeyTypeDescription
x-api-key*stringthis Value contain an secret APIKEY identic for Shipping API

Body RAW​

KeyTypeDescription
order_date*date-timeThe date and time when the order was created.
brand_name*stringThe brand name displayed on the shipping label.
shipper_name*stringThe name of the person sending the package.
shipper_phone*stringThe phone number of the sender.
shipper_destination_id*intThe ID representing the pickup location for the shipment.
origin_pin_pointstringGeolocation (latitude, longitude) of the pickup address.
shipper_address*stringFull address of the sender for pickup.
shipper_email*stringEmail address of the sender.
receiver_name*stringThe name of the recipient.
receiver_phone*stringThe phone number of the recipient.
receiver_destination_id*intThe ID representing the delivery destination.
destination_pin_pointstringGeolocation (latitude, longitude) of the delivery address.
receiver_address*stringFull delivery address of the recipient.
receiver_emailstringEmail address of the recipient.
shipping*stringSelected shipping courier, e.g., JNE, SICEPAT, SAP, IDEXPRESS, J&T, NINJA.
shipping_type*stringShipping service type, such as REG19, GOKIL, REGULER, INSTANT, etc.
shipping_cost*intThe standard shipping cost charged to the user.
shipping_cashback*intDiscount or cashback applied to the shipping cost.
payment_method*stringThe payment method used for the order (e.g., COD, bank transfer).
service_fee*intAdditional fee charged when using COD (typically 2.8% of the product price).
additional_cost*intAny extra costs related to the order (e.g., packaging, handling).
grand_total*intTotal payment amount, calculated as: product total + shipping cost + additional cost - shipping cashback.
cod_value*intCOD payment amount. This value must match the grand_total.
insurance_value*floatDeclared value for insurance, if insurance is used.
product_name*stringName of the product being shipped.
product_variant_name*stringVariant or specific type of the product (if applicable).
product_price*intPrice per unit of the product.
product_width*intProduct width in centimeters.
product_height*intProduct height in centimeters.
product_length*intProduct length in centimeters.
product_weight*intProduct weight in grams.
qty*intQuantity of the product ordered.
subtotal*intTotal product value, calculated as product_price * qty.
Pinpoint information

Additional information for the using origin or destination, pin_point is used to calculate the estimated shipping cost by using Instant or LionParcel Courier. Make sure the pin_point data sent is in accordance with the estimated delivery from the origin location to the destination so that the courier can pick up and deliver to the appropriate address.

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​

KeyValue
meta.messageResponse for creating an order
meta.codeAny respons have different status code
meta.statusBollean status for creating an order
data.order_idAn unique id if successfully creating an order
data.order_noAn unique number for order

Success Respons for Creating an Order​

{
    "meta": {
        "message": "Success Create New Order",
        "code": 201,
        "status": "success"
    },
    "data": {
        "order_id": 9999,
        "order_no": "KOMXXXXXXXXXXXXXXXXX"
    }
}

Error Respons for Creating an Order​

example.json
{
    "meta": {
        "message": "{{ error.message }}",
        "code": 400,
        "status": "failed"
    },
    "data": null
}

Error Code​

CodeStatusDescriptionHow to Fix
400FailedThere is a mismatch in one or more of the parameters usedCheck all available parameters, make sure the values entered match the desired conditions.
401UnauthorizedAPI key invalid or missing from parameterMake sure your API key is valid using your Account.
422Unprocessable EntityParameter is missingAdd an valid parameter in your requested query. Parameter Request can't be null or missing
500---

Tips to Avoid Errors​

  1. Always include the Authorization header with a valid token.
  2. Do not leave the any parameter empty — it’s required.
  3. Makesure all parameters using correct value
  4. Use the correct endpoint and query structure.