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 and management for returns — including automatic status tracking for supported carriers.

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

carrier must be the carrier’s standard name (for example usps, fedex, ups) — never the tracking number or an internal reference — and tracking_number must be the tracking number the carrier itself issued for the shipment. Loop uses these two fields to track the shipment automatically, for supported carriers, once the label is pushed. If carrier isn’t a real carrier value, or tracking_number isn’t one that carrier recognizes, automatic tracking never starts and the label stays at status new — see Step 3 below.

Including tracking_url is strongly recommended — it gives the shopper a working tracking link on their return status page right away, even before Loop’s automatic tracking produces a status update.

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

For supported carriers, Loop automatically tracks the shipment using the carrier and tracking_number you supplied when you pushed the label in Step 2, and updates the label’s status as it moves (for example: in transit, out for delivery, or delivered). For these carriers, your integration doesn’t need to push status. For any other carrier, you must push status yourself (see below).

Automatic tracking depends on carrier and tracking_number being accurate — see Push the label to Loop above. If a label’s status is stuck at new, see Common Errors & Troubleshooting below.

Pushing status updates yourself

If Loop doesn’t track your carrier automatically, push status changes with the Update Label Status API. Otherwise the label stays at new. If you’re not sure whether your carrier is supported, ask your Loop contact before you go live.

Pushing status doesn’t turn off automatic tracking. For a supported carrier, both write the same label status, and the most recent update wins. A later automatic update can overwrite a status you pushed. For supported carriers, don’t push status.

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, call 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).

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).
Label stuck at new: This usually means one of three things. carrier isn’t a real carrier value (for example, a tracking number or internal reference was sent instead). tracking_number isn’t a tracking number that carrier recognizes. Or Loop doesn’t track the carrier automatically, and your integration hasn’t pushed status. Check carrier against the carrier’s standard name, and confirm tracking_number is what the carrier issued. If both are correct and the carrier has scanned the package, push status with the Update Label Status API.
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, tracking status, 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

Pushing status updates yourself

🛡️ 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

​Pushing status updates yourself

​🛡️ 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

Pushing status updates yourself

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

Common Errors & Troubleshooting

Recommendations

Testing Your Integration

✅ Conclusion