---
title: "ERP integration playbook to sync returns"
slug: "erp-integration-playbook-to-sync-returns"
tags: ["integration", "api", "platform", "events", "ERP integration", "return", "refund", "event stream ", "developer", "newstore platform"]
updated: 2024-12-17T19:35:23Z
published: 2024-12-17T19:35:23Z
canonical: "docs.newstore.com/erp-integration-playbook-to-sync-returns"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newstore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ERP integration playbook to sync returns

NewStore allows you to create financial transactions in an ERP system and sync them with the NewStore platform for all returns.

This integration playbook helps you integrate an ERP system used in your business with the NewStore platform, to sync all returns made by customers. The integration is achieved via the [Event Stream](/v1/docs/receiving-real-time-data#event-stream).

For each return order placed in the NewStore platform, a cash refund transaction is created in the ERP, which includes:

- Returned items
- Refund details

## Process overview

The following sequence diagram represents a typical integration of returns made in the NewStore platform with an ERP:

![](https://cdn.document360.io/c2d22fcd-a44b-4e1e-bf3a-84f0ffba0dbe/Images/Documentation/ERP integration playbook to sync returns.svg?sv=2026-02-06&spr=https&st=2026-11-06T07%3A22%3A43Z&se=2026-11-06T08%3A22%3A43Z&sr=c&sp=r&sig=VBI0PdQOC0pG6mvQL5TPGscD6TwwcXPHCpZkUUgxohU%3D)

In this playbook:

1. NewStore sends the `return.processed` event when the return has been completed.
2. The integration fetches all necessary details via [GraphQL API](/v1/docs/graphql-api#graphql).
3. The integration creates the cash refund transaction in the ERP by calling the ERP's API.

## Exceptions

### ERP unavailable

The integrations returns a 500 error, and the [Event stream](https://docs.newstore.net/api/webhooks/stream_webhook_sink_hook) retries sending the macro event.

### Payment details unavailable

In some cases, it takes more than a few seconds until payment processing at the `PSP` has been completed and the payment details become available in the platform. The integration moves the event into an internal queue (for example, SQS) to reprocess later, and returns `200`.

## Sample GraphQL Query

Here is an example [GraphQL](/v1/docs/graphql-api#graphql) query to retrieve all the information required to create a cash refund transaction in the ERP.

```plaintext
query MyQuery {
  order(id: "012345Ab-CdEf-GhIj-KlMn-OpQrStUvWxYz", tenant: "dodici") {
    externalId
    placedAt
    demandLocationId
    currency
    isExchange
    isHistorical
    channel
    channelType
    shippingTax
    shippingTotal
    taxExempt
    taxStrategy
    taxTotal
    subtotal
    grandTotal
    discounts {
      edges {
        node {
          couponCode
        }
      }
    }
    paymentAccount {
      instruments {
        edges {
          node {
            paymentMethod
            paymentOrigin
            paymentProvider
            paymentAccountTransactions {
              edges {
                node {
                  amount
                  currency
                  transactionType
                }
              }
            }
          }
        }
      }
    }
    items {
      edges {
        node {
          productId
          quantity
          pricebookPrice
          itemDiscounts
          orderDiscounts
          tax
          shippingServiceLevel
          fulfillmentLocationId
        }
      }
    }
  }
}
```

## ERP integration example with NetSuite

For integrations with NetSuite as an ERP system for returns, see this [example](/v1/docs/erp-integration-example-with-netsuite-for-returns#erp-return-example).

**Related topics**

- [ERP integration playbook to sync in-store purchases](/v1/docs/erp-integration-playbook-to-sync-in-store-purchases#integ-erp-playbook-instore)
- [ERP integration playbook to sync endless-aisle orders](/v1/docs/erp-integration-playbook-to-sync-endless-aisle-orders#integ-erp-playbook-endless-aisle)
- [ERP integration playbook for synchronizing cancellations](/v1/docs/erp-integration-playbook-for-synchronizing-cancellations#integ-erp-playbook-cancellation)
- [ERP integration playbook to sync appeasement refunds](/v1/docs/erp-integration-playbook-to-sync-appeasement-refunds#integ-erp-playbook-appeasement)
- [ERP integration example with NetSuite for returns](/v1/docs/erp-integration-example-with-netsuite-for-returns#erp-return-example)
- [Integrating a payment service provider](/v1/docs/integrating-a-payment-service-provider#integ-psp)
- [GraphQL API](/v1/docs/graphql-api#graphql)