Third Party Labels

​

📝 Overview

​

⚙️ Prerequisites

​

Accept our Label Provider Terms

​

Register your integration

​

Create a webhook via the Loop API

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

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

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

​

Poll for labels

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

• 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

​

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.

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

• 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

​

✅ Conclusion