Skip to main content
API docs by Redocly

Refund API (order level, deprecated) (0.1.0)

Download OpenAPI specification:Download

team-order-management: team-order-management@newstore.com

Represents a refund request, triggered by a return or appeasement. Although a refund request is bound to an order, it need not contain order items or shipping information. For example, money that your business offers voluntarily to appease a customer when their previous order was delivered late, is not tied to an item or to a shipping rate.

A refund request can be pending, successful, or failed. A successful refund request may depend on the captured amount and on previous refunds (pending and successful).

Related resources:

List refund requests

Retrieves the refund request identifiers of the specified order as a list ordered by ascending creation dates. The list is empty when no refunds have been requested for this order.

Use the Get refund request details method to get more information about each refund request.

Authorizations:
newStoreAccessToken
path Parameters
id
required
string

The identifier of the order. To retrieve the order ID, use the List orders method.

Responses

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

Create refund request

Creates a refund request to initiate a refund. This call is asynchronous. A successful response means that the refund request was accepted and will be executed after there are enough captured funds. To import a historical refund from other applications into NewStore set is_historical to true in the request.

Note: When the refund request is successful, an email is sent to the customer if you provided their email address. No email is sent for historical refund requests.

Important: When creating the refund request, ensure that you specify the value of the amount property correctly, according to the specified currency. For example, if the currency is specified as USD and the product price (amount) has more than 2 decimal places, it is considered as invalid by the platform.

For more information, see pricing dependencies on currency.

Authorizations:
newStoreAccessToken
path Parameters
id
required
string

The identifier of the order. To retrieve the order ID, use the List orders method.

Request Body schema: application/json
return_id
string = 36 characters

Identifier for the corresponding return if any.

amount
required
number >= 0

The monetary amount requested to refund.

value
number >= 0

The percentage of the refund if the type is percentage or the monetary amount if it's fixed.

return_fee
number >= 0

If provided, this return fee will be deducted from the overall refund amount to be issued back to the customer. The decimal places should conform to the currency standards.

type
string
Enum: "percentage" "fixed"

The type of the refund it's either percentage or fixed.

currency
required
string = 3 characters

The currency this refund was issued in.

reason_code
integer

The corresponding code for the return reason.

reason
string

The reason why this refund was requested.

note
string

Additional note for the refund reason.

email
string <email>

Customer Email address to which a refund note will be sent in case of success. Email is not sent for historical refund requests.

requested_at
string <date-time>

The time when the refund was requested.

Array of objects <= 100 items

Additional information about the refund request passed as metadata, without any processing logic associated with it in NewStore. For example, the payment provider for the refund.

is_historical
boolean

Set to true if the refund request was imported from an external system and was already processed and the money was refunded.

Responses

Request samples

Content type
application/json
Example
{
  • "amount": 15,
  • "currency": "USD",
  • "reason_code": 2,
  • "reason": "Item is damaged",
  • "note": "The white shirt has yellow stains on it",
  • "email": "johndoe@example.com",
  • "is_historical": false
}

Response samples

Content type
application/json
{
  • "id": "192bb646-fff2-4a2f-bbb5-afcd5c491cc9"
}

Get refund request

Retrieves the refund request details of the provided refund request identifier, for the specified order.

Authorizations:
newStoreAccessToken
path Parameters
refund_id
required
string

The identifier of the refund.

id
required
string

The identifier of the order.

Responses

Response samples

Content type
application/json
{
  • "refund": {
    }
}

Calculate refund amount

Calculates the total refund amount for the order that will be applied when creating a refund request. The amount is rounded according to the currency the customer used to pay the order.

Authorizations:
newStoreAccessToken
path Parameters
id
required
string

The identifier of the order. To retrieve the order ID, use the List orders method.

Request Body schema: application/json
value
required
number

The percentage value that should be applied as a refund, e.g. 50.0 means a 50% refund will be applied.

currency
required
string = 3 characters

The currency this refund was issued in.

refundable_amount
required
number

The order total on which refund can be applied. It is the remaining order total after subtracting from it existing refunds, cancellations and gift wrapping charges.

Responses

Request samples

Content type
application/json
{
  • "value": 50,
  • "currency": "USD",
  • "refundable_amount": 300
}

Response samples

Content type
application/json
{
  • "refund": {
    }
}