search
System Status

Refunds

The Refunds resource allows you to issue customers full or partial refunds on product costs, shipping expenses, taxes, duties, and fees. The API also allows you to refund the same charge multiple times. However, you cannot issue a refund greater than the combined amount of an order's charges.

hashtag
Creates a refund for an order.

post

Refunds all all or part of an order charge.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
orderIdstringOptional

The unique identifier of the order. You are required to provide this parameter or invoiceId.

Example: ord_5823594809
invoiceIdstringOptional

The unique identifier of the invoice. You are required to provide this parameter or orderId.

Example: 5823594809
currencystringRequired

Three-letter ISO currency code.

Example: USD
amountnumber · double · nullableOptional

The amount to refund. You are required to provide this value, percent, or items.

Example: 9.99
percentnumber · double · min: 0.01 · max: 100 · nullableOptional

The percent to refund. You are required to provide this value, amount, or items.

Example: 100
typestring · enumOptional

The type of the refund.

Example: shippingPossible values:
reasonstring · max: 64Optional

The reason for the refund.

Example: requested_by_customer
Responses
post
/refunds

hashtag
Returns a list of refunds

get

Get all refunds.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
endingBeforestringOptional

A cursor for use in pagination. The endingBefore parameter is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with xyz your subsequent calls can include endingBefore=xyz in order to fetch the previous page of the list.

startingAfterstringOptional

A cursor for use in pagination. The startingAfter parameter is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with xyz, your subsequent calls can include startingAfter=xyz in order to fetch the next page of the list.

limitinteger · min: 1 · max: 100Optional

A limit on the number of objects returned. Limit can range between 1 and 100, and the default is 10.

statestringOptional

Only return objects in the given state

idsstring[]Optional

Only return refunds with the given IDs

orderIdstringOptional

The order to retrieve refunds for.

skuIdstringOptional

The sku to retrieve refunds for.

reasonstringOptional

Retrieve refunds with this reason.

failureReasonstringOptional

Retrieve refunds that failed for this reason.

Responses
chevron-right
200

200 OK

application/json
hasMorebooleanOptional

Whether or not there are more elements available after this set. If false this set represents the end of the list.

Example: true
get
/refunds

hashtag
Gets a refund by ID.

get

Retrieves the details of a refund. Supply the unique identifier of the refund.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired

Refund ID

Responses
chevron-right
200

OK.

application/json
idstringRead-onlyOptional

The unique identifier of the refund.

Example: ref_5823594809
createdTimestring · date-timeRead-onlyOptional

Time at which the refund was created.

Example: {"offset":{"totalSeconds":0,"id":"Z","rules":{"fixedOffset":true,"transitions":[],"transitionRules":[]}},"nano":0,"year":2018,"monthValue":4,"dayOfMonth":25,"hour":20,"minute":36,"second":0,"dayOfWeek":"WEDNESDAY","dayOfYear":115,"month":"APRIL"}
orderIdstringRead-onlyOptional

The unique identifier of the order.

Example: ord_6645940010
invoiceIdstringRead-onlyOptional

The unique identifier of the invoice.

Example: 5823594809
currencystringOptional

Three-letter ISO currency code.

Example: USD
typestring · enumOptional

The type of refund.

Example: shippingPossible values:
amountnumber · doubleRead-onlyOptional

The requested refund amount.

Example: 9.99
refundedAmountnumber · doubleRead-onlyOptional

The total amount refunded.

Example: 9.99
reasonstring · max: 64Optional

The reason for the refund.

Example: requested_by_customer
failureReasonstringOptional

The reason for the refund failure, if known.

Example: expired_or_canceled_card
statestring · enumOptional

The state of the refund.

Example: createdPossible values:
expiresTimestring · date-timeRead-onlyOptional

Time at which the information token expires.

Example: {"offset":{"totalSeconds":0,"id":"Z","rules":{"fixedOffset":true,"transitions":[],"transitionRules":[]}},"nano":0,"year":2019,"monthValue":12,"dayOfMonth":25,"hour":20,"minute":36,"second":0,"dayOfWeek":"WEDNESDAY","dayOfYear":359,"month":"DECEMBER"}
liveModebooleanOptional

Has the value true if the object exists in live mode or the value false if the object exists in test mode.

Example: false
get
/refunds/{id}

hashtag
Updates a refund for an order or a specific order charge.

post

Updates the specified refund by setting the values of the parameters passed. Any parameters not provided will be left unchanged. This request only accepts metadata as an argument.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired

Refund ID

Body
Responses
chevron-right
200

200 OK

application/json
idstringRead-onlyOptional

The unique identifier of the refund.

Example: ref_5823594809
createdTimestring · date-timeRead-onlyOptional

Time at which the refund was created.

Example: {"offset":{"totalSeconds":0,"id":"Z","rules":{"fixedOffset":true,"transitions":[],"transitionRules":[]}},"nano":0,"year":2018,"monthValue":4,"dayOfMonth":25,"hour":20,"minute":36,"second":0,"dayOfWeek":"WEDNESDAY","dayOfYear":115,"month":"APRIL"}
orderIdstringRead-onlyOptional

The unique identifier of the order.

Example: ord_6645940010
invoiceIdstringRead-onlyOptional

The unique identifier of the invoice.

Example: 5823594809
currencystringOptional

Three-letter ISO currency code.

Example: USD
typestring · enumOptional

The type of refund.

Example: shippingPossible values:
amountnumber · doubleRead-onlyOptional

The requested refund amount.

Example: 9.99
refundedAmountnumber · doubleRead-onlyOptional

The total amount refunded.

Example: 9.99
reasonstring · max: 64Optional

The reason for the refund.

Example: requested_by_customer
failureReasonstringOptional

The reason for the refund failure, if known.

Example: expired_or_canceled_card
statestring · enumOptional

The state of the refund.

Example: createdPossible values:
expiresTimestring · date-timeRead-onlyOptional

Time at which the information token expires.

Example: {"offset":{"totalSeconds":0,"id":"Z","rules":{"fixedOffset":true,"transitions":[],"transitionRules":[]}},"nano":0,"year":2019,"monthValue":12,"dayOfMonth":25,"hour":20,"minute":36,"second":0,"dayOfWeek":"WEDNESDAY","dayOfYear":359,"month":"DECEMBER"}
liveModebooleanOptional

Has the value true if the object exists in live mode or the value false if the object exists in test mode.

Example: false
post
/refunds/{id}
PreviousPayoutsNextReservations

Last updated