Webhooks

Webhooks are HTTP callbacks processed and sent by Loop to a pre-defined URL. They allow your application to recive information from Loop without having to reach out to Loop via an API call. Each webhook has a topic, which defines the information payload, & a trigger, which determines the event which triggers the request to be sent from Loop.

Setting Up Webhooks

To set up webhooks you can go to the settings/developers page in the Loop admin. There you can create a webhook and select the topic, trigger, and define the URL the payload will be went to.

Loop offers three webhook topics:

Return
Label
Restock

Loop offers five triggers:

Return create (fires a webhook when a return is created)
Return update (fires a webhook when a return is updated)
Label create (fires a webhook when a shipping label is created)
Label update (fires a webhook when a shipping label is updated)
Restock Requested (fires a webhook when an item is restocked in Shopify using a webhook)

The topics & triggers can be combined to suit your desired outcome. There are also certain combinations that will not yield results. (For example, If you set up a webhook with a topic of "Label" & a trigger of "Return create", there will be no payload available, as a return is created before the label.)

Each of our webhooks expect a successful response and will, in the case of failure, reattempt up to 3 times.

Our webhooks will disable if they get a non-2xx response more than 10 times consecutively. you can reactivate the webhook in the settings/developers page of the Loop Admin. To prevent webhooks from disabling themselves after 10 failues you can turn on testing mode, which prevents this for 72 hours.

If you wish to see the information payload of a webhook before incorporating the webhook into your code the webpage webhook.site is a wonderful resource. They provide you with a url to use in the webhook and display the information you receive on their page, allowing you to examine the JSON structure of the payload when the webhook is fired (even as a test). Later on you can change the webhook URL for production use.

If you need additional support regarding webhooks, please reach out to Loop.

Return Webhook

This notification is sent when the return topic is requested. For those that subscribe to this topic for more than one trigger event, the "trigger" property is included in the payload for reference.

{
    "topic": "return",
    "trigger": "return.created",// or "return.updated"
    "id": "12345",
    "state": "open",
    "created_at": "2019-04-01T12:00:00+00:00",
    "total": "0.00",
    "order_id": "1234567890",
    "provider_order_id": "1029384756",
    "order_name": "#1234",
    "order_number": "1234",
    "customer": "me@myself.com",
    "currency": "USD",
    "exchange": "10.00",
    "gift_card": "0.00",
    "refund": "0.00",
    "line_items": [
      {
        "line_item_id": "123456789",
        "provider_line_item_id": "3847568374653883",
        "product_id": "1624622563417",
        "variant_id": "14773475377241",
        "sku": "FD-RL-2",
        "title": "Retro Laser",// includes variant title where applicable
        "price":"10.00",
        "returned_at":"2019-04-01T12:00:00+00:00",
        "exchange_variant": "14773475377999",
        "return_reason": "Reason here",
        "parent_return_reason": "Parent reason here"
      }
    ],
    "carrier": "USPS",// If no label exists, we pass "N/A"
    "tracking_number": "28735625627856237856287",// If no label exists, we pass "N/A"
    "label_status": "in_transit",// If no label exists, we pass "N/A"
    "label_updated_at": "2019-04-01T12:00:00+00:00"// If no label exists, we pass "N/A"
}

{
    "topic": "return",
    "trigger": "return.created",
    "id": "12345",
    "state": "open",
    "created_at": "2019-04-01T12:00:00+00:00",
    "order_id": "1234567890",
    "order_name": "#1234",
    "provider_order_id": "1029384756",
    "order_number": "1234",
    "customer": "me@myself.com",
    "currency": "USD",
    "return_product_total": "46.00",
    "return_discount_total": "0.00",
    "return_tax_total": "3.34",
    "return_total": "49.34",
    "return_credit_total": "49.34",
    "exchange_product_total": "84.00",
    "exchange_discount_total": "10.00",
    "exchange_tax_total": "5.37",
    "exchange_total": "79.37",
    "exchange_credit_total": "49.34",
    "gift_card": "0.00",
    "handling_fee": "0.00",
    "refund": "0.00",
    "upsell": "30.03",
    "line_items": [
        {
            "line_item_id": "123456789",
            "provider_line_item_id": "3847568374653883",
            "product_id": "1624622563417",
            "variant_id": "14773475377241",
            "sku": "FD-RL-2",
            "title": "Retro Laser - Big",
            "price": "46.00",
            "discount": "0.00",
            "tax": "3.34",
            "refund": "0.00",
            "returned_at": "2019-04-01T12:00:00+00:00",
            "exchange_variant": "",
            "return_reason": "Reason here",
            "parent_return_reason": "Parent reason here",
            "outcome": "Line item outcome('default', 'keep', 'donate', 'reject')"

        }
    ],
    "exchanges": [
        {
            "exchange_id": "54320",
            "product_id": "1624622563418",
            "variant_id": "14773475377242",
            "sku": "FD-NC-1",
            "title": "Noisy Cricket - Small",
            "price": "46.00",
            "discount": "5.48",
            "tax": "2.94",
            "total": "43.46"
        },
        {
            "exchange_id": "54321",
            "product_id": "1624622563419",
            "variant_id": "14773475377243",
            "sku": "FD-RG-2",
            "title": "Ray Gun - Medium",
            "price": "46.00",
            "discount": "5.48",
            "tax": "2.94",
            "total": "43.46"
        }
    ],
    "carrier": "USPS",// If no label exists, we pass "N/A"
    "tracking_number": "28735625627856237856287",// If no label exists, we pass "N/A"
    "label_status": "in_transit",// If no label exists, we pass "N/A"
    "label_updated_at": "2019-04-01T12:00:00+00:00"// If no label exists, we pass "N/A"
}

Response Header	Description
X-Loop-Signature	Hashed Webhook Secret Key

The X-Loop-Signature is a base-64, HMAC hash of body payload using the Webhook Secret provided by Loop.

Note: Before attempting to create your hash of the POST request body, make sure slashes have been escaped & newlines have been removed from the JSON.

Label Webhook

This notification is sent when the label topic is requested. For those that subscribe to this topic for more than one trigger event, the "trigger" property is included in the payload for reference.

{
    "topic": "label",
    "trigger": "label.updated",
    "return_id": "12345",
    "order_id": "1234567890",
    "provider_order_id": "1029384756",
    "carrier": "USPS",
    "tracking_number": "28735625627856237856287",
    "label_status": "in_transit",
    "label_updated_at": "2019-04-01T12:00:00+00:00"
}

Response Header	Description
X-Loop-Signature	Hashed Webhook Secret Key

The X-Loop-Signature is a base-64, HMAC hash of body payload using the Webhook Secret provided by Loop.

Note: Before attempting to create your hash of the POST request body, make sure slashes have been escaped & newlines have been removed from the JSON.

Restocking Webhook

This is sent out when a line item has been restocked in Shopify. This webhook triggers when you have restock set to webhooks rather than restocking set to Shopify directly. This setting is found in the general settings page of the Loop Admin.

{
  "topic": "restock",
  "trigger": "restock.requested",
  "id": "12345",
  "order_id": "1234567890",
  "provider_order_id": "1029384756",
  "restock_items": [
    {
      "location_id": "10123456789",
      "inventory_item_id": "10987654321",
      "available_adjustment": "1",
      "inventory_management": "shopify"
    }
  ]
}

Response Header	Description
X-Loop-Signature	Hashed Webhook Secret Key

The X-Loop-Signature is a base-64, HMAC hash of body payload using the Webhook Secret provided by Loop.

Note: Before attempting to create your hash of the POST request body, make sure slashes have been escaped & newlines have been removed from the JSON.

API Key Scopes

As of 8/2019, Loop has strictly scoped APIs. All previously existing keys have been granted all scopes, so they will be backwards compatible. (Reach out to Loop for access to the new developer page, which will allow you to create your own API keys & assign any scopes you need.)

API Key Scope	Available APIs
Returns	Advanced Shipping Notice, Process Return, Flag Return, Cancel Return, Return Details
Orders	Deeplink
Carts	On-store, On-store Snippet
Reports	Coming Soon

Returns API (Formerly Warehouse API)

The Loop warehouse API requires a key to be generated by Loop that you will include in your requests. The base url for all warehouse API calls will be https://api.loopreturns.com/api/v1

Advanced Shipping Notice

[
    {
        "id": 12345,
        "created_at": "dd/mm/yyyy hh:mm:ss",
        "updated_at": "dd/mm/yyyy hh:mm:ss",
        "return_line_item_id": 1234,
        "order_id": 1234567890,
        "order_name": "#1234",
        "state": "open",
        "customer_email": "me@myself.com",
        "title": "Cool Product Name",
        "sku": "THX-1138",
        "carrier": "USPS",
        "label_status": "in_transit",
        "label_updated_at": "dd/mm/yyyy",
        "tracking_number": "28735625627856237856287"
    }
]

Endpoint to pull all packages by tracking statuses/timeframe.

Request

GET api.loopreturns.com/api/v1/warehouse/reporting/asn?from=yyyy/mm/dd&to=yyyy/mm/dd

Header	Description
X-Authorization	Authorization token

Query Params	Description
from	ASN start date, format yyyy/mm/dd
to	ASN end date, format yyyy/mm/dd

Detailed Returns List

[
    {
        "id": "12345",
        "state": "open",
        "created_at": "2019-04-01T12:00:00+00:00",
        "updated_at": "2019-04-01T12:00:00+00:00",
        "order_id": "1234567890",
        "order_name": "#1234",
        "provider_order_id": "1029384756",
        "order_number": "1234",
        "customer": "me@myself.com",
        "currency": "USD",
        "return_product_total": "46.00",
        "return_discount_total": "0.00",
        "return_tax_total": "3.34",
        "return_total": "49.34",
        "return_credit_total": "49.34",
        "exchange_product_total": "84.00",
        "exchange_discount_total": "10.00",
        "exchange_tax_total": "5.37",
        "exchange_total": "79.37",
        "exchange_credit_total": "49.34",
        "gift_card": "0.00",
        "handling_fee": "0.00",
        "refund": "0.00",
        "upsell": "30.03",
        "line_items": [
            {
                "line_item_id": "123456789",
                "provider_line_item_id": "3847568374653883",
                "product_id": "1624622563417",
                "variant_id": "14773475377241",
                "sku": "FD-RL-2",
                "title": "Retro Laser - Big",
                "price": "46.00",
                "discount": "0.00",
                "tax": "3.34",
                "refund": "0.00",
                "returned_at": "2019-04-01T12:00:00+00:00",
                "exchange_variant": "",
                "return_reason": "Reason here",
                "parent_return_reason": "Parent reason here",
                "barcode": "1234567890"
            }
        ],
        "exchanges": [
            {
                "exchange_id": "54320",
                "product_id": "1624622563418",
                "variant_id": "14773475377242",
                "type": "storefront",
                "sku": "FD-NC-1",
                "title": "Noisy Cricket - Small",
                "price": "46.00",
                "discount": "5.48",
                "tax": "2.94",
                "total": "43.46"
            },
            {
                "exchange_id": "54321",
                "product_id": "1624622563419",
                "variant_id": "14773475377243",
                "type": "advanced",
                "sku": "FD-RG-2",
                "title": "Ray Gun - Medium",
                "price": "46.00",
                "discount": "5.48",
                "tax": "2.94",
                "total": "43.46"
            }
        ],
        "carrier": "USPS",
        "tracking_number": "28735625627856237856287",
        "label_status": "in_transit",
        "label_updated_at": "2019-04-01T12:00:00+00:00"
    },
    {
        ...
    }
]

Endpoint to pull a detailed list of returns submitted during a given timeframe, down to the second.

If no datetimes are passed, list defaults to the previous 24 hours.

Request

GET api.loopreturns.com/api/v1/warehouse/return/list?from={{ timestamp }}&to={{ timestamp }}

Header	Description
X-Authorization	Authorization token

Query Params	Description
from	list start date, MySQL datetime format: yyyy-mm-dd hh:mm:ss, e.g. 2019-01-01 00:00:00
to	list end date, MySQL datetime format: yyyy/mm/dd hh:mm:ss, e.g. 2019-01-08 23:59:59

Process Return

true

Endpoint to process returns. You may pass one or more optional values as a json payload to the process endpoint.

Request

POST api.loopreturns.com/api/v1/warehouse/return/{return id}/process

Payload	Description
rmaid	A custom value to be passed along to Shopify.
custom1	A string to be passed along to Shopify.
custom1	A string to be passed along to Shopify.

Header	Description
X-Authorization	Authorization token

Flag Return

true

Endpoint to flag returns for manual review.

Request

POST api.loopreturns.com/api/v1/warehouse/return/{return id}/flag

Header	Description
X-Authorization	Authorization token

Cancel Return

true

Endpoint to cancel returns.

Request

POST api.loopreturns.com/api/v1/warehouse/returns/{return id}/cancel

Header	Description
X-Authorization	Authorization token

Return Details

{
    "id": 799367,
    "created_at": "2019-02-07 23:11:56",
    "order_id": 828525019234,
    "order_name": "#1164",
    "order_number": 164,
    "state": "open",
    "currency": "USD",
    "refund": 0,
    "gift_card": 0,
    "exchange": "125.00",
    "return_total": "125.00",
    "line_items": [
      {
          "provider_line_item_id": 3985739845738957
          "sku": "THX-1138"
          "title": "Shirt",
          "returned_at": "2017-05-30 15:55:00"
          "line_item_id": 1234567,
          "product_id": 1234567,
          "variant_id": 1234567,
          "price": "125.00",
          "exchange_variant": 1234566,
          "reason": "This is the child reason",
          "parent_reason": "This is the parent reason"
      }
    ],
    "customer_email": "me@myself.com",
    "carrier": "USPS",
    "label_status": "in_transit",
    "label_updated_at": "dd/mm/yyyy",
    "tracking_number": "28735625627856237856287"
}

Endpoint to get the details of a return.

Request

GET api.loopreturns.com/api/v1/warehouse/return/details?<query>=<value>

Pass one of the query params below at a time.

Header	Description
X-Authorization	Authorization token

Query Params	Description
return_id	id of the return
order_name	name on the order of the return
order_id	id associated with the order the return was placed on

Listings API

The Loop listings API requires a key to be generated by Loop that you will include in your requests. The base url for all listings API calls will be https://api.loopreturns.com/api/v1

List Blacklist Items

{
    "current_page": 1,
    "data": [
        {
            "id": 123,
            "created_at": "<date time>",
            "type": "order",
            "value": "order name",
            "secondary_value": null
        }
    ],
    "from": 1,
    "last_page": 1,
    "next_page_url": null,
    "path": "https://api.looptesting.rocks/api/v1/blacklists",
    "per_page": 15,
    "prev_page_url": null,
    "to": 2,
    "total": 2
}

Endpoint to pull paginated blacklisted items.

Request

GET api.loopreturns.com/api/v1/blacklists?page=1

Header	Description
X-Authorization	Authorization token

Get Blacklisted Item

{
    "id": 57,
    "created_at": "<date time>",
    "type": "order",
    "value": "order name",
    "secondary_value": null
}

Endpoint to get a blacklisted item by id.

Request

`GET api.loopreturns.com/api/v1/blacklists/{id}

Header	Description
X-Authorization	Authorization token

Add Blacklist Item

{
    "id": 57,
    "created_at": "<date time>",
    "type": "order",
    "value": "order name",
    "secondary_value": null
}

Endpoint to create a blacklist entry.

Request

POST api.loopreturns.com/api/v1/blacklists

Payload	Description
type	order, product or email.
value	The value of the product, email or order to blacklist.
secondary_value	Optional secondary value.

Header	Description
X-Authorization	Authorization token

Delete Blacklist Entry

Endpoint to delete a blacklist entry by id.

Request

DELETE api.loopreturns.com/api/v1/blacklists/{id}

Header	Description
X-Authorization	Authorization token

List Whitelisted Items

{
    "current_page": 1,
    "data": [
        {
            "id": 123,
            "created_at": "<date time>",
            "type": "order",
            "value": "order name",
            "secondary_value": null
        }
    ],
    "from": 1,
    "last_page": 1,
    "next_page_url": null,
    "path": "https://api.looptesting.rocks/api/v1/whitelists",
    "per_page": 15,
    "prev_page_url": null,
    "to": 2,
    "total": 2
}

Endpoint to pull paginated whitelisted items.

Request

GET api.loopreturns.com/api/v1/whitelists?page=1

Header	Description
X-Authorization	Authorization token

Get Whitelist Item

{
    "id": 57,
    "created_at": "<date time>",
    "type": "order",
    "value": "order name",
    "secondary_value": null
}

Endpoint to get a whitelisted item by id.

Request

`GET api.loopreturns.com/api/v1/whitelists/{id}

Header	Description
X-Authorization	Authorization token

Add Whitelist Item

{
    "id": 57,
    "created_at": "<date time>",
    "type": "order",
    "value": "order name",
    "secondary_value": null
}

Endpoint to create a whitelist entry.

Request

POST api.loopreturns.com/api/v1/whitelists

Payload	Description
type	order or email.
value	The value of the product, email or order to blacklist.
secondary_value	Optional secondary value.

Header	Description
X-Authorization	Authorization token

Delete Whitelist Entry

Endpoint to remove a blacklist entry by id.

Request

DELETE api.loopreturns.com/api/v1/whitelists/{id}

Header	Description
X-Authorization	Authorization token

Orders API (Formerly Deeplink API)

Authentication/Setup

Set the request headers of all API requests to the following:

content-type: application/json

x-authorization: <api-key>

You must replace api-key with your personal API key.

POST

{
  "link": "https://example.loopreturns.com/as7d687atd78attsd78tas87dt7tdt7td"
}

HTTP Request

POST api.loopreturns.com/api/v1/order/link

Payload	Description
designation	This is your store id.
name	The Shopify order number
zip	the shipping zip code attached to the order

Response	Description
link	Link that will take the user directly to their order

Cart API (On-Store)

Authentication/Setup

Set the request headers of all API requests to the following:

content-type: application/json

x-authorization: <api-key>

You must replace api-key with your personal API key.

Initial Data

Example URL: https://example.myshopify.com/?loop_total=1299&loop_base=799&loop_credit=500&loop_subdomain=example&loop_redirect_url=example.loopreturns.com%2F%23%2Fcredit&loop_customer_name=Jane%20Doe

{
  "loop_return_id": "e1d10005-ec40-47da-b47b-424c4b19f11c",
  "loop_currency": "USD",
  "loop_total": 1299,
  "loop_base": 799,
  "loop_credit": 500,
  "loop_domain": "example.loopreturns.com",
  "loop_subdomain": "example",
  "loop_redirect_uri": "example.loopreturns.com/#/credit",
  "loop_customer_name": "Jane Doe"
}

When a customer is dropped onto your store from the app, there will be multiple parameters in the link address. It will be up to you to URI Decode these parameters and use them for your on-store experience. The parameters are as follows:

URL Parameters	Description
loop_return_id	A UUID that is unique per order lookup
loop_currency	The currency the original order was made in
loop_total	total credit after tax in cents
loop_base	total credit without tax
loop_credit	amount of bonus credit
loop_domain	The domain the user came from
loop_subdomain	Loop's subdomain for you
loop_redirect_uri	redirect link back to the app
loop_customer_name	name of customer on the original order

Create cart

{
  "cart": [
    1532560506891,
    1532560506892
  ]
}

{
  "token": "15113876394d0bdd44dbdf80596f2c774b29837ae25",
  "data": {
    "cart": [
      1532560506891,
      1532560506892
    ]
  }
}

This initial call is used to create a cart in our system. It will return a cart token that will later be passed to the returns portal for cart retrieval.

HTTP Request

POST api.loopreturns.com/api/v1/cart/

Payload	Description
Cart	Array of variant ids

Our system takes the Shopify variant ids sent to us and generates a cart. This cart will be held for 30 days before expiring or will be deleted when the return they are attached to is processed.

Response	Description
Token	Your token for the cart.
Cart	Array of current variants attached to the token.

Get cart

{
  "cart": [
    1532560506891,
    1532560506892
  ]
}

Get an existing cart by cart token. You can get a cart token by calling the create cart endpoint.

HTTP Request

GET api.loopreturns.com/api/v1/cart/{token}

Response	Description
Cart	Array of current variants attached to the token.

Update cart

{
  "cart": [
    1532560506891,
    1532560506892
  ]
}

{
  "updated": true,
  "data": {
    "cart": [
      1532560506891,
      1532560506892
    ]
  }
}

Modifies an existing cart to set the variants to whatever you send it. The cart array you send it will replace the existing cart, so you'll need to make sure you're sending the entire cart you want.

HTTP Request

POST api.loopreturns.com/api/v1/cart/{token}

Payload	Description
Cart	Array of variant ids

Response	Description
Updated	Boolean, whether or not the cart was successfully updated.
Cart	Array of current variants attached to the token.

Delete cart

true

Delete a card

HTTP Request

DELETE api.loopreturns.com/api/v1/cart/{token}

Complete Transaction

URL

https://<subdomain>.loopreturns.com/#/cart/v2/<token>

URL Parameters	Description
Subdomain	This is the subdomain attached to your returns portal at loopreturns.com.
Token	The token you received in response to the POST request

When a customer is satisfied with their cart, they should be redirected back to the app like this. From there, we will process the token and automatically add the items to the cart. All credit and tax calculations will be accounted for at this point and displayed to the customer.

Cart API (On-Store SDK)

<script src="https://unpkg.com/@loophq/onstore-sdk@latest/dist/loop-onstore-sdk.js"></script>
<script>
  LoopOnstore.init({
    key: 'api key',
    attach: 'checkout button selector'
  });
</script>

The easiest way to integrate with the cart API is to use our onstore SDK.

Create a development theme on your Shopify store. You can do this by duplicating your live theme. We recommend renaming it to something that indicates what it's for, like "Current theme + Loop On-Store Integration".
Click the actions dropdown on your new theme and select "Edit code". This will load up Shopify's theme editor. Once that's open, find the file under the layout section named theme.liquid and open it.
Scroll to the bottom of the page and find the </body>. Paste the snippet directly above the </body> tag.
Paste your API key as the key value in the init call.
Find a unique selector for your checkout button and paste that as the attach value in the init call. You can find this by right clicking on your checkout button and selecting inspect element. Common selectors are #checkout, .checkout, .cart__checkout, and .cart__submit.
Test that you've integrated successfully by running LoopOnstore.testMode() in your browser console. You should see the page refresh with on-store enabled and the messages Loop returns activated and Loop attaching to: "<your checkout button>" print out in console.
Do a full test starting in Loop Returns and have it send you to your store and then send you back to Loop Returns when you click the checkout button.

<script src="https://unpkg.com/@loophq/onstore-sdk@latest/dist/loop-onstore-sdk.js"></script>
<script>
  LoopOnstore.init({
    key: 'f0e4c2f76c58916ec258f246851bea091d14d4247a2fc3e18694461b1816e13b',
    attach: '.checkout__button'
  });
</script>