Refund & Cancel Orders (Item Level)


When to Use & Other Considerations

  • Buyer wants to cancel or return one or more items (but not all items) in an order.
  • Seller needs to refund some or all of an item or items.
  • Seller needs to refund some or all of the costs associated with an item or items.
  • Seller needs to cancel an item or items in an order because the item is out of stock or backordered.
  • Seller needs to cancel or refund an item or items in order because the item could not be delivered to the buyer.
  • For US and Canadian eBay Sellers:
    • If an eBay account is enabled for Premium Tax, submit cancel/refund adjustments are required  at the item level.
    • If an eBay account is NOT enabled for Premium Tax, submit cancel/refund adjustments are required at the order level.
  • For non-US eBay Sellers: submit cancel/refund adjustments at the item level.
  • Partial quantity refund/cancel = refunding part of the quantity of an order, but a full amount of the unit cost x quantity + appropriate tax, shipping, and shipping tax (each x quantity).
    • Some marketplaces will allow a partial quantity Item Level refund/cancel (but not Order Level, as quantity is not defined at the order level).
    • Note: any attempt to refund anything less than the order total (for Order Level requests) or item total (for Item Level requests), is considered a partial price refund/cancel.
    • Item Level Behavior for Partial Quantity Cancellations: if "Quantity" is less than the total original item quantity on an Item Level adjustment in a pre-shipment scenario (cancellation), it will be honored ONLY IF the marketplace supports Partial Quantity Cancellations.The total item value (including item price + appropriate taxes, shipping associated with the product, shipping taxes, gift prices and taxes), multiplied by the "Quantity" provided, will be returned to the buyer.
    • Item Level Behavior for Partial Quantity Refunds: the item(s) must be shipped, and a Partial Item Level Refund request needs to be executed with the "Quantity" defined in the request. It will be honored ONLY IF the marketplace supports Partial Quantity Refunds.The total item value (including item price + appropriate taxes, shipping associated with the product, shipping taxes, gift prices and taxes), multiplied by the "Quantity" provided, will be returned to the buyer.
  • Partial price refund/cancel = refunding part of the price of an order, but not the full amount of the unit or order (ie: withholding shipping costs)
    • No marketplace allows for Order Level or Item Level partial price cancellations.
    • Item Level Behavior for Partial Price Cancellations: if "ItemAdjustment" (or any other item-level adjustment fields) is less than the total original item value on an Item Level adjustment in a pre-shipment scenario (cancellation), it will be ignored by ChannelAdvisor and the entire item amount (total item value including taxes, shipping associated with the product, shipping taxes, gift prices and taxes) will be returned to the buyer.
    • Item Level Behavior for Partial Price Refunds: the item(s) must be shipped, and a Partial Item Level Refund request needs to be executed. The value(s) passed in the "ItemAdjustment" (and other "Adjustment" properties) fields will be honored if the marketplace allows for Item Level Refunds.

Item Level Refund & Cancel Endpoint

POST https://api.channeladvisor.com/v1/OrderItems(OrderItemID)/Adjust

Important and/or Required Parameters

Property
Type Required Description
OrderItemID  integer (32 bit) Required Include in URL. The ChannelAdvisor generated unique identifier for the OrderItem.
Quantity integer (32 bit) Optional Include in body. The number of units being refunded or cancelled. Cannot be more than the total in the original order.
Restock boolean Optional Include in body. Indicates the adjusted quantity should be added back to available quantity.
Defaults to 'false' if property is not provided.
Reason enum Optional Include in body. Indicates why the adjustment was requested.
Defaults to "GeneralAdjustment" if property is not provided.
PreventSiteProcessing boolean Optional Include in body. Indicates if the adjustment will be sent to the marketplace.
Default value is 'false' when not provided in the request.
When 'true' is sent, information is logged in ChannelAdvisor only and not shared with the marketplace.
ItemAdjustment decimal Conditional

Include in body. The amount returned from item costs (not Unit Cost). Required if other item price properties are provided in a post-shipment refund.
Value cannot exceed total item cost in the original order unless marketplace allows over-refunding.

TaxAdjustment decimal Optional Include in body. The amount returned from item tax costs. Assumed as zero dollars if ItemAdjustment is provided in post-shipment refund.
Value cannot exceed total item cost in the original order.
ShippingAdjustment decimal Optional Include in body. The amount returned from shipping costs. Assumed as zero dollars if ItemAdjustment is provided in post-shipment refund.
Value cannot exceed total item cost in the original order.
ShippingTaxAdjustment decimal Optional Include in body. The amount returned from shipping tax costs. Assumed as zero dollars if ItemAdjustment is provided in post-shipment refund.
Value cannot exceed total item cost in the original order.
GiftWrapAdjustment decimal Optional Include in body. The amount returned from gift wrap costs. Assumed as zero dollars if ItemAdjustment is provided in post-shipment refund.
Value cannot exceed total item cost in the original order.
GiftWrapTaxAdjustment decimal Optional Include in body. The amount returned from gift wrap tax costs. Assumed as zero dollars if ItemAdjustment is provided in post-shipment refund.
Value cannot exceed total item cost in the original order.
RecyclingFeeAdjustment decimal Optional Include in body. The amount returned from recycling and waste fees. Assumed as zero dollars if ItemAdjustment is provided in post-shipment refund.
Value cannot exceed total item cost in the original order.
SellerAdjustmentID string (50) Optional Include in body. Identifier provided by the seller.
ForceCalculateOmittedAmounts boolean Optional Include in body. For refunds only. When true, any amount fields omitted or null in the request will be replaced by the calculated balance available, based on the quantity being refunded. When false, default behavior is maintained, meaning that calculated remaining balances will only be applied if ALL amount fields are omitted or null, but if any amounts are specified then omitted or null fields will default to zero.

Item Level Refund & Cancel Math Calculations

Property
Regular Mathematical Calculations
When TaxType = NoTax, Standard, ExclusiveVat
* not a real field; used for explanation purposes only

Mathematical Calculations
When TaxType = InclusiveVat 
* not a real field; used for explanation purposes only 

Quantity  Number of units to be refunded.
ItemAdjustment UnitPrice x (Item)Quantity to be refunded
(rounded down until final item is refunded - where remaining total is sent)
Note: do not only send unit price in this property.
UnitPrice(include UnitVAT*) x (Item)Quantity to be refunded
(rounded down until final item is refunded - where remaining total is sent)
Note: do not only send unit price in this property. 
TaxAdjustment

Sum of all item taxes to be refunded
Calculating by Unit:
TaxPrice / (Item)Quantity = UnitTax*
UnitTax* x (Item)Quantity for refund = Total TaxAdjustment
(rounded down until final item is refunded - where whatever is left is sent)

Not applicable since VAT needs to be included in ItemAdjustment.
ShippingAdjustment

Sum of all shipping costs to be refunded
Calculating by Unit:
ShippingPrice / (Item)Quantity = UnitShippingPrice*
UnitShippingPrice* x (Item)Quantity for refund = Total ShippingAdjustment

(rounded down until final item is refunded - where whatever is left is sent)

Sum of all shipping costs to be refunded (including Shipping VAT)
Calculating by Unit:
(ShippingPrice + ShippingVAT*) / (Item)Quantity = UnitShippingPricewVAT*
UnitShippingPricewVAT* x (Item)Quantity for refund = Total ShippingAdjustment
(rounded down until final item is refunded - where whatever is left is sent)

ShippingTaxAdjustment Sum of all shipping tax costs to be refunded
Calculating by Unit:
ShippingTaxPrice / (Item)Quantity = UnitShippingTaxPrice*
UnitShippingTaxPrice* x (Item)Quantity for refund = Total ShippingTaxAdjustment
(rounded down until final item is refunded - where whatever is left is sent)

Not applicable since VAT needs to be included in ShippingAdjustment.

RecyclingFeeAdjustment Sum of all recycling fees to be refunded
(rounded down until final item is refunded - where whatever is left is sent) 

GiftWrapAdjustment Sum of all gift wrap costs to be refunded
Calculating by Unit:
GiftPrice / (Item)Quantity = UnitGiftPrice*
UnitGiftPrice* x (Item)Quantity for refund = Total GiftWrapAdjustment
(rounded down until final item is refunded - where whatever is left is sent)
Sum of all gift wrap costs to be refunded (including Gift Wrap VAT)
(GiftPrice + GiftVAT*) / (Item)Quantity = UnitGiftPricewVAT*
UnitGiftPricewVAT* x (Item)Quantity for refund = Total GiftWrapAdjustment
(rounded down until final item is refunded - where whatever is left is sent)  
GiftWrapTaxAdjustment Sum of all gift wrap tax costs to be refunded
Calculating by Unit:
GiftTaxPrice / (Item)Quantity = UnitGiftTaxPrice*
UnitGiftTaxPrice* x (Item)Quantity for refund = Total GiftWrapTaxAdjustment
(rounded down until final item is refunded - where whatever is left is sent)
Not applicable since VAT needs to be included in GiftWrapAdjustment.

Important Behaviors About Item Level Cancellations

  • The REST API views any refund on an item prior to being shipped as a cancellation.
  • Any dollar amounts provided are always ignored - the API will cancel as many quantity as are specified in the request or all quantity if no quantity is defined.
    • If a partial quantity cancel is requested (e.g. total order was for Qty 3, and an adjustment request with Qty 1 is placed) along with values that are the total of an item, or partial totals from ItemAdjustment, TaxAdjustment, ShippingAdjustment, ShippingTaxAdjustment, ChannelAdvisor will use the quantity provided to execute the math to refund 1 * the original item cost, 1/3 of the total tax, 1/3 of the total shipping, and 1/3 of the total shipping tax AND ignore any values sent for ItemAdjustment, TaxAdjustment, ShippingAdjustment, ShippingTaxAdjustment.
      • This is done because no marketplace allows partial price cancellations.
  • A request with no quantity or pricing defined will cancel and refund 100% of the costs on the item defined in the request.
  • If "ItemAdjustment" is sent for only part of the price in a pre-shipment scenario (ie: a cancellation), it will be ignored within the request and the entire item amount (with appropriate ratio of item and shipping costs executed by ChannelAdvisor using the quantity being refunded).
  • A common misconception about cancellations is that cancelling part of the quantity of an item and retaining shipping costs is considered a Partial Quantity Cancellation.
    • Marketplaces view all of the costs on an item - including shipping, gift wrap, etc - part of the item. Therefore the marketplaces expect an appropriate ratio of shipping and gift wrap costs to be refunded and do not allow retention of any of those costs. When sending a cancellation to refund full item-related costs, but withhold shipping, gift wrap, etc, it is considered a Partial Price Cancellation.
      • No marketplace allows Partial Price Cancellations.

Important Behaviors About Item Level Refunds

  • The REST API views any adjustment on an item after it is shipped as a refund.
  • If Quantity is the only value sent on a Refund, ChannelAdvisor will execute those refunds based on the math described above. This will prevent attempts to over-refund.
    • If partial quantity is submitted with no amount fields (ItemAdjustment, TaxAdjustment, ShippingAdjustment, ShippingTaxAdjustment, GiftWrapAdjustment, etc), ChannelAdvisor will use the quantity provided to calculate and refund the appropriate portion of the remaining un-refunded item cost, tax, shipping, et cetera.
    • Submitting the ForceCalculateOmittedAmounts property as true will force ChannelAdvisor to replace any omitted or null amount fields with the appropriate portion of the remaining balance, based on quantity submitted.
  • If Price amounts are sent and no Quantity is defined on a refund, the dollar amounts provided are sent to the marketplace. We recommend executing the math as noted above to avoid over-refunding.
  • If Quantity and Price are provided on a refund, the quantity is logged, but the dollar amounts are honored at face value (unless attempting to purposely over-refund and the marketplace doesn't allow it).
    • If  a partial quantity refund is sent (e.g. total order was for Qty 3, send the adjustment request with Qty 1) along with values that are the total of an item, or partial totals from ItemAdjustment, TaxAdjustment, ShippingAdjustment, ShippingTaxAdjustment, ChannelAdvisor will NOT do the math on the order and will apply the values sent as the refund.
  • A request with no quantity or pricing defined will refund 100% of the costs on the item.
  • Any request to refund anything outside the Item costs requires "ItemAdjustment" be included with a value of '0' to successfully execute.
    • For example, to refund shipping costs as a courtesy, but not complete a full refund on the item - "ItemAdjustment": 0 is required

Item Level Refund & Cancel Request Examples