Skip to main content

​
PATCH /api/orders/:id/status

Allows administrators to manually update an order’s status and transaction hash. This is typically used for manual interventions, refunds, or resolving payment issues.

​
Authentication

Requires JWT authentication token with admin role in the Authorization header.

​
Authorization

Only users with role: 'admin' can access this endpoint.

​
Path Parameters

​
id
string
required
MongoDB ObjectId of the order to update

​
Request Body

​
status
string
required
New order status. Valid values: pending, completed, refunded
​
transactionHash
string
Blockchain transaction hash (optional, used when manually adding transaction proof)

​
Response

​
success
boolean
Indicates if the status was updated successfully
​
message
string
Confirmation message
​
order
object
Updated order object with new status
​
status
string
Updated order status
​
transactionHash
string
Transaction hash (if provided)
​
updatedAt
string
ISO 8601 timestamp of the update

​
Valid Status Transitions

Administrators can set the following statuses:
  • pending - Reset order to pending state
  • completed - Mark order as successfully completed
  • refunded - Mark order as refunded to customer
Note: The endpoint validation only allows these three statuses. To mark orders as ‘failed’ or ‘cancelled’, use other system mechanisms or update the validation rules.

​
Common Use Cases

  1. Manual Refund - Change status to refunded after processing a blockchain refund transaction
  2. Manual Completion - Mark as completed if blockchain confirmation was missed
  3. Add Transaction Hash - Update order with transaction hash if it was missing
  4. Reset Order - Return to pending if payment needs to be retried

​
Error Responses

400 Bad Request - Invalid status 
{
  "error": "Invalid status"
}
404 Not Found - Order doesn’t exist 
{
  "error": "Order not found"
}
500 Internal Server Error 
{
  "error": "Database update failed"
}

​
Example Request

# Mark order as completed
curl -X PATCH https://api.cryptoshop.com/api/orders/507f1f77bcf86cd799439011/status \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed"
  }'

# Mark order as refunded with transaction hash
curl -X PATCH https://api.cryptoshop.com/api/orders/507f1f77bcf86cd799439011/status \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "refunded",
    "transactionHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  }'

​
Example Response

{
  "success": true,
  "message": "Order status updated",
  "order": {
    "_id": "507f1f77bcf86cd799439011",
    "orderId": "#TRX-1",
    "userId": "507f191e810c19729de860ea",
    "products": [
      {
        "productId": "507f1f77bcf86cd799439011",
        "name": "iPhone 14 Pro",
        "price": 999,
        "quantity": 1,
        "color": "black"
      }
    ],
    "subtotal": 999,
    "networkFee": -0.01,
    "total": 998.99,
    "status": "refunded",
    "transactionHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "walletAddress": "TUserWalletAddress123456789",
    "merchantAddress": "TMerchantWalletAddress456789",
    "createdAt": "2026-03-04T10:30:00.000Z",
    "updatedAt": "2026-03-04T11:15:00.000Z"
  }
}

​
Important Notes

  • This endpoint is restricted to admin users only
  • The updatedAt timestamp is automatically updated
  • Only three status values are allowed: pending, completed, refunded
  • The transaction hash is optional and only needs to be provided when adding/updating transaction proof
  • No stock adjustments or refund transactions are automatically processed - this endpoint only updates the order record
  • For complete refund workflows, admins should:
    1. Process the blockchain refund transaction separately
    2. Use this endpoint to update the order status to ‘refunded’
    3. Include the refund transaction hash in the request

Build docs developers (and LLMs) love

Get started for freeTalk to us