How do you integrate Instant with a refunds system?

The refund order API can cater for use cases where a third party system needs to call Instant to process refunds.

It is recommended that Instant brands utilise the Instant dashboard, or eCommerce dashboards to process refunds.

However, if your integration is more advanced / bespoke, and requires custom integration with Instant's Orders API, the documentation below can assist with integration. Please contact Instant support or your Customer Success Manager for assistance if you encounter any issues.

Any refunds created through this endpoint will be immediately available in the Instant dashboard as well.

Endpoint (POST):




X-Instant-App-Auth: {YOUR_APP_AUTH_TOKEN}
X-Instant-App-Id: {YOUR_APP_ID}

If you do not have these values, please contact your Customer Success manager.

Please note that the header values are case-sensitive.


"amountToRefund": number // Amount to refund, e.g. 10.99 for 10 dollars and 99 cents.
"displayOrderId": string // Customer facing order ID.
"storeCode": string // This is provided by Instant.

If you do not have the storeCode, please contact your Customer Success manager.

Please note that for Magento, displayOrderId is the order increment ID - i.e. the order ID the customer sees, which differs from the entity ID (the underlying database ID).

For BigCommerce and WooCommerce, the displayOrderId is the order ID the customer sees.

The amount to refund will be rounded to the nearest smallest unit of currency, and the amount after rounding must be a positive value.


Status: 200 - refund successful and no further action required 

Status: 500 - possible responses. If INTENRAL_SERVER_ERROR is received, please contact Instant support for more details.

"error": string,
"message": string

The possible values for the "error" field are below.

REFUND_FAILURE - indicates a failure with the refund. Please contact Instant support for assistance.
INVALID_AMOUNT_TO_REFUND - indicates the amountToRefund is invalid. Ensure that the amount is not zero or negative, and the amount represents more than a single unit of currency.
POSSIBLE_DUPLICATE_REFUND - indicates that there was a previous refund for this order for the same amount within the last 60 seconds. This safeguard is to prevent duplicate refunds from happening.
REFUND_AMOUNT_GREATER_THAN_AVAILABLE - indicates that the provided refund amount is greater than the available funds to refund.
NO_ENTITY_FOUND - indicates that the order for the displayOrderId cannot be found.
UNAUTHORIZED - indicates an incorrect X-Instant-App-Auth header provided.
INVALID_CREDENTIALS - indicates an invalid X-Instant-App-Id header provided.
INTENRAL_SERVER_ERROR - indicates that the request failed due to an unexpected error. If this persists, please contact Instant support for assistance.