## Purpose

Shopify added a new field on the [Order object](/docs/api/admin-graphql/latest/objects/Order) in the [2023-07 version of the GraphQL API](/changelog/exchangev2s-field-is-available-behind-beta-flag-on-order-graphql), 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](/docs/api/admin-graphql/latest/objects/Order) through the [order](/docs/api/admin-graphql/latest/queries/order) and [order list](/docs/api/admin-graphql/latest/queries/orders) 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 Integration | Client | Who requests access to the exchangeV2s field? | Who to reach out to?         |
| -------------------------------- | ------ | --------------------------------------------- | ---------------------------- |
| Uses ERP native connector        | ERP    | ERP                                           | Shopify Product Partnerships |
| Uses 3rd Party ERP connector     | 3rd Party | 3rd Party | Shopify Product Partnerships or Support Team |
| Uses custom in house connector | Merchant | Merchant | MSM 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.

## Requesting 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.

## 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.

<p>
<div class="react-code-block" data-preset="basic">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar basic-codeblock"></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>


<script type="text/plain" data-language="graphql">
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.
  …
}
</script>

</div>
</p>


## ExchangeV2s related GraphQL Objects

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

<p>
<div class="react-code-block" data-preset="basic">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar basic-codeblock"></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>


<script type="text/plain" data-language="graphql">
{
  edges: [ExchangeV2Edge!]! A list of edges.
  pageInfo: PageInfo! Information to aid in pagination.
  nodes: [ExchangeV2!]! A list of the nodes contained in ExchangeV2Edge.
}
</script>

</div>
</p>


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

<p>
<div class="react-code-block" data-preset="basic">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar basic-codeblock"></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>


<script type="text/plain" data-language="graphql">
{
  cursor: String! A cursor for use in pagination.
  node: ExchangeV2! The item at the end of ExchangeV2Edge.
}
</script>

</div>
</p>


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

<p>
<div class="react-code-block" data-preset="basic">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar basic-codeblock"></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>


<script type="text/plain" data-language="graphql">
{
  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.
}
</script>

</div>
</p>


`ExchangeV2Additions`: New items associated to the exchange.

<p>
<div class="react-code-block" data-preset="basic">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar basic-codeblock"></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>


<script type="text/plain" data-language="graphql">
{
  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.
}
</script>

</div>
</p>


`ExchangeV2Returns`: Return items associated to the exchange.

<p>
<div class="react-code-block" data-preset="basic">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar basic-codeblock"></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>


<script type="text/plain" data-language="graphql">
{
  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.
}
</script>

</div>
</p>


`ExchangeV2LineItem`: Contains information about an item in the exchange.

<p>
<div class="react-code-block" data-preset="basic">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar basic-codeblock"></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>


<script type="text/plain" data-language="graphql">
{
  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.
}
</script>

</div>
</p>


## 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](/docs/api/admin-rest/unstable/resources/webhook#event-topics) 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 Operation | Webhook Triggered | Data changes visible when querying the GraphQL API |
| --------------------- | ----------------- | -------------------------------------------------- |
| Process Refund _(*only for net-refundable + Interac refunds)_ | refunds/create | Refund transaction appears on the [Order](/docs/api/admin-graphql/latest/objects/Order). |
| Payment _(*only for net-payable refunds)_ | checkouts/create | No changes observed. |
| Create Exchange |  | A new empty `exchangeV2s` connection appears on the [Order](/docs/api/admin-graphql/latest/objects/Order). (Interac Refund and the transaction will also be visible under `exchangeV2s.refunds` and `exchangeV2s.transactions`). |
| Process Checkout _(*only for net-payable refunds)_ | orders/updated | Payment transaction shows up on the `Order.transactions` and `exchangeV2s.transaction` fields. |
| Process Refund _(*only for net-refundable + non-Interac refunds)_ | refunds/create, orders/updated | Refund transaction appears on `Order.transactions` and `exchangeV2s.transactions`. |
| Add New Items | orders/edited, orders/updated, fulfillments/create | New items are available in `Order.line_items` and `exchangeV2s.additions`. |
| Remove Returned Items | refunds/create, orders/updated | New refund and return objects appear on [Order](/docs/api/admin-graphql/latest/objects/Order), calculated returns values also appear in `exchangeV2s.returns`. |
| Order Financial Status Update | orders/paid _(if payable)_, orders/updated | Update `order.finicial_status` |
| Complete Exchange |  | ExchangeV2 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.