To reduce the customer contact rate and chargebacks from customers, Shieldware, Inc. offers a self-service refund option on their website. Using this option, customers can request a refund themselves, without having to involve a customer service representative. Shieldware's development team implemented the refund option using the GraphQL API.

You can use the GraphQL API to issue a refund to a customer. This can be useful for customers who were incorrectly charged, canceled your service before a certain date, or were not satisfied with the product.

📘

Note

You can execute a maximum number of refunds per minute simultaneously via GraphQL API. If not configured, the default limit is set to 10 refunds per minute. For more information on the configuration of your account, contact Client Experience.

You can refund money in the following ways using the GraphQL API:

Refund Total Amount

To refund the total amount of a purchase, use the refundAll mutation object. You must provide a purchaseId and refundReason in the basicRefundOptions argument. The other fields are optional.

Example Request

mutation {
  refundAll(
    basicRefundOptions: {
      purchaseId: 124147819
      reclaimFromClient: true
      recalculateFee: false
      refundReason: INSTALLATION_FAILED
      remark: "customer was very upset"
      deactivateSubscription: true
      suppressCustomerMail: false
    }
  ) {
    refundedPurchase {
      id
      status {
        name
      }
    }
  }
}

The API call returns the refundAll object with the requested fields. You can use the value of the name field to display the new purchase status to the customer.

Example Response

{
  "data": {
    "refundAll": {
      "refundedPurchase": {
        "id": 124147819,
        "status": {
          "name": "Refunded"
        }
      }
    }
  }
}

Cleverbridge processes the refund and sends out the following:

• An email to the customer that confirms the refund and contains a credit note. For more information, see Handle refunds.
• A RefundNotificationto the endpoint of your choice, which you can use to update the transactional data in your internal system. For more information, see Notifications.

Refund Partial Amount

🚧

Important

You can make multiple partial refunds but only until you reach the total amount of the purchase.

To refund part of a charge, use the refundAmount mutation object. In the basicRefundOptions argument, you must, among other things, provide the amount to be refunded and the purchaseItemRunningNumber the refund refers to.

Example Request

mutation {
  refundAmount(
    basicRefundOptions: {
      purchaseId: 124147819
      reclaimFromClient: true
      recalculateFee: false
      refundReason: INSTALLATION_FAILED
      remark: "customer was very upset"
      deactivateSubscription: true
      suppressCustomerMail: false
    }
    purchaseItemRunningNumber: 1
    amount: 10
    isGross: true
  ) {
    refundedPurchase {
      id
      status {
        name
      }
    }
  }
}

The API call returns the refundAmount object with the requested fields. You can use the value of the name field to display the new purchase status to the customer.

Example Response

{
  "data": {
    "refundAmount": {
      "refundedPurchase": {
        "id": 124147819,
        "status": {
          "name": "Partially Refunded"
        }
      }
    }
  }
}

Cleverbridge processes the refund and sends out the following:

• An email to the customer that confirms the refund and contains a credit note. For more information, see Handle refunds.
• A PartialRefundNotification to the endpoint of your choice, which you can use to update the transactional data in your internal system. For more information, see Notifications

Refund Amount for Item

To refund the amount for a specific item of the purchase, use the refundItems mutation object. In the basicRefundOptions argument, you must, among other things, provide the purchaseItemRunningNumber of the item you would like to refund.

Example Request

mutation {
  refundItems(
    basicRefundOptions: {
      purchaseId: 124147819
      reclaimFromClient: true
      recalculateFee: false
      refundReason: INSTALLATION_FAILED
      remark: "customer was very upset"
      deactivateSubscription: true
      suppressCustomerMail: false
    }
    purchaseItemRunningNumbers: 1
  ) {
    refundedPurchase {
      id
      status {
        name
      }
    }
  }
}

The API call returns the refundItems object with the requested fields. You can use the value of the name field to display the new purchase status to the customer.

Example Response

{
  "data": {
    "refundItems": {
      "refundedPurchase": {
        "id": 124147819,
        "status": {
          "name": "Partially Refunded"
        }
      }
    }
  }
}

Cleverbridge processes the refund and sends out the following:

• An email to the customer that confirms the refund and contains a credit note. For more information, see Handle refunds.
• A PartialRefundNotification to the endpoint of your choice, which you can use to update the transactional data in your internal system. For more information, see Notifications.

Add Coupon Code

To add a coupon code to an existing order, and refund the corresponding discount to the customer, use the refundCoupon mutation object. You must provide a purchaseId and the couponCode. The third field is optional.

Example Request

mutation {
  refundItems(
    basicRefundOptions: {
      purchaseId: 124147819
      reclaimFromClient: true
      recalculateFee: false
      refundReason: INSTALLATION_FAILED
      remark: "customer was very upset"
      deactivateSubscription: true
      suppressCustomerMail: false
    }
    purchaseItemRunningNumbers: 1
  ) {
    refundedPurchase {
      id
      status {
        name
      }
    }
  }
}

The API call returns the refundItems object with the requested fields. You can use the value of the name field to display the new purchase status to the customer.

Example Response

{
  "data": {
    "refundItems": {
      "refundedPurchase": {
        "id": 124147819,
        "status": {
          "name": "Partially Refunded"
        }
      }
    }
  }
}

Cleverbridge processes the refund and sends out the following:

• An email to the customer confirms the refund and contains a credit note. For more information, see Handle refunds.
• A PartialRefundNotification to the endpoint of your choice, which you can use to update the transactional data in your internal system. For more information, see Notifications.

📘

Note

When you issue a refund, the money is returned to the customer via the original payment method. When a bank or credit card payment was used, your customer will see the refund as a credit about 5-10 business days after the refund date, depending on their bank.