NAV Navbar
JSON
  • Webhooks
  • API Key Scopes
  • Returns API (Formerly Warehouse API)
  • Listings API
  • Orders API (Formerly Deeplink API)
  • Cart API (On-Store)
  • Cart API (On-Store SDK)
  • 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:

    Loop offers five triggers:

    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.

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

    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.

    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.

    v2 Response

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

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

    Response

    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

    Response

    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

    Response

    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

    Response

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

    Response

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

    Response

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

    Response

    200
    

    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

    Response

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

    Response

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

    Response

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

    Response

    200
    

    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>

    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_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

    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.

    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

    Response

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

    Payload

    {
      "cart": [
        1532560506891,
        1532560506892
      ]
    }
    

    Response

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

    Response

    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)

    Snippet

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

    1. 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".
    2. 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.
    3. Scroll to the bottom of the page and find the </body>. Paste the snippet directly above the </body> tag.
    4. Paste your API key as the key value in the init call.
    5. 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.
    6. 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.
    7. 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.

    Sample

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