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.

​

⚙️ Prerequisites

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

​

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.

​

Create a webhook via the Loop API

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();

​

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:

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

​

Subscribe to webhooks

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.

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.

​

Poll for labels

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

• This endpoint allows you to retrieve all label requests that are pending action, so your integration can process and generate labels as needed.
• 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.

​

🏷️ 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.
• If a label is not generated within a certain timeframe, Loop will also email the label to the customer when it becomes available.

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",
  "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 ensures Loop is aware of any issues and can update the return accordingly.

​

🔄 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, delivered, or failed delivery).

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

​

🛡️ 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 so Loop can update the return accordingly.

​

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.

​

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