Return event

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Return event webhook.

Return event

string<date-time>

Event time

order

Order · object

Order for return.

Show child attributes

order.customer

object

required

Show child attributes

order.customer.name

Name · object

required

Name of customer.

Show child attributes

order.customer.name.given

string

required

Given name

order.customer.name.surname

string

required

Surname

order.customer.emailAddress

string<email>

Email address of customer.

order.customer.phoneNumber

string

Phone number of customer.

order.discounts

Discounts · object

required

The total amount discounted on the order before returns. This includes both order and line level discounts.

Show child attributes

order.discounts.amount

string

order.discounts.currency

string

order.id

string

required

Order ID

Example:

"64e4da943dd822979a70bd12"

order.items

Line items · object[]

required

Show child attributes

order.items.fulfillmentLocationId

string | null

required

ID of the location where the item was be fulfilled.

Example:

"123"

order.items.id

string

required

Line item ID

order.items.price

Price · object

required

Currency amount

Show child attributes

order.items.price.amount

string

order.items.price.currency

string

order.items.product

Product · object

required

Product.

Show child attributes

order.items.product.name

string

required

Product title

order.items.product.externalId

string

Product ID in external system (e.g. shopify).

order.items.quantity

number

required

Item quantity.

Example:

1

order.items.variant

Variant · object

required

Show child attributes

order.items.variant.name

string

required

order.items.variant.externalId

string

order.items.variant.sku

string

order.items.variant.weight

Weight · object

Weight.

Show child attributes

order.items.variant.weight.kg

number

Weight in kilograms

Required range: x >= 0

order.items.externalId

string

Example:

"123"

order.lineItemsTotal

Line Items Total · object

required

Total price of all line items before discounts, shipping, and taxes.

Show child attributes

order.lineItemsTotal.amount

string

order.lineItemsTotal.currency

string

order.name

string

required

Shopify name.

order.shippingCost

Shipping Cost · object

required

The total shipping cost for the order. This includes fees and any related discounts that were refunded.

Show child attributes

order.shippingCost.amount

string

order.shippingCost.currency

string

order.taxes

Taxes · object

required

Total taxes applied to the order.

Show child attributes

order.taxes.amount

string

order.taxes.currency

string

order.total

Total · object

required

The total price of the order, before returns. This includes taxes, discounts, and shipping costs.

Show child attributes

order.total.amount

string

order.total.currency

string

order.externalId

string

Shopify ID

return

Return · object

Return.

Show child attributes

return.createdAt

string<date-time>

required

Time of creation.

return.destination

object

required

Show child attributes

return.destination.mailingAddress

Mailing address · object

Mailing address to send the returned items.

Show child attributes

return.destination.mailingAddress.city

string

required

City name

return.destination.mailingAddress.country

string

required

Country code

return.destination.mailingAddress.line1

string

required

Line 1

return.destination.mailingAddress.postalCode

string

required

Postal or ZIP code

return.destination.mailingAddress.state

string

required

State or province

return.destination.mailingAddress.line2

string

default:""

Line 2

return.destination.phoneNumber

string

Phone number of the destination.

return.giftCards

Gift cards · object[]

required

Gift card(s) created for return

Show child attributes

return.giftCards.amount

Amount · object

required

Currency amount

Show child attributes

return.giftCards.amount.amount

string

return.giftCards.amount.currency

string

return.giftCards.code

string

required

Gift card 16 digit code.

return.giftCards.externalId

string

required

Gift card ID.

return.id

string

required

Return identifier.

return.items

object[]

required

Return items

Show child attributes

return.items.id

string

required

Return item ID.

return.items.orderItem

Order item · object

required

Order line item

Show child attributes

return.items.orderItem.id

string

required

Line item reference ID in format: {orderId}/{lineItemIndex}

return.items.orderItem.line_item_id

string

Original Shopify line item ID

return.items.quantity

integer

required

Quantity of items being returned

return.items.reason

string

required

Primary return reason

return.items.assessments

object[]

Assessment records for this return item. Only applicable for warranties.

Show child attributes

return.items.assessments.assignedUser

object

required

User assigned to this assessment

Show child attributes

return.items.assessments.assignedUser.email

string

required

return.items.assessments.assignedUser.firstName

string

required

return.items.assessments.assignedUser.id

string

required

return.items.assessments.assignedUser.lastName

string

required

return.items.assessments.assignedUser.name

string

required

return.items.assessments.responses

required

Assessment responses

Show child attributes

return.items.assessments.responses.type

string

required

Allowed value: "short_text"

return.items.assessments.responses.value

string

required

Short text response value

return.items.customerComment

string

Customer's comment about the return

return.items.exchangeItem

Exchange item · object

Exchange item details if this return item is being exchanged

Show child attributes

return.items.exchangeItem.product

object

Show child attributes

return.items.exchangeItem.product.externalId

string

return.items.exchangeItem.product.name

string

return.items.exchangeItem.quantity

integer

return.items.exchangeItem.variant

object

Show child attributes

return.items.exchangeItem.variant.externalId

string

return.items.exchangeItem.variant.name

string

return.items.greenReturn

boolean

Whether this is a green return (no physical return required)

return.items.multipleChoiceQuestions

object[]

Multiple choice questions and answers for this return item

Show child attributes

return.items.multipleChoiceQuestions.answer

string

required

The selected answer

return.items.multipleChoiceQuestions.question

string

required

The question text

return.items.productAdjustment

string

Product adjustment details

return.items.productId

string

Product ID

return.items.reasonCode

string

Return reason code

return.items.reasonCodes

string[]

Array of return reason codes

return.items.reasons

string[]

Array of return reasons

return.items.refund

object

Refund details

Show child attributes

return.items.refund.amount

Amount · object

required

Currency amount

Show child attributes

return.items.refund.amount.amount

string

return.items.refund.amount.currency

string

return.items.refund.type

string

Refund strategy

return.items.sku

string

Product SKU

return.items.status

string

Return item status

return.items.variantId

string

Product variant ID

return.order

Order · object

required

Original order.

Show child attributes

return.order.id

string

required

Order ID.

Example:

"abc123"

return.source

object

required

Show child attributes

return.source.emailAddress

string<email>

required

Email address.

return.source.mailingAddress

Mailing address · object

required

Mailing address returned items are sent from.

Show child attributes

return.source.mailingAddress.city

string

required

City name

return.source.mailingAddress.country

string

required

Country code

return.source.mailingAddress.line1

string

required

Line 1

return.source.mailingAddress.postalCode

string

required

Postal or ZIP code

return.source.mailingAddress.state

string

required

State or province

return.source.mailingAddress.line2

string

default:""

Line 2

return.source.name

Name · object

required

Name of returner.

Show child attributes

return.source.name.given

string

required

Given name

return.source.name.surname

string

required

Surname

return.source.phoneNumber

string

required

Phone number of returner.

return.status

enum<string>

required

Return status.

Available options:

open,

in_transit,

delivered,

needs_review,

in_review,

complete,

rejected,

flagged,

pre_shipment,

deleted

Example:

"open"

return.updatedAt

string<date-time>

required

Time of last update.

return.compensationMethods

enum<string>[]

Array of compensation methods available for this return

Available options:

refund,

store_credit,

exchange

return.exchange

Exchange · object

Exchange order

Show child attributes

return.exchange.items

Line items · object[]

required

Show child attributes

return.exchange.items.id

string

required

return.exchange.items.quantity

number

required

Item quantity.

Example:

1

return.exchange.items.variant

Product variant · object

required

Show child attributes

return.exchange.items.variant.name

string

required

return.exchange.items.variant.externalId

string

return.exchange.items.variant.sku

string

return.exchange.items.variant.weight

Weight · object

Weight.

Show child attributes

return.exchange.items.variant.weight.kg

number

Weight in kilograms

Required range: x >= 0

return.exchange.items.originalPrice

object

Original price for the exchange item without discounts and taxes

Show child attributes

return.exchange.items.originalPrice.amount

string

return.exchange.items.originalPrice.currency

string

return.exchange.items.price

object

Subtotal price for the exchange item including discounts

Show child attributes

return.exchange.items.price.amount

string

return.exchange.items.price.currency

string

return.exchange.items.price.tax

string

return.exchange.items.product

Product · object

Product.

Show child attributes

return.exchange.items.product.name

string

required

Product title

return.exchange.items.product.externalId

string

Product ID in external system (e.g. shopify).

return.exchange.provision

enum<string>

required

Available options:

instant,

deferred

Example:

"deferred"

return.exchange.itemCount

integer

Total quantity of all exchange items

return.exchange.order

object

Show child attributes

return.exchange.order.externalId

string

ID of external order

return.exchange.totalTax

object

Total tax for exchange items

Show child attributes

return.exchange.totalTax.amount

string

return.exchange.totalTax.currency

string

return.externalOrderIds

string[]

Array of external order IDs associated with this return

return.internalCreatedByName

string

Name of the internal team member who created this return

return.notes

Notes · object[]

Teammembers generated notes and comments on the return

Show child attributes

return.notes.message

string

required

The note text

return.notes.image

string

Optional image URL attached to the note

return.shipment

Shipment · object

Shipment, if has been made

Show child attributes

return.shipment.carrier

string

Carrier code

return.shipment.postageLabel

string

Postage label URL

return.shipment.status

enum<string>

Status of shipment

Available options:

unknown,

pre_transit,

in_transit,

out_for_delivery,

available_for_pickup,

cancelled,

delivered,

error,

failure,

return_to_sender,

expired

return.shipment.tracker

string

Tracking number

return.shipment.trackingUrl

string

Tracking URL

return.shipments

Return Shipment · object[]

Array of all shipments associated with this return

Show child attributes

return.shipments.carrier

string

Carrier code

return.shipments.postageLabel

string

Postage label URL

return.shipments.status

enum<string>

Status of shipment

Available options:

unknown,

pre_transit,

in_transit,

out_for_delivery,

available_for_pickup,

cancelled,

delivered,

error,

failure,

return_to_sender,

expired

return.shipments.tracker

string

Tracking number

return.shipments.trackingUrl

string

Tracking URL

return.shopifyOrderIds

string[]

Array of Shopify order IDs (deprecated, use externalOrderIds)

return.totals

Totals · object

Calculated totals for the return

Show child attributes

return.totals.charge

object

required

The upsell amount for the exchange order

Show child attributes

return.totals.charge.amount

Money · object

required

Currency amount

Show child attributes

return.totals.charge.amount.amount

string

return.totals.charge.amount.currency

string

return.totals.exchange

object

required

Total value of new items in exchange

Show child attributes

return.totals.exchange.amount

Money · object

required

Currency amount

Show child attributes

return.totals.exchange.amount.amount

string

return.totals.exchange.amount.currency

string

return.totals.refund

object

required

Total refund amount excluding shipping

Show child attributes

return.totals.refund.amount

Money · object

required

Currency amount

Show child attributes

return.totals.refund.amount.amount

string

return.totals.refund.amount.currency

string

return.totals.storeCredit

object

required

Total store credit amount

Show child attributes

return.totals.storeCredit.amount

Money · object

required

Currency amount

Show child attributes

return.totals.storeCredit.amount.amount

string

return.totals.storeCredit.amount.currency

string

return.type

enum<string>

Return type.

Available options:

claim,

return,

warranty

Example:

"return"

type

enum<string>

Event type

Available options:

backfill,

created,

updated

Response

Success. Return a 2xx status code to indicate success.

Getting Started

Endpoints

Return event

Authorizations

Body

Response