Refund Webhooks

All the customers who are using ClickPost Returns and Exchanges module to handle refunds can use these webhooks

Usecase

This webhook is useful for customers using ClickPost returns and exchange platform. It is triggered whenever a refund status update occurs — whether the refund has been initiated, successfully processed, or has failed — for both return and exchange orders.

Activating Refund Webhooks:

Visit ClickPost dashboard: Settings Tab on the right and click the Notification section.
Select Webhooks and activate the relevant events under Selected Webhooks Configuration:

  • Return Refund Initiated
  • Return Refund Processed
  • Return Refund Failed
  • Exchange Refund Initiated
  • Exchange Refund Processed
  • Exchange Refund Failed

Status Code Reference

The status, clickpost_status_code, and notification_event_id fields in the payload will vary based on the event triggered. All other fields in the payload remain structurally identical.

Notification Typestatusclickpost_status_codenotification_event_id
Return Refund InitiatedReturn Refund Initiated10081008
Return Refund ProcessedReturn Refund Processed10091009
Return Refund FailedReturn Refund Failed10101010
Exchange Refund InitiatedExchange Refund Initiated10111011
Exchange Refund ProcessedExchange Refund Processed10121012
Exchange Refund FailedExchange Refund Failed10131013

Webhook Payload

The sample below shows a Return Refund Initiated event. Replace the status, clickpost_status_code, and notification_event_id values as per the table above for other events.

{
  "waybill": "RE71824491766401910",
  "status": "Return Refund Initiated",
  "timestamp": "2026-01-07T12:06:13Z",
  "location": "",
  "remark": "Return Refund Initiated",
  "clickpost_status_code": 1008,
  "clickpost_city": null,
  "clickpost_status_description": "Return Refund Initiated",
  "account_code": "",
  "cp_id": 34,
  "rto_awb": null,
  "additional": {
    "latest_status": {
      "location": "",
      "remark": "Return Refund Initiated",
      "clickpost_status_code": 1008,
      "clickpost_status_description": "Return Refund Initiated",
      "clickpost_status_bucket_description": "Return Refund Initiated",
      "status": "Return Refund Initiated",
      "clickpost_status_bucket": 8,
      "timestamp": "2026-01-07T12:06:13Z"
    },
    "source": "dashboard",
    "forward_order_id": "X12345",
    "is_rvp": true,
    "forward_awb": "1111111111",
    "forward_reference_number": "12345-XZ02",
    "notification_event_id": 1008,
    "self_shipped": false,
    "item_info": [
      {
        "sku": "222222222",
        "quantity": 1,
        "return_reason": "Defective product was delivered",
        "refund_mode": "Back to source",
        "customer_comment": "Damage product",
        "id": "1234422134",
        "return_mode": "REFUND",
        "description": "Black Mid Rise Cargo Pants",
        "return_sub_reason": "I received a damaged or defective product",
        "images": "https://www.shutterstock.com/image-photo/blank-collared-shirt-mock-template-600nw-1287554233.jpg",
        "customer_uploaded_images": "",
        "shopify_line_item_id": "1734917128379"
      }
    ],
    "return_reference_number": "RE71824491766401910",
    "refund_details": {
      "refund_mode": "Bank Account Transfer",
      "refund_status": "Initiated",
      "refund_amount": 500.00,
      "bank_details": {
        "name": "John Doe",
        "ifsccode": "ICIC12345",
        "bank_name": "ICICI Bank",
        "branch_name": "KORAMANGALA BANGALORE",
        "account_number": "123456789"
      }
    }
  },
  "request_placed_time": "2025-12-22T11:11:50Z",
  "pickup_info": {
    "customer_name": "John Doe",
    "customer_email": "[email protected]",
    "customer_phone_number": "9999999999",
    "pickup_state": "KA",
    "pickup_address": "123, abc street, Bangalore, Karnataka",
    "pickup_pincode": "560001",
    "pickup_city": "Bangalore",
    "pickup_country": "IN"
  }
}

refund_details Object — Variations by Refund Mode

The refund_details object is nested inside the additional object. Its structure varies depending on the refund mode chosen by the customer. The refund_status field inside this object will be "Initiated", "Processed", or "Failed" depending on the event.

Bank Account Transfer

"refund_details": {
  "refund_mode": "Bank Account Transfer",
  "refund_status": "Initiated",
  "refund_amount": 564.6,
  "bank_details": {
    "name": "John Doe",
    "ifsccode": "ICIC12345",
    "bank_name": "ICICI Bank",
    "branch_name": "KORAMANGALA BANGALORE",
    "account_number": "123456789"
  }
}

UPI Transfer

"refund_details": {
  "refund_mode": "UPI Transfer",
  "refund_status": "Processed",
  "refund_amount": 564.6,
  "upi_details": {
    "payment_mode": {
      "label": "Google Pay",
      "value": "google_pay"
    },
    "phone_number_vpa": "dummy@upi"
  }
}

Payout Link

"refund_details": {
  "refund_mode": "Payout Link",
  "refund_status": "Processed",
  "refund_reference_number": "poutlk_12345",
  "refund_amount": 659.0,
  "payout_link": "https://rzp.io/rzp/12345",
  "payout_link_active": false
}

Discount Code

"refund_details": {
  "refund_mode": "Discount Code",
  "refund_status": "Processed",
  "refund_amount": 564.6,
  "discount_coupon_code": "coupon_code"
}

Gift Card

"refund_details": {
  "refund_mode": "Gift Card",
  "refund_status": "Processed",
  "refund_reference_number": "571188838494",
  "refund_amount": 1700.0,
  "gift_card_code": "gift_card_code",
  "gift_card_code_expiry": "2027-01-08T00:00:00Z"
}

Original Payment Method (Shopify)

"refund_details": {
  "refund_mode": "Original Payment method (Shopify)",
  "refund_status": "Processed",
  "refund_reference_number": "gid://shopify/Refund/123456",
  "refund_amount": 1729.0
}

Refund to Source Account

"refund_details": {
  "refund_mode": "Refund To Source Account",
  "refund_status": "Processed",
  "refund_amount": 300.0
}

Store Credit

"refund_details": {
  "refund_mode": "Brand Credits",
  "refund_status": "Processed",
  "refund_reference_number": "null",
  "refund_amount": 327.0,
  "store_credit_code": "NA",
  "store_credit_transaction_id": "44204113",
  "store_credit_server": "SHOPIFY"
}

Manual

"refund_details": {
  "refund_mode": "Other mode (Manually)",
  "refund_status": "Processed",
  "refund_amount": 1539.0
}