{
  "topic": "label.request",
  "id": 6340,
  "return_id": 1001,
  "shop_id": 50,
  "created_at": "2023-11-07T05:31:56Z",
  "addresses": {
    "origin": {
      "name": "Alice Returns",
      "address1": "123 Example Rd",
      "company": "Example Co.",
      "address2": "Apt A",
      "city": "Columbus",
      "state": "Ohio",
      "zip": "43215",
      "country": "United States",
      "country_code": "US",
      "phone": "12345678901"
    },
    "destination": {
      "name": "My Domestic Warehouse",
      "address1": "123 Commerce St",
      "company": "Ecommerce Inc.",
      "address2": "Ste 100",
      "city": "Columbus",
      "state": "Ohio",
      "zip": "43215",
      "country": "United States",
      "country_code": "US",
      "phone": "12345678901"
    }
  },
  "parcel": {
    "height": 5,
    "width": 10.9,
    "length": 20.2,
    "weight": 65.9
  },
  "products": [
    {
      "name": "Green T-Shirt",
      "sku": "tshirt-g-2314-L",
      "hs_code": "61051000",
      "country_of_origin": "US",
      "price": {
        "amount": 100,
        "currency": "USD"
      }
    }
  ]
}

Webhook Payloads

Label requests

Trigger	What it means
`label.request.issued`	Loop needs a label for this return.
`label.request.cancelled`	A previously issued label request was cancelled.

label.request.issued: the id in the payload is the label request ID. Use it to create the label with POST /labels, or, if label generation fails on your end, to report the failure with POST /label-requests/{id}/errors.
label.request.cancelled: for example, a merchant regenerated the label, or the return itself was cancelled. Stop any work in progress for this id and void/refund the carrier label if one was already purchased. The id is never reused: a regenerated label arrives as a brand-new label.request.issued event with a new id.

Acknowledge every delivery with a 200 response. A non-200 response is not how you report a label-generation failure — failures are reported with POST /label-requests/{id}/errors. Reporting an error does not cause Loop to resend the webhook or issue a new label request: the request remains issued and stays fulfillable via POST /labels with the same id, so retrying is your integration’s own responsibility.

WEBHOOK

LabelRequests

{
  "topic": "label.request",
  "id": 6340,
  "return_id": 1001,
  "shop_id": 50,
  "created_at": "2023-11-07T05:31:56Z",
  "addresses": {
    "origin": {
      "name": "Alice Returns",
      "address1": "123 Example Rd",
      "company": "Example Co.",
      "address2": "Apt A",
      "city": "Columbus",
      "state": "Ohio",
      "zip": "43215",
      "country": "United States",
      "country_code": "US",
      "phone": "12345678901"
    },
    "destination": {
      "name": "My Domestic Warehouse",
      "address1": "123 Commerce St",
      "company": "Ecommerce Inc.",
      "address2": "Ste 100",
      "city": "Columbus",
      "state": "Ohio",
      "zip": "43215",
      "country": "United States",
      "country_code": "US",
      "phone": "12345678901"
    }
  },
  "parcel": {
    "height": 5,
    "width": 10.9,
    "length": 20.2,
    "weight": 65.9
  },
  "products": [
    {
      "name": "Green T-Shirt",
      "sku": "tshirt-g-2314-L",
      "hs_code": "61051000",
      "country_of_origin": "US",
      "price": {
        "amount": 100,
        "currency": "USD"
      }
    }
  ]
}

Body

application/json

topic

string

The webhook topic.

Example:

"label.request"

trigger

enum<string>

The event that triggered the webhook.

Available options:

label.request.issued,

label.request.cancelled

integer

The Loop label request ID.

Example:

6340

return_id

integer

The Loop return ID.

Example:

1001

shop_id

integer

The unique identifier of the shop that created the webhook.

Example:

50

created_at

string<date-time>

The date and time at which the request was created, using the ISO 8601 date format.

addresses

object

The origin and destination addresses of the label.

Show child attributes

parcel

object

The dimensions, weight, and contents of the parcel.

Show child attributes

products

object[]

Details about the products returned in the parcel.

Show child attributes

Response

200

Return a 200 status to indicate that the data was received successfully.