Webhooks

Webhooks are HTTP callbacks processed and sent by Loop to a pre-defined URL. Each webhook has a topic, which defines the payload itself, & a trigger, which determines the event which triggers the request.

Loop offers two webhook topics:

• Return

• Label

Loop offers four triggers:

• Return create

• Return update

• Label create

• Label update

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 setup 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 will need to contact Loop to have them re-enabled.

If you plan on using our webhooks, please reach out to Loop for the initial set up.

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.

v1 Response (Deprecated)

{
    "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"
}

v2 Response

{
    "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"
        }
    ],
    "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.

v2 Response

{
    "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.

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

Response

[
    {
        "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

Response

[
    {
        "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"
            }
        ],
        "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",
        "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

Respone

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

Respone

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

Respone

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

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>

POST

Response

{
  "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>

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

Example of data after decoding

{
  "loop_total": 1299,
  "loop_base": 799,
  "loop_credit": 500,
  "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_total	total credit after tax in cents
loop_base	total credit without tax
loop_credit	amount of bonus credit
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

POST

Payload

{
  "cart": [
    1532560506891,
    1532560506892
  ]
}

Response

{
  "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. The token will change with every call.

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.

Complete Transaction

URL

https://<subdomain>.loopreturns.com/#/cart/<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 Snippet)

setKey

Loop.setKey(apiKey)

Parameters	Description
apiKey	STRING - Loop developer API key

The setKey function is used to set and store your API key for your snippet to use on it's calls to the server.

setup

Loop.setup(mode)

Parameters	Description
mode	STRING - Loop preconfiguration option("url", "input", "option")

url

-Many Shopify templates use url params to keep track of their variants. This mode is created to detect the variant in the URL param and send it to the Loop Cart when a customer hits "Add to Cart".

-If your variant param is different from the default 'variant' key, you can update it the same you you configured the Add To Cart button with "Loop.config.targets.url".

input

-UNDER DEVELOPMENT

option

-UNDER DEVELOPMENT

updateVariant

Loop.updateVariant(variant, callback);

Parameters	Description
variant	STRING - Shopify variant ID
callback	FUNCTION - Optional, callback function

The updateVariant method is used to change and store the variant id help in the snippet. This is useful for binding to change events, like a swatch select or any other input change. You can use Loop.submit() with no params at anytime after this and it will use the variant id of the last update.

submit

Loop.submit(variant)

Parameters	Description
variant	STRING - Optional, Shopify variant ID

The submit function is used to create a token and send you back to the loop app automatically. This is great for flows that send you back to the app when adding an item to the cart. A 'variant' param should only needs to be specified if you have not been updating the variant id already.