Skip to main content

Integration with Exchanges V2 (Better Exchanges)

Anchor to PurposePurpose

Shopify added a new field on the Order object in the 2023-07 version of the GraphQL API, which requires authorized access. This field gives merchant systems, such as Enterprise Resource Planning (ERP), access to the data they need to identify and model exchanges V2 data.

The new exchangeV2s field is available on the Order object through the order and order list queries. Only clients with authorized access will have visibility to the data. This document provides details on how to request access for your client and how to integrate with the exchangeV2s field.

Type of Merchant ERP IntegrationClientWho requests access to the exchangeV2s field?Who to reach out to?
Uses ERP native connectorERPERPShopify Product Partnerships
Uses 3rd Party ERP connector3rd Party3rd PartyShopify Product Partnerships or Support Team
Uses custom in house connectorMerchantMerchantMSM or Support Team
Note

This access authorized field is a temporary solution as Shopify builds the future of exchange functionality and APIs. This data is only available on Shopify’s GraphQL Admin API.

Anchor to Requesting AccessRequesting Access

Clients need to request access to the exchangeV2s field. Refer to above table for Shopify point of contact regarding access.

The client will receive a "Field 'exchangeV2s' doesn't exist on type 'Order'" or an “Access denied for exchangeV2s field” error message if access has not been requested or has been requested and access is pending.

Anchor to What data is available in the exchangeV2s field?What data is available in the exchangeV2s field?

The exchangeV2s field returns a paginated list of ExchangeV2Connection objects using the filters provided. You can follow the return object to see more details on each level.

Order {
id
transactions
…
exchangeV2s(
first: Int Returns up to the first n elements from the list.
after: String Returns the elements that come after the specified cursor.
last: Int Returns up to the last n elements from the list.
before: String Returns the elements that come before the specified cursor.
reverse: Boolean = false Reverse the order of the underlying list. Order by Completed_at
query: String Supported filter parameters:
- completed_at:
See the detailed search syntax for more information about using filters.
- include_mirrored_exchanges:
Controls whether exchanges that are mirrored from the Shopify admin are queryable through this API
): ExchangeV2Connection! A list of ExchangeV2s for the order.
…
}

Anchor to ExchangeV2s related GraphQL ObjectsExchangeV2s related GraphQL Objects

ExchangeV2Connection: An auto-generated type for paginating through multiple ExchangeV2s.

{
edges: [ExchangeV2Edge!]! A list of edges.
pageInfo: PageInfo! Information to aid in pagination.
nodes: [ExchangeV2!]! A list of the nodes contained in ExchangeV2Edge.
}

ExchangeV2Edge: An auto-generated type which holds one ExchangeV2 and a cursor during pagination.

{
cursor: String! A cursor for use in pagination.
node: ExchangeV2! The item at the end of ExchangeV2Edge.
}

ExchangeV2: An exchange where existing items on an order are returned and new items are added to the order.

{
additions: ExchangeV2Additions! The details of the new items in the exchange.
completedAt: DateTime The date and time when the exchange was completed.
createdAt: DateTime! The date and time when the exchange was created.
id: ID! A globally-unique identifier.
location: Location The location where the exchange happened.
note: String The text of an optional note that a shop owner can attach to the exchange.
refunds: [Refund!]! The refunds processed during the exchange.
returns: ExchangeV2Returns! The details of the returned items in the exchange.
staffMember: StaffMember The staff member associated with the exchange.
totalAmountProcessedSet: MoneyBag! The amount of money that was paid or refunded as part of the exchange.
totalPriceSet: MoneyBag! The difference in values of the items that were exchanged.
transactions: [OrderTransaction!]! The order transactions related to the exchange.
}

ExchangeV2Additions: New items associated to the exchange.

{
lineItems: [ExchangeV2LineItem!]! The list of new items for the exchange.
subtotalPriceSet: MoneyBag! The subtotal of the items being added, including discounts.
taxLines: [TaxLine!]! The summary of all taxes of the items being added.
totalPriceSet: MoneyBag! The total price of the items being added, including discounts and taxes.
}

ExchangeV2Returns: Return items associated to the exchange.

{
lineItems: [ExchangeV2LineItem!]! The list of return items for the exchange.
orderDiscountAmountSet: MoneyBag! The amount of the order-level discount for the items and shipping being returned, which doesn't contain any line item discounts.
shippingRefundAmountSet: MoneyBag! The amount of money to be refunded for shipping.
subtotalPriceSet: MoneyBag! The subtotal of the items being returned.
taxLines: [TaxLine!]! The summary of all taxes of the items being returned.
tipRefundAmountSet: MoneyBag! The amount of money to be refunded for tip.
totalPriceSet: MoneyBag! The total value of the items being returned.
}

ExchangeV2LineItem: Contains information about an item in the exchange.

{
customAttributes: [Attribute!]! A list of attributes that represent custom features or special requests.
discountedTotalSet: MoneyBag! The total line price, in shop and presentment currencies, after discounts are applied.
discountedUnitPriceSet: MoneyBag! The price, in shop and presentment currencies, of a single variant unit after line item discounts are applied.
fulfillmentService: FulfillmentService Name of the service provider who fulfilled the order. Valid values are either **manual** or the name of the provider. For example, **amazon**, **shipwire**. Deleted fulfillment services will return null.
giftCard: Boolean! Indiciates if this line item is a gift card.
giftCards: [GiftCard!]! The gift cards associated with the line item.
name: String! The name of the product.
originalTotalSet: MoneyBag! The total price, in shop and presentment currencies, before discounts are applied.
originalUnitPriceSet: MoneyBag! The price, in shop and presentment currencies, of a single variant unit before line item discounts are applied.
quantity: Int! The number of products that were purchased.
requiresShipping: Boolean! Whether physical shipping is required for the variant.
sku: String The SKU number of the product variant.
taxLines: [TaxLine!]! The TaxLine object connected to this line item.
taxable: Boolean! Whether the variant is taxable.
title: String! The title of the product or variant. This field only applies to custom line items.
variant: ProductVariant The product variant of the line item.
variantTitle: String The name of the variant.
vendor: String The name of the vendor who created the product variant.
lineItem: LineItem The line item associated with this object.
}

Anchor to Real Time Support (Webhooks)Real Time Support (Webhooks)

Our API does not emit exchange specific webhooks throughout the processing of an exchange. There is no dedicated webhook emitted when an exchange starts or when it fully completes (i.e.when all the data is available). In that sense, our API does not offer real time support.

However, when an exchange is being processed, there will be multiple existing webhooks that are emitted. They are emitted to reflect the changes happening to the Order as part of the exchange. The following chart shows the emitted webhooks in the order in which they are enqueued. They are not guaranteed to be delivered in this order since the received order will vary depending on the traffic.

Exchange V2 OperationWebhook TriggeredData changes visible when querying the GraphQL API
Process Refund (*only for net-refundable + Interac refunds)refunds/createRefund transaction appears on the Order.
Payment (*only for net-payable refunds)checkouts/createNo changes observed.
Create ExchangeA new empty exchangeV2s connection appears on the Order. (Interac Refund and the transaction will also be visible under exchangeV2s.refunds and exchangeV2s.transactions).
Process Checkout (*only for net-payable refunds)orders/updatedPayment transaction shows up on the Order.transactions and exchangeV2s.transaction fields.
Process Refund (*only for net-refundable + non-Interac refunds)refunds/create, orders/updatedRefund transaction appears on Order.transactions and exchangeV2s.transactions.
Add New Itemsorders/edited, orders/updated, fulfillments/createNew items are available in Order.line_items and exchangeV2s.additions.
Remove Returned Itemsrefunds/create, orders/updatedNew refund and return objects appear on Order, calculated returns values also appear in exchangeV2s.returns.
Order Financial Status Updateorders/paid (if payable), orders/updatedUpdate order.finicial_status
Complete ExchangeExchangeV2 updates the completed_at timestamp.

As shown by the chart above, receiving an “orders/updated” does not indicate the completion of the exchange. This webhook is triggered by the in-between order update actions. The complete exchangeV2s data can only be guaranteed to be available when the exchange is marked as completed. To determine if the exchange is marked as completed, you can check that the completed_at field on exchangeV2s is not empty. If it is empty, it means the exchange is still in progress and the data under exchangeV2s is incomplete.

It is possible that fewer orders/updated webhooks than the ones shown in the chart above are received due to performance optimizations. However, at least one webhook for a topic will be sent out during the exchange process.

Was this page helpful?