Skip to main content

Refund Synchronization

⚠️ Deprecated Endpoint

This endpoint is deprecated and will no longer be maintained. Compared to the previous version:

  • all previously collected information remains associated with the order
  • the use of Shopify webhooks is removed

For all new developments, use Orders > Import List, which introduces:

  • a more standard handling of order retrieval

👉 See the new documentation: Import List

Refunds are managed by Flowlyze through a Shopify Webhook.

The information regarding the refund includes:

  • the items refunded (RefundLineItems): details about returned items.
  • the shipping refunded (RefundShippingLines): information about refunded shipping costs.
  • the transactions executed (Transactions): data on payment transactions associated with the refund.
  • the associated order (Order).
  • the associated return (Return): return information, if present.
  • duties (Duties): any customs duties refunded.

The shop URL to which the refund belongs (Shop) is retrieved, the identifier of the order (OrderId), information about the associated return (Return) and all transactions (Transactions) that have been made on the order up to that point except the first, i.e. the one referring to the initial sale.

The Adapter adds a tag to the order to have the ability to monitor how many refunds have been exported (IPaaS Refunds Exported: #). In addition, it handles sending information to a NetSuite endpoint configured to receive refund data.

Destination configuration​

Configure a Shopify destination and associate it with the flow, in addition to the basic data flow configuration.

FieldValueNotes
Destination TypeShopify
Operation[DEPRECATED] - Refund sync to NetSuitePOST /egress/sync-refund-to-ns-api
GraphQL endpoint URLhttps://SHOPIFYURL.myshopify.com/Shopify Admin API GraphQL endpoint URL
Admin API access tokenshpat_CODICEALFANUMERICOOr Client ID (API key) + Client secret — see Authentication
Client ID (API key)YOUR_CLIENT_ID
Client secretYOUR_CLIENT_SECRET

NetSuite header​

Token-based credentials for sending refund data to NetSuite.

FieldValueNotes
NetSuite API URLhttps://ACCOUNT.suitetalk.api.netsuite.com/NetSuite REST or SOAP web services base URL
Consumer key**********Consumer key for NetSuite token-based authentication
Consumer secret**********NetSuite consumer secret
Token ID**********NetSuite OAuth token ID
Token secret**********NetSuite OAuth token secret
Account IDACCOUNT_IDNetSuite account or realm identifier

Deprecated — previous configuration (HTTP Adapter)​

Deprecated

Configuration via HTTP Adapter with Base Url, Resource Path, and x-api-key header in Settings Override is deprecated. Use the Shopify destination configuration described above. For new developments, prefer Import List.

In addition to the basic data flow configuration the following settings were required in the destination's Settings Override:

FieldValueNote
Base Urlhttps://adapter.flowlyze.ioadapter URL
Resource Path/api/adp/shopify/egress/sync-refund-to-ns-apiadapter path for the refund flow.
Headers :: x-api-key**********API key for endpoint interaction verification
Headers :: x-shopify-graphql-urlhttps://SHOPIFYURL.myshopify.com/Shopify shop URL to connect to
Headers :: x-shopify-access-tokenshpat_CODICEALFANUMERICOsecret of the custom app created for integration
Headers :: x-ns-api-urlNetSuite API URLNetSuite API URL to send refund-related data to.
Headers :: x-ns-consumer-keyConsumer KeyConsumer key value generated for NetSuite
Headers :: x-ns-consumer-secretConsumer SecretConsumer secret value generated for NetSuite
Headers :: x-ns-token-idAccess Token IdAccess token for NetSuite
Headers :: x-ns-token-secretToken SecretToken secret generated for NetSuite
Headers :: x-ns-account-idAccount IdThe account ID (Realm) for NetSuite
info

How to configure the Webhook on Shopify​

  1. Go to the Settings section in your Shopify admin panel.
  2. Select Notifications from the left menu.
  3. Select the Webhooks section.
  4. Click on Create Webhook.
  5. Choose the event for which you want to receive the notification (e.g. for this flow you need to select Refund create).
  6. Select the format (e.g. Json).
  7. Enter the URL where you will receive notifications (e.g. for this flow the Flowlyze flow URL).
  8. Select the API version 'Webhook API version' (e.g. 2024-10)

For more information, visit the official Shopify documentation for creating Webhooks.

Example of retrieved information​

{
  "Shop": "https://yourShopName.myshopify.com/",
  "OrderId": "gid://shopify/Order/6090290397491",
  "Refund": {
    "Id": "gid://shopify/Refund/973899563315",
    "CreatedAt": "2024-10-15T12:58:16+00:00",
    "UpdatedAt": "2024-10-15T12:58:16+00:00",
    "Duties": [],
    "LegacyResourceId": "973899563315",
    "Note": null,
    "RefundLineItems": {
      "Nodes": [
        {
          "Id": "gid://shopify/RefundLineItem/593618305331",
          "LineItem": {
            "RequiresShipping": true,
            "Taxable": true,
            "IsGiftCard": false,
            "Duties": [],
            "TaxLines": [],
            "Id": "gid://shopify/LineItem/15345811456307",
            "Sku": "ABC0015-Black",
            "Name": "ABC0015 Product - Black / One size",
            "Quantity": 1,
            "Title": "ABC0015 Product",
            "VariantTitle": "Black / One size",
            "Vendor": "Vendor",
            "TotalDiscountSet": {
              "ShopMoney": {
                "Amount": 0,
                "CurrencyCode": "EUR"
              },
              "PresentmentMoney": {
                "Amount": 0,
                "CurrencyCode": "EUR"
              }
            },
            "DiscountedUnitPriceAfterAllDiscountsSet": {
              "ShopMoney": {
                "Amount": 200,
                "CurrencyCode": "EUR"
              },
              "PresentmentMoney": {
                "Amount": 200,
                "CurrencyCode": "EUR"
              }
            },
            "DiscountedTotalSet": {
              "ShopMoney": {
                "Amount": 200,
                "CurrencyCode": "EUR"
              },
              "PresentmentMoney": {
                "Amount": 200,
                "CurrencyCode": "EUR"
              }
            },
            "OriginalTotalSet": {
              "ShopMoney": {
                "Amount": 200,
                "CurrencyCode": "EUR"
              },
              "PresentmentMoney": {
                "Amount": 200,
                "CurrencyCode": "EUR"
              }
            },
            "OriginalUnitPriceSet": {
              "ShopMoney": {
                "Amount": 200,
                "CurrencyCode": "EUR"
              },
              "PresentmentMoney": {
                "Amount": 200,
                "CurrencyCode": "EUR"
              }
            },
            "DiscountedUnitPriceSet": {
              "ShopMoney": {
                "Amount": 200,
                "CurrencyCode": "EUR"
              },
              "PresentmentMoney": {
                "Amount": 200,
                "CurrencyCode": "EUR"
              }
            },
            "Product": {
              "Id": "gid://shopify/Product/9320461205811"
            },
            "Variant": {
              "Id": "gid://shopify/ProductVariant/49481263350067",
              "SelectedOptions": [
                {
                  "Name": "color",
                  "Value": "Black"
                },
                {
                  "Name": "size",
                  "Value": "One size"
                }
              ],
              "Barcode": null,
              "Price": 200,
              "CompareAtPrice": 200
            },
            "DiscountAllocations": [],
            "CustomAttributes": []
          },
          "Location": {
            "Id": "gid://shopify/Location/99130769715"
          },
          "PriceSet": {
            "ShopMoney": {
              "Amount": 200,
              "CurrencyCode": "EUR"
            },
            "PresentmentMoney": {
              "Amount": 200,
              "CurrencyCode": "EUR"
            }
          },
          "Quantity": 1,
          "Restocked": true,
          "RestockType": "RETURN",
          "SubtotalSet": {
            "ShopMoney": {
              "Amount": 200,
              "CurrencyCode": "EUR"
            },
            "PresentmentMoney": {
              "Amount": 200,
              "CurrencyCode": "EUR"
            }
          },
          "TotalTaxSet": {
            "ShopMoney": {
              "Amount": 0,
              "CurrencyCode": "EUR"
            },
            "PresentmentMoney": {
              "Amount": 0,
              "CurrencyCode": "EUR"
            }
          }
        }
      ],
      "PageInfo": {
        "HasNextPage": false,
        "EndCursor": "eyJsYXN0X2lkIjo1OTM2MTgzMDUzMzEsImxhc3RfdmFsdWUiOjU5MzYxODMwNTMzMX0="
      }
    },
    "RefundShippingLines": {
      "Nodes": [],
      "PageInfo": {
        "HasNextPage": false,
        "EndCursor": null
      }
    },
    "TotalRefundedSet": {
      "ShopMoney": {
        "Amount": 200,
        "CurrencyCode": "EUR"
      },
      "PresentmentMoney": {
        "Amount": 200,
        "CurrencyCode": "EUR"
      }
    },
    "Transactions": {
      "Nodes": [
        {
          "AccountNumber": "•••• •••• •••• 1",
          "AuthorizationExpiresAt": null,
          "CreatedAt": "2024-10-15T12:58:16+00:00",
          "Fees": [],
          "FormattedGateway": "(For Testing) Bogus Gateway",
          "ManuallyCapturable": false,
          "MaximumRefundableV2": null,
          "MultiCapturable": true,
          "Order": {
            "Id": "gid://shopify/Order/6090290397491",
            "App": null,
            "CustomAttributes": null,
            "Metafield": null,
            "Tags": null
          },
          "PaymentDetails": {
            "Name": "Mario Rossi",
            "ExpirationMonth": 12,
            "ExpirationYear": 2025,
            "PaymentMethodName": "card",
            "Wallet": null,
            "AvsResultCode": null,
            "Bin": "1",
            "CvvResultCode": null,
            "Number": "•••• •••• •••• 1",
            "Company": "Bogus"
          },
          "PaymentId": "#1036.3",
          "SettlementCurrency": null,
          "SettlementCurrencyRate": null,
          "ShopifyPaymentsSet": null,
          "Test": true,
          "TotalUnsettledSet": {
            "ShopMoney": {
              "Amount": 0,
              "CurrencyCode": "EUR"
            },
            "PresentmentMoney": {
              "Amount": 0,
              "CurrencyCode": "EUR"
            }
          },
          "AmountSet": {
            "ShopMoney": {
              "Amount": 200,
              "CurrencyCode": "EUR"
            },
            "PresentmentMoney": {
              "Amount": 200,
              "CurrencyCode": "EUR"
            }
          },
          "AuthorizationCode": null,
          "ProcessedAt": "2024-10-15T12:58:16Z",
          "Status": "SUCCESS",
          "ErrorCode": null,
          "Gateway": "bogus",
          "Id": "gid://shopify/OrderTransaction/7354863714611",
          "Kind": "REFUND",
          "ReceiptJson": "{\"paid_amount\":\"200.00\"}",
          "ParentTransaction": {
            "Id": "gid://shopify/OrderTransaction/7354787004723",
            "AccountNumber": "•••• •••• •••• 1"
          }
        }
      ],
      "PageInfo": {
        "HasNextPage": false,
        "EndCursor": "eyJsYXN0X2lkIjo3MzU0ODYzNzE0NjExLCJsYXN0X3ZhbHVlIjo3MzU0ODYzNzE0NjExfQ=="
      }
    },
    "Order": {
      "Id": "gid://shopify/Order/6090290397491",
      "App": {
        "Name": "Online Store",
        "Id": "gid://shopify/App/580111"
      },
      "CustomAttributes": [
        {
          "Key": "orderSynced",
          "Value": "TRUE"
        }
      ],
      "Metafield": {
        "Id": "gid://shopify/Metafield/39108985159987",
        "Key": "listOfRefundProcessed",
        "Value": "[\"973899432243\"]",
        "Namespace": "refundProcessed"
      },
      "Tags": [
        "IPaaS Refunds Exported: 1"
      ]
    },
    "Return": {
      "Id": "gid://shopify/Return/5781946675",
      "Name": "#1036-R2",
      "Status": "CLOSED",
      "TotalQuantity": 1,
      "Decline": null
    },
    "OrderAdjustments": {
      "Nodes": [],
      "PageInfo": {
        "HasNextPage": false,
        "EndCursor": null
      }
    }
  },
  "Return": {
    "Id": "gid://shopify/Return/5781946675",
    "Name": "#1036-R2",
    "Status": "CLOSED",
    "TotalQuantity": 1,
    "Decline": null,
    "Order": {
      "Id": "gid://shopify/Order/6090290397491",
      "App": {
        "Name": "Online Store",
        "Id": "gid://shopify/App/580111"
      },
      "Metafield": null,
      "Tags": [
        "IPaaS Refunds Exported: 4"
      ]
    },
    "ReturnLineItems": {
      "Nodes": [
        {
          "Id": "gid://shopify/ReturnLineItem/10342203699",
          "Quantity": 1,
          "CustomerNote": null,
          "RefundableQuantity": 0,
          "RefundedQuantity": 1,
          "ReturnReason": "UNKNOWN",
          "ReturnReasonNote": "",
          "RestockingFee": null,
          "FulfillmentLineItem": {
            "Id": "gid://shopify/FulfillmentLineItem/13212864905523",
            "LineItem": {
              "RequiresShipping": true,
              "Taxable": true,
              "IsGiftCard": false,
              "Duties": [],
              "TaxLines": [],
              "Id": "gid://shopify/LineItem/15345811456307",
              "Sku": "ABC0015-Black",
              "Name": "ABC0015 Product - Black / One size",
              "Quantity": 1,
              "Title": "ABC0015 Product",
              "VariantTitle": "Black / One size",
              "Vendor": "Vendor",
              "TotalDiscountSet": {
                "ShopMoney": {
                  "Amount": 0,
                  "CurrencyCode": "EUR"
                },
                "PresentmentMoney": {
                  "Amount": 0,
                  "CurrencyCode": "EUR"
                }
              },
              "DiscountedUnitPriceAfterAllDiscountsSet": {
                "ShopMoney": {
                  "Amount": 200,
                  "CurrencyCode": "EUR"
                },
                "PresentmentMoney": {
                  "Amount": 200,
                  "CurrencyCode": "EUR"
                }
              },
              "DiscountedTotalSet": {
                "ShopMoney": {
                  "Amount": 200,
                  "CurrencyCode": "EUR"
                },
                "PresentmentMoney": {
                  "Amount": 200,
                  "CurrencyCode": "EUR"
                }
              },
              "OriginalTotalSet": {
                "ShopMoney": {
                  "Amount": 200,
                  "CurrencyCode": "EUR"
                },
                "PresentmentMoney": {
                  "Amount": 200,
                  "CurrencyCode": "EUR"
                }
              },
              "OriginalUnitPriceSet": {
                "ShopMoney": {
                  "Amount": 200,
                  "CurrencyCode": "EUR"
                },
                "PresentmentMoney": {
                  "Amount": 200,
                  "CurrencyCode": "EUR"
                }
              },
              "DiscountedUnitPriceSet": {
                "ShopMoney": {
                  "Amount": 200,
                  "CurrencyCode": "EUR"
                },
                "PresentmentMoney": {
                  "Amount": 200,
                  "CurrencyCode": "EUR"
                }
              },
              "Product": {
                "Id": "gid://shopify/Product/9320461205811"
              },
              "Variant": {
                "Id": "gid://shopify/ProductVariant/49481263350067",
                "SelectedOptions": [
                  {
                    "Name": "color",
                    "Value": "Black"
                  },
                  {
                    "Name": "size",
                    "Value": "One size"
                  }
                ],
                "Barcode": null,
                "Price": 200,
                "CompareAtPrice": 200
              },
              "DiscountAllocations": [],
              "CustomAttributes": []
            },
            "Quantity": 1,
            "OriginalTotalSet": {
              "ShopMoney": {
                "Amount": 200,
                "CurrencyCode": "EUR"
              },
              "PresentmentMoney": {
                "Amount": 200,
                "CurrencyCode": "EUR"
              }
            },
            "DiscountedTotalSet": {
              "ShopMoney": {
                "Amount": 200,
                "CurrencyCode": "EUR"
              },
              "PresentmentMoney": {
                "Amount": 200,
                "CurrencyCode": "EUR"
              }
            }
          }
        }
      ],
      "PageInfo": {
        "HasNextPage": false,
        "EndCursor": "eyJsYXN0X2lkIjoxMDM0MjIwMzY5OSwibGFzdF92YWx1ZSI6IjEwMzQyMjAzNjk5In0="
      }
    },
    "ExchangeLineItems": {
      "Nodes": [],
      "PageInfo": {
        "HasNextPage": false,
        "EndCursor": null
      }
    },
    "ReturnShippingFees": [],
    "ReverseFulfillmentOrders": {
      "Nodes": [
        {
          "Id": "gid://shopify/ReverseFulfillmentOrder/5489066291",
          "Status": "OPEN",
          "LineItems": {
            "Nodes": [
              {
                "Id": "gid://shopify/ReverseFulfillmentOrderLineItem/9709125939",
                "Dispositions": [
                  {
                    "Id": "gid://shopify/ReverseFulfillmentOrderDisposition/561447219",
                    "Location": {
                      "Id": "gid://shopify/Location/99130769715"
                    },
                    "Quantity": 1,
                    "Type": "RESTOCKED"
                  }
                ],
                "FulfillmentLineItem": {
                  "Id": "gid://shopify/FulfillmentLineItem/13212864905523",
                  "LineItem": {
                    "RequiresShipping": true,
                    "Taxable": true,
                    "IsGiftCard": false,
                    "Duties": [],
                    "TaxLines": [],
                    "Id": "gid://shopify/LineItem/15345811456307",
                    "Sku": "ABC0015-Black",
                    "Name": "ABC0015 Product - Black / One size",
                    "Quantity": 1,
                    "Title": "ABC0015 Product",
                    "VariantTitle": "Black / One size",
                    "Vendor": "Vendor",
                    "TotalDiscountSet": {
                      "ShopMoney": {
                        "Amount": 0,
                        "CurrencyCode": "EUR"
                      },
                      "PresentmentMoney": {
                        "Amount": 0,
                        "CurrencyCode": "EUR"
                      }
                    },
                    "DiscountedUnitPriceAfterAllDiscountsSet": {
                      "ShopMoney": {
                        "Amount": 200,
                        "CurrencyCode": "EUR"
                      },
                      "PresentmentMoney": {
                        "Amount": 200,
                        "CurrencyCode": "EUR"
                      }
                    },
                    "DiscountedTotalSet": {
                      "ShopMoney": {
                        "Amount": 200,
                        "CurrencyCode": "EUR"
                      },
                      "PresentmentMoney": {
                        "Amount": 200,
                        "CurrencyCode": "EUR"
                      }
                    },
                    "OriginalTotalSet": {
                      "ShopMoney": {
                        "Amount": 200,
                        "CurrencyCode": "EUR"
                      },
                      "PresentmentMoney": {
                        "Amount": 200,
                        "CurrencyCode": "EUR"
                      }
                    },
                    "OriginalUnitPriceSet": {
                      "ShopMoney": {
                        "Amount": 200,
                        "CurrencyCode": "EUR"
                      },
                      "PresentmentMoney": {
                        "Amount": 200,
                        "CurrencyCode": "EUR"
                      }
                    },
                    "DiscountedUnitPriceSet": {
                      "ShopMoney": {
                        "Amount": 200,
                        "CurrencyCode": "EUR"
                      },
                      "PresentmentMoney": {
                        "Amount": 200,
                        "CurrencyCode": "EUR"
                      }
                    },
                    "Product": {
                      "Id": "gid://shopify/Product/9320461205811"
                    },
                    "Variant": {
                      "Id": "gid://shopify/ProductVariant/49481263350067",
                      "SelectedOptions": [
                        {
                          "Name": "color",
                          "Value": "Black"
                        },
                        {
                          "Name": "size",
                          "Value": "One size"
                        }
                      ],
                      "Barcode": null,
                      "Price": 200,
                      "CompareAtPrice": 200
                    },
                    "DiscountAllocations": [],
                    "CustomAttributes": []
                  },
                  "Quantity": 1,
                  "OriginalTotalSet": {
                    "ShopMoney": {
                      "Amount": 200,
                      "CurrencyCode": "EUR"
                    },
                    "PresentmentMoney": {
                      "Amount": 200,
                      "CurrencyCode": "EUR"
                    }
                  },
                  "DiscountedTotalSet": {
                    "ShopMoney": {
                      "Amount": 200,
                      "CurrencyCode": "EUR"
                    },
                    "PresentmentMoney": {
                      "Amount": 200,
                      "CurrencyCode": "EUR"
                    }
                  }
                },
                "TotalQuantity": 1
              }
            ],
            "PageInfo": {
              "HasNextPage": false,
              "EndCursor": "eyJsYXN0X2lkIjo5NzA5MTI1OTM5LCJsYXN0X3ZhbHVlIjoiOTcwOTEyNTkzOSJ9"
            }
          },
          "ReverseDeliveries": {
            "Nodes": [],
            "PageInfo": {
              "HasNextPage": false,
              "EndCursor": null
            }
          },
          "ThirdPartyConfirmation": null
        }
      ],
      "PageInfo": {
        "HasNextPage": false,
        "EndCursor": "eyJsYXN0X2lkIjo1NDg5MDY2MjkxLCJsYXN0X3ZhbHVlIjoiNTQ4OTA2NjI5MSJ9"
      }
    }
  },
  "Transactions": [
    {
      "AmountSet": {
        "ShopMoney": {
          "Amount": 241,
          "CurrencyCode": "EUR"
        },
        "PresentmentMoney": {
          "Amount": 241,
          "CurrencyCode": "EUR"
        }
      },
      "AuthorizationCode": null,
      "ProcessedAt": "2024-10-15T12:56:53Z",
      "Status": "SUCCESS",
      "ErrorCode": null,
      "Gateway": "bogus",
      "Id": "gid://shopify/OrderTransaction/7354862534963",
      "Kind": "REFUND",
      "ReceiptJson": "{\"paid_amount\":\"241.00\"}",
      "ParentTransaction": {
        "Id": "gid://shopify/OrderTransaction/7354787004723",
        "AccountNumber": null
      },
      "PaymentDetails": {
        "AvsResultCode": null,
        "Bin": "1",
        "CvvResultCode": null,
        "Number": "•••• •••• •••• 1",
        "Company": "Bogus"
      }
    },
    {
      "AmountSet": {
        "ShopMoney": {
          "Amount": 200,
          "CurrencyCode": "EUR"
        },
        "PresentmentMoney": {
          "Amount": 200,
          "CurrencyCode": "EUR"
        }
      },
      "AuthorizationCode": null,
      "ProcessedAt": "2024-10-15T12:58:16Z",
      "Status": "SUCCESS",
      "ErrorCode": null,
      "Gateway": "bogus",
      "Id": "gid://shopify/OrderTransaction/7354863714611",
      "Kind": "REFUND",
      "ReceiptJson": "{\"paid_amount\":\"200.00\"}",
      "ParentTransaction": {
        "Id": "gid://shopify/OrderTransaction/7354787004723",
        "AccountNumber": null
      },
      "PaymentDetails": {
        "AvsResultCode": null,
        "Bin": "1",
        "CvvResultCode": null,
        "Number": "•••• •••• •••• 1",
        "Company": "Bogus"
      }
    }
  ]
}