Skip to main content
API docs by Redocly

Refund API (item level) (1.0.0)

Download OpenAPI specification:Download

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

Represents a refund request, triggered by a return or appeasement. It can be applied to all or specific items of an order. If needed, shipping costs can be refunded as well.

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 list of refund requests for the specified order 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.

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.

Note: In case of fixed type request the refund amount will be pro-rated across all specified items. Example: Request

Refund 50$ from items:

Item ID Price paid
Item 1 $50
Item 2 $75
Item 3 $25
Total $150

Response

Item ID Refunded amount Details
Item 1 $16.67 50 / (50 + 75 + 25) * 50 = 16.67
Item 2 $25 75 / (50 + 75 + 25) * 50 = 25
Item 3 $8.33 25 / (50 + 75 + 25) * 50 = 8.33
Total refund amount $50
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.

value
required
number >= 0

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

type
required
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.

required
Array of objects or objects non-empty

A list of product and/or shipping items that should be refunded.

Responses

Request samples

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

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 requested items (product or shipping) 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.

required
Array of objects or objects non-empty

A list of product and/or shipping items that should be refunded.

Responses

Request samples

Content type
application/json
{
  • "value": 50,
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "refund": {
    },
  • "items": [
    ]
}