Third Party Labels

📝 Overview

Loop’s third party label feature allows merchants to generate return labels using providers that aren’t directly integrated with Loop’s shipping services. This is a step-by-step guide for merchants and partners to integrate with Loop’s Labels API, enabling automated shipping label generation, management, and status updates for returns.

🔁 Label request lifecycle

Every label request Loop creates moves through a small, fixed set of statuses. Understanding this model up front makes the rest of this guide easier to follow.

issued — Loop is waiting for your integration to push a label for this request. issued is the only status that requires action from your integration.
fulfilled — Your integration pushed a label via the Create Label API. Terminal — there’s nothing more to do for this request.
cancelled — The request was withdrawn, either because a merchant clicked Create/Regenerate label in Loop admin, or because the return itself was cancelled. Terminal for this id. If a label is still needed, cancelling always issues a fresh request with a new id (a new label.request.issued event) — the same request is never reopened.

There is no “errored” status. Reporting an error is an append-only annotation on an issued request — see below.

What happens when you report an error

Calling the Create a Label Request Error API only:

Records the error against that label request.
Surfaces it as an entry on the return’s timeline in Loop admin, so the merchant can see something went wrong.

It does not:

Retry anything.
Create a new label request.
Send a new webhook.
Notify the merchant or shopper by email.
Change the request’s status — it stays issued.

Because the request is still issued and still has no label, you can fulfill it later with a normal POST /labels call using the same id — that’s the recommended way to recover from a transient failure (rate limit, carrier outage, and so on), not anything Loop does automatically.

Until a label exists, the shopper receives no confirmation email at all — reporting an error doesn’t change that. If you never follow up with a label, the return just stays open with none.

The only Loop-side recovery is manual: a merchant clicking Create/Regenerate label on the return in Loop admin. That cancels the existing label request(s) — firing label.request.cancelled — and issues new one(s) with new ids.

If you poll instead of using webhooks

A label request you’ve reported an error on is still status=issued, so it will keep showing up in every subsequent poll of the List Label Requests API. Track which ids you’ve already reported errors for so you don’t reprocess the same failure forever — or check the errors array on each returned LabelRequestResponse, which also lets you detect an already-errored request directly from the payload.

⚙️ Prerequisites

Before integrating with the Labels API, complete the following setup steps:

Accept our Label Provider Terms

Start by filling out this form, which will send a signable version of our terms to your preferred signatory. If you have any questions about those terms, please feel free to reach out to Kent Woodyard (kent@loopreturns.com).

Register your integration

Follow the steps in the Authorize with OAuth guide to register your integration and obtain an OAuth client ID and secret. This is required to use the Labels API.

The code samples in this guide use an API key in the X-Authorization header for simplicity. Once your integration is registered per the steps above, each call can instead authenticate with an OAuth 2.0 bearer token scoped to whatever that operation requires: the webhook-creation samples immediately below need developer_tools (per the Webhooks API reference), while the Labels API calls used later in this guide need label_requests:read (list/get label requests), label_requests:write (report a label request error), or labels:write (create a label, update label status). See Authentication for both methods.

Create a webhook via the Loop API

Only necessary if you want to receive label requests via webhooks (real-time event delivery).

After your integration completes the OAuth flow, you can create a webhook via the Loop API. See the Webhooks API reference for more details.

const fetch = require('node-fetch');

const createWebhook = async () => {
  const response = await fetch('https://api.loopreturns.com/api/v1/webhooks', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Authorization': 'your-api-key-here',
    },
    body: JSON.stringify({
      topic: 'label.request',
      trigger: 'label.request.issued',
      url: 'https://your-app.com/webhook',
      status: 'active',
    }),
  });

  if (response.ok) {
    const webhook = await response.json();
    console.log('Webhook created:', webhook);
    return webhook;
  } else {
    const error = await response.json();
    console.error('Error creating webhook:', error);
    throw new Error('Failed to create webhook');
  }
};

createWebhook();

import requests
import json

def create_webhook():
    url = 'https://api.loopreturns.com/api/v1/webhooks'
    headers = {
        'Content-Type': 'application/json',
        'X-Authorization': 'your-api-key-here'
    }
    data = {
        'topic': 'label.request',
        'trigger': 'label.request.issued',
        'url': 'https://your-app.com/webhook',
        'status': 'active'
    }

    response = requests.post(url, headers=headers, json=data)

    if 200 <= response.status_code < 300:
        webhook = response.json()
        print('Webhook created:', webhook)
        return webhook
    else:
        error = response.json()
        print('Error creating webhook:', error)
        raise Exception('Failed to create webhook')

create_webhook()

<?php

function createWebhook() {
    $url = 'https://api.loopreturns.com/api/v1/webhooks';
    $headers = [
        'Content-Type: application/json',
        'X-Authorization: your-api-key-here'
    ];
    $data = [
        'topic' => 'label.request',
        'trigger' => 'label.request.issued',
        'url' => 'https://your-app.com/webhook',
        'status' => 'active'
    ];

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode >= 200 && $httpCode < 300) {
        $webhook = json_decode($response, true);
        echo 'Webhook created: ' . json_encode($webhook) . "\n";
        return $webhook;
    } else {
        $error = json_decode($response, true);
        echo 'Error creating webhook: ' . json_encode($error) . "\n";
        throw new Exception('Failed to create webhook');
    }
}

createWebhook();
?>

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.JsonNode;
import java.util.HashMap;
import java.util.Map;

public class CreateWebhook {
    private static final HttpClient client = HttpClient.newHttpClient();
    private static final ObjectMapper objectMapper = new ObjectMapper();

    public static void main(String[] args) throws Exception {
        createWebhook();
    }

    public static JsonNode createWebhook() throws Exception {
        String url = "https://api.loopreturns.com/api/v1/webhooks";
        String apiKey = "your-api-key-here";

        Map<String, String> data = new HashMap<>();
        data.put("topic", "label.request");
        data.put("trigger", "label.request.issued");
        data.put("url", "https://your-app.com/webhook");
        data.put("status", "active");

        String jsonBody = objectMapper.writeValueAsString(data);

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/json")
            .header("X-Authorization", apiKey)
            .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() / 100 == 2) {
            JsonNode webhook = objectMapper.readTree(response.body());
            System.out.println("Webhook created: " + webhook.toString());
            return webhook;
        } else {
            JsonNode error = objectMapper.readTree(response.body());
            System.err.println("Error creating webhook: " + error.toString());
            throw new RuntimeException("Failed to create webhook");
        }
    }
}

Configure return policies

In the Loop admin, navigate to Returns management → Policy settings → Return policies.
Create or edit a return policy.
Ensure “Generate labels” is toggled on.
Under Label provider, select “External connector”.
Confirm with your third party label partner that they’re ready to go live before enabling.

🔍 Step 1: Discover Labels to Generate

There are two ways to discover when a shipping label needs to be generated for a return:

Receive real-time notifications via webhooks when a label request event occurs.
Periodically poll the API to retrieve outstanding label requests that require action.

We strongly recommend using webhooks to receive real-time notifications for label requests, instead of polling the API. Webhooks ensure your customers get their labels faster and reduce the number of API calls made to Loop. Polling should only be used if webhooks are not supported in your environment.

If you choose to receive events via webhooks, the Label requests webhook allows you to subscribe to the following events:

label.request.issued — Triggered when Loop requires a new shipping label for a return.
label.request.cancelled — Triggered when a previously issued label request is cancelled (for example, a merchant regenerates the label, or the return itself is cancelled). When you receive this event, stop any work in progress for that label request id, and void or refund the carrier label if you already purchased one for it. Label request ids are never reused — if a label is still needed, Loop issues a new label.request.issued event with a brand-new id. Don’t key your own records on a cancelled id expecting it to come back.

When these events occur, Loop will send a POST request to your configured webhook URL with details about the label request. Your integration can use this information to generate or cancel shipping labels as needed.

For more details on event payloads and configuration, see the Label requests webhook documentation.

Poll for labels

If you prefer to poll for outstanding label requests, you can use the List Label Requests API.

Pass status=issued to retrieve only the label requests that need action — without a status filter, this endpoint returns label requests of every status (issued, cancelled, and fulfilled).
You can filter results by status, creation date, or other parameters to only fetch relevant label requests.

Typical usage:

Periodically call this endpoint (e.g., every 15 minutes, every hour) to check for new or updated label requests.
Process each returned label request according to your business logic.

For full details on request parameters and response structure, see the API documentation.

🏷️ Step 2: Generate and Push the Label

To fulfill a label request, follow these steps:

Generate the shipping label

Use the id field from the webhook payload or List Label Requests API to identify the label request you need to fulfill.
If you need to fetch the full details for a specific label request (for example, if you only have the id), use the Get Label Request API.
Gather the necessary information from the label request (such as return details, customer info, and shipping address) to generate a shipping label using your preferred carrier or label provider.

Push the label to Loop

Submit the generated label to Loop using the Create Label API.
The id field from the label request is required.
Include all relevant label details (tracking number, carrier, label file, etc.).
Once the label is pushed to Loop, it will be made available to the customer on their return status and confirmation page for printing or download.
Loop emails the label to the customer when it’s created (unless the merchant has disabled that email template) — while a label request has no label, the shopper receives no confirmation email at all, so there’s no separate timeout-based safety net.

Example request body:

{
  "label_request_id": "67329889100573",
  "tracking_number": "9400136105440512280610",
  "carrier": "usps",
  "label_url": "https://s3.amazonaws.com/example-bucket/label.pdf",
  "qrcode_url": "https://s3.amazonaws.com/example-bucket/qrcode.pdf",
  "tracking_url": "https://tools.usps.com/go/TrackConfirmAction?qtc_tLabels1=9400136105440512280610",
  "rate": {
    "amount": 50000,
    "currency_code": "USD"
  }
}

Handle errors

If you are unable to generate a label for any reason, report the error to Loop using the Create a Label Request Error API.
This records the failure against the request and surfaces it on the return’s timeline in Loop admin — see Label request lifecycle for what does (and doesn’t) happen next.

For full details on required fields and request structure, refer to the Create Label API documentation and Create a Label Request Error API documentation.

🔄 Step 3: Status Updates

To keep Loop up to date on the progress of each shipping label, you’ll need to notify Loop whenever the status of a label changes (for example: in transit, out for delivery, or delivered).

Your third-party software should include a listener or subscriber mechanism to detect when a label’s status is updated by the carrier or shipping provider.
When a status change occurs, trigger a call to the Update Label Status API to push the latest status to Loop.
The id value used in this API call comes from the 201 response of the Create Label API (i.e., after you have successfully submitted the label to Loop).
This ensures that Loop and the merchant have real-time visibility into the return shipment’s journey.

For details on required fields, supported status values, and request structure, see the Update Label Status API documentation.

🛡️ Step 4: Error Handling, Best Practices & Testing

Common Errors & Troubleshooting

Invalid or missing id field: Ensure you are passing the correct id from the label request when pushing label data or updating status (see Create Label API and Update Label Status API).
Authentication errors: Double-check that your API key is valid, has the correct scopes, and is included in each request.
Incorrect payload format: Verify that your request matches the API schema (field names, types, and required fields).
Webhook endpoint not reachable: Make sure your webhook endpoint is publicly accessible and returns a 200 OK response to Loop.
Duplicate label submissions: Implement idempotency logic to prevent sending the same label or status update multiple times.
Unprocessed label request errors: If you encounter an error generating a label, always report it using the Create a Label Request Error API — this records the failure and surfaces it to the merchant, but does not retry or re-issue the label itself.
404 Label request not found when reporting an error: This doesn’t necessarily mean the id is unknown — reporting an error against a request that’s already fulfilled or cancelled also returns this 404, because the request is already closed.

Recommendations

Retry logic: Implement retries with exponential backoff for transient network or server errors when calling Loop APIs.
Idempotency: Use idempotency keys or check for existing submissions to avoid duplicate processing of label requests or status updates.
Logging: Log all API interactions and webhook payloads for auditability and easier troubleshooting.
Security: Store API keys securely and restrict access. Validate webhook signatures to ensure authenticity.
Monitoring: Set up monitoring and alerts for failed API calls, webhook delivery issues, or unexpected errors.

Testing Your Integration

Before going live, thoroughly test your integration to ensure all functionality works as expected. Loop provides detailed testing procedures and best practices for validating your label integration. For step-by-step instructions, see the Testing Your Third Party Label Integration guide.

Reminder: Always use sandbox or test credentials/environments (if available) when testing your integration to avoid affecting live return data or triggering real customer notifications.

✅ Conclusion

Integrating with Loop’s Labels API enables seamless, automated handling of return shipping labels for merchants and partners. By following the steps in this guide—setting up prerequisites, discovering label requests, generating and submitting labels, updating statuses, and handling errors—you can ensure a smooth and reliable experience for both your team and your customers. For further details or support, refer to the official API documentation or contact Loop’s support team.

Introduction

Guides

Use Cases

Return Create

📝 Overview

🔁 Label request lifecycle

What happens when you report an error

If you poll instead of using webhooks

⚙️ Prerequisites

Accept our Label Provider Terms

Register your integration

Create a webhook via the Loop API

Configure return policies

🔍 Step 1: Discover Labels to Generate

Poll for labels

🏷️ Step 2: Generate and Push the Label

Generate the shipping label

Push the label to Loop

Handle errors

🔄 Step 3: Status Updates

🛡️ Step 4: Error Handling, Best Practices & Testing

Common Errors & Troubleshooting

Recommendations

Testing Your Integration

✅ Conclusion

​📝 Overview

​🔁 Label request lifecycle

​What happens when you report an error

​If you poll instead of using webhooks

​⚙️ Prerequisites

​Accept our Label Provider Terms

​Register your integration

​Create a webhook via the Loop API

​Configure return policies

​🔍 Step 1: Discover Labels to Generate

​Subscribe to webhooks

​Poll for labels

​🏷️ Step 2: Generate and Push the Label

​Generate the shipping label

​Push the label to Loop

​Handle errors

​🔄 Step 3: Status Updates

​🛡️ Step 4: Error Handling, Best Practices & Testing

​Common Errors & Troubleshooting

​Recommendations

​Testing Your Integration

​✅ Conclusion

📝 Overview

🔁 Label request lifecycle

What happens when you report an error

If you poll instead of using webhooks

⚙️ Prerequisites

Accept our Label Provider Terms

Register your integration

Create a webhook via the Loop API

Configure return policies

🔍 Step 1: Discover Labels to Generate

Subscribe to webhooks

Poll for labels

🏷️ Step 2: Generate and Push the Label

Generate the shipping label

Push the label to Loop

Handle errors

🔄 Step 3: Status Updates

🛡️ Step 4: Error Handling, Best Practices & Testing

Common Errors & Troubleshooting

Recommendations

Testing Your Integration

✅ Conclusion