iF returns Javascript SDK

Overview

This is the library reference for the iF returns JavaScript SDK. It will include a description of how to use the SDK, the different supported methods, their required parameters, and their responses. During the return process, iF returns will offer other resolution methods to your customer to transform the monetary refund into a new sale. To enable these customer interactions, you need to perform two main actions:

Prepare the order data
Display the iF returns widget
Get the return request data and close the return flow

Prepare the return data

In this step, you have to prepare the order data that will be sent to the iF returns widget. The data will be used to display the list of products that the user will be able to select, and for the execution of the business rules configured by the merchant about product eligibility, return reasons, resolution methods and transport.

In this step you must configure the container where the widget will be displayed, as well as the flow of the return process that will be supported by the portal. The process flow establishes the steps of the customer journey that will be performed in the widget:

Product selection
Selection of return reasons
Resolution selection
Selection of exchange product (change of variant or exchange for another product)
Selection of return method
Payment of the price difference

Get the return request data and close the return flow

In this step the data returned by the widget shall be processed. The data will be returned via callback functions and its structure will depend on the process flow supported by the widget. The merchant is expected to use the returned data in order to close the customer's return flow on his website.

Set up JavaScript SDK - Client Session

The client session connection model should only be used in flows where the widget is to collect data on the return request, but without storing the final request. In this model , a client session will be generated when the SDK is initialised. This session will be used by the widget to retrieve the order data to be displayed to the customer.

From a security point of view, the following mechanisms can be implemented:

CORS Restrictions and domain whitelisting
Domain Binding, restrict the public token to work only on specific domains

To make the call for displaying the widget, first you need to add and initialize the SDK and then place a container in your page.

Add the SDK to your page

Add the SDK by including the following script in the body section of the page where the widget will be loaded .

<script src="https://cdn.ifreturns.com/js/v1/ifreturns.js" async></script>

You do not need to install the JavaScript SDK beforehand. It's enough to include the previous script in the HTML file of your page.

Initialize the SDK

Initialize the SDK library by making a call to the init() method.

Parameters

The init() method uses the following parameters:

Parameter	Data Type	Description
`publicKey`	`string`	Token assigned to your merchant code and your domain
`orderData`	`object`	Data of the sales order that contains the products the customer wants to return

Returns

InvalidTokenError If the token is not valid.

Sample Code

javascript

ifreturns.init({
  publicKey: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U', 
  orderData: {} 
})

The order data has the following format:

orderData.yaml

{
  "shopCode": "marchelacolombine",
  "currencyCode": "EUR",
  "ecommerceOrder": {
    "id": "123",
    "orderType": "DTC",
    "salesChannel": "web",
    "status": "COMPLETED",
    "totalPaid": 254,
    "totalDiscount": 0,
    "totalShippingCost": 5,
    "paymentMethods": [
      {
        "method": "credit_card",
        "amount": 254
      }
    ],
    "tags": [
      "WEB",
      "SUMMER"
    ],
    "discountCodes": [
      "WELCOME10",
      "FREESHIPPING"
    ],
    "lineItems": [
      {
        "id": "456456",
        "name": "Oxford shirt M",
        "sku": "OSM123",
        "variantOptions": [
          {
            "key": "color",
            "value": "blue"
          },
          {
            "key": "size",
            "value": "M"
          }
        ],
        "quantity": 1,
        "refundableQuantity": 1,
        "originalUnitPrice": 100,
        "lineTotalPrice": 100,
        "lineTotalDiscount": 0,
        "lineTotalPaid": 100,
        "productTags": [
          "new",
          "color:blue",
          "collection:summer"
        ],
        "primaryProductCategory": "shirts",
        "productVendor": "ifreturns"
      },
      {
        "id": "456488",
        "name": "Black trouser 38",
        "sku": "BT038",
        "variantOptions": [
          {
            "key": "color",
            "value": "black"
          },
          {
            "key": "size",
            "value": "38"
          }
        ],
        "quantity": 2,
        "refundableQuantity": 1,
        "originalUnitPrice": 149,
        "lineTotalPrice": 298,
        "lineTotalDiscount": 10,
        "lineTotalPaid": 288,
        "productTags": [
          "outlet"
        ],
        "primaryProductCategory": "trousers",
        "productVendor": "ifreturns"
      }
    ],
    "fulfillments": [
      {
        "id": "2454552154",
        "fulfilledAt": "2024-07-02",
        "deliverAt": "2024-07-04",
        "fulfillmentCenter": "MAIN_WAREHOUSE",
        "fulfillmentCenterCountryCode": "ES",
        "shipmentCarrier": "CORREOS",
        "shipmentServiceName": "Express Delivery",
        "fulfillmentLineItems": [
          {
            "lineItemid": "456456",
            "quantity": 1
          },
          {
            "lineItemid": "456488",
            "quantity": 2
          }
        ]
      }
    ]
  },
  "originAddress": {
    "postalCode": "28010",
    "countryCode": "ES"
  },
  "client": {
    "id": "2352123",
    "tier": "GOLD"
  }
}

Add a container to your page

Add a container in the HTML file where you want to display iFreturns widget . This container specifies where to place the widget.

<div id=ifreturns-container"> </div>

During the return process, your customers will enter into iF's return flow to have the option to choose product exchanges or gift card refunds. To display our widget you have to call the load() method on the client side. Once the widget is opened the customer can select the resolution for each returned product.

Parameters

The load() method uses the following parameters:

Parameter	Type	Description
`container`	`string`	Identifier of the container where the widget will be loaded. It should be an HTML element or a valid CSS selector.
`backUrl`	`string`	URL to redirect the client in case the widget closes without completing the flow.
`flowType`	`string`	Return steps that will be supported by the widget. Following values are accepted. ITEMS_SELECTION
`locale`	`string`	Language in which the widget will be localised (e.g. `es`)
`eventListeners`	`object`	Functions to be called to communicate events occurred during the process. Currently the following event event listeners are triggered: `onItemsSelected`: When the customer has completed the selection of items to return `onDismiss`: When the customer closes the widget without completing the flow. This function will be called even if the `backUrl` parameter is not sent

Returns

ApplicationNotInitializedError If load() is called prior to init()
InvalidContainerSelectorError If the container is neither an HTML element nor a valid CSS selector
FlowTypeNotSupportedError If the flow_type is not supported.

Sample Code

javascript

ifreturns.load({
  container: '#ifreturns-container', 
  flowType: 'PRODUCT_SELECTION', 
  backURL: 'https://merchant.com/account/123/order/P01', 
  sandbox: false, 
  onItemsSelected: (res) => { },
  onDismiss: () => { }) 
})

The order data has the following format:

orderData

{
  "shopCode": "marchelacolombine",
  "currencyCode": "EUR",
  "ecommerceOrder": {
    "id": "123",
    "orderType": "DTC",
    "salesChannel": "web",
    "status": "COMPLETED",
    "totalPaid": 254,
    "totalDiscount": 0,
    "totalShippingCost": 5,
    "paymentMethods": [
      {
        "method": "credit_card",
        "amount": 254
      }
    ],
    "tags": [
      "WEB",
      "SUMMER"
    ],
    "discountCodes": [
      "WELCOME10",
      "FREESHIPPING"
    ],
    "lineItems": [
      {
        "id": "456456",
        "name": "Oxford shirt M",
        "sku": "OSM123",
        "variantOptions": [
          {
            "key": "color",
            "value": "blue"
          },
          {
            "key": "size",
            "value": "M"
          }
        ],
        "quantity": 1,
        "refundableQuantity": 1,
        "originalUnitPrice": 100,
        "lineTotalPrice": 100,
        "lineTotalDiscount": 0,
        "lineTotalPaid": 100,
        "productTags": [
          "new",
          "color:blue",
          "collection:summer"
        ],
        "primaryProductCategory": "shirts",
        "productVendor": "ifreturns"
      },
      {
        "id": "456488",
        "name": "Black trouser 38",
        "sku": "BT038",
        "variantOptions": [
          {
            "key": "color",
            "value": "black"
          },
          {
            "key": "size",
            "value": "38"
          }
        ],
        "quantity": 2,
        "refundableQuantity": 1,
        "originalUnitPrice": 149,
        "lineTotalPrice": 298,
        "lineTotalDiscount": 10,
        "lineTotalPaid": 288,
        "productTags": [
          "outlet"
        ],
        "primaryProductCategory": "trousers",
        "productVendor": "ifreturns"
      }
    ],
    "fulfillments": [
      {
        "id": "2454552154",
        "fulfilledAt": "2024-07-02",
        "deliverAt": "2024-07-04",
        "fulfillmentCenter": "MAIN_WAREHOUSE",
        "fulfillmentCenterCountryCode": "ES",
        "shipmentCarrier": "CORREOS",
        "shipmentServiceName": "Express Delivery",
        "fulfillmentLineItems": [
          {
            "lineItemid": "456456",
            "quantity": 1
          },
          {
            "lineItemid": "456488",
            "quantity": 2
          }
        ]
      }
    ]
  },
  "originAddress": {
    "postalCode": "28010",
    "countryCode": "ES"
  },
  "client": {
    "id": "2352123",
    "tier": "GOLD"
  }
}

The widget returns the data collected during the executed process flow. This data must be used by the merchant in order to finalise the customer's return flow on his website.

onItemsSelected Response

The response of the callback onItemsSelected will contain the list of products selected by the customer. The following data will be included per each selected item:

Return Reason
Resolution method
New exchange item

onItemSelectedResponse

{
  "returnLineItems": [
    {
      "id": "e98ff5b3-362e-462f-9931-5e4deba6ae8c",
      "sku": "P4545454",
      "barcode": "778545487",
      "quantity": 1,
      "refundAmount": 0,
      "refundType": "EXCHANGE",
      "refundMode": "POST_VALIDATION",
      "returnReason": {
        "additionalInfo": "Me queda grande en la parte alta",
        "code": "size-big-reason",
        "reason": "Es demasiado grande"
      },
      "evidenceImgUrls": [
          "https://ifreturns.com/evidence1.png",
          "https://ifreturns.com/evidence2.png" 
],
      "exchangeLineItems": [
        {
          "id": "ee07a87f-9471-41d9-a84e-c29c0d80349b",
          "ecommerceProductId": "gid://shopify/Product/7260093055162",
          "ecommerceVariantId": "gid://shopify/ProductVariant/46613114290507",
          "imageUrl": "https://merchant.com/products/3.webp?v=1667378318",
          "productName": "Apple iPhone 13 Pro 128GB",
          "variantName": "Amarillo / Platino",
          "quantity": 1,
          "sku": "P78845457",
          "price": 1183,
          "vendor": "Marche La Colombine"
        }
      ]
    },
    {
      "id": "4efb9e81-ef96-4fc6-ab87-7466b741610c",
      "sku": "P898956",
      "barcode": "1545485",
      "quantity": 1,
      "refundAmount": 120,
      "refundType": "ORIGINAL_PAYMENT_METHOD",
      "refundMode": "POST_VALIDATION",
      "returnReason": {
        "additionalInfo": "Al final no me gustó el corte",
        "code": "whim-reason",
        "reason": "Cambié de opinión"
      },
      "evidenceImgUrls": [],
      "exchangeLineItems": []
    }
  ]
}

iF returns Javascript SDK

Overview

Prepare the return data

Display the iF return widget

Get the return request data and close the return flow

Set up JavaScript SDK - Client Session

Add the SDK to your page

Initialize the SDK

Add a container to your page

Display iF returns widget

Process widget response data

Was this helpful?