Note: This feature is currently in Beta, so you will need to let your Merchant Success Manager or support@loopreturns.com know that you’d like to enable this feature.

​
📝 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:

​
Create webhooks

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

  • In the Loop admin, navigate to Returns management → Tools & integrations → Developer tools.
  • Click “Create webhook” and set up these webhooks:
    • Event: Label request.issued
      Response: Label request
      URL: Provided by your third party label partner
    • Event: Label request.cancelled
      Response: Label request
      URL: Provided by your third party label partner
  • If your label partner requires your webhook secret, you can find it at the bottom of the Webhooks table in Loop admin.

​
Generate an API key

  • In the Loop admin, navigate to Returns management → Tools & integrations → Developer tools.
  • Scroll to API keys and click Generate API key.
  • Select these scopes:
    • Return
    • Developer Tools
    • Destinations (read)
    • Destinations (write)
    • Labels (read)
    • Labels (write)
    • Label Generation Requests (read)
    • Label Generation Requests (write)
  • Give the API key a descriptive name and click Generate.
  • Copy the API key and share it securely with your label partner if needed.

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

Best Practice: 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.

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

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.

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

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

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

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

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.