{
  "topic": "ship-by-loop.shipment",
  "trigger": "ship-by-loop.services.requested",
  "shop_id": 4321,
  "shipment": {
    "id": "ff8a4470-41e0-4cc3-9bfe-44564f4286b7",
    "type": "return",
    "status": "draft",
    "origin": {
      "name": "Jane Shopper",
      "address1": "123 Main Street",
      "address2": null,
      "city": "Columbus",
      "state": "OH",
      "zip": "43215",
      "country": "US",
      "email": "jane@example.com",
      "phone": "5555555555"
    },
    "destination": {
      "name": "Returns Processing",
      "address1": "500 Industrial Pkwy",
      "address2": null,
      "city": "Reno",
      "state": "NV",
      "zip": "89501",
      "country": "US",
      "email": "returns@example.com",
      "phone": "5555550199"
    },
    "outbound_order": {
      "order_number": "#1001",
      "carrier": "USPS",
      "tracking_number": "1Z888",
      "total_value": {
        "value": 4565,
        "currency": "USD"
      },
      "shipped_date": "2026-08-01T14:32:00+00:00",
      "commercial_invoice_number": null
    },
    "packages": [
      {
        "id": "900a8671-35ad-4743-9b6c-2540d3bb1faf",
        "dimensions": {
          "length": 12,
          "width": 9,
          "height": 4,
          "unit": "in"
        },
        "weight": {
          "value": 24,
          "unit": "oz"
        },
        "items": [
          {
            "id": "3c6e9d0a-9b1a-4e9f-8c3e-5a2b1d4f6e7a",
            "name": "Classic Tee",
            "sku": "SKU1234567890",
            "country_of_origin": "US",
            "hs_code": "6109.10.00",
            "weight": {
              "value": 8,
              "unit": "oz"
            },
            "price": {
              "value": 2800,
              "currency": "USD"
            }
          }
        ],
        "service": null,
        "label_url": null,
        "qr_code_url": null,
        "tracking_number": null
      }
    ]
  }
}

Webhook Payloads

Ship by Loop shipment

Trigger	What it means
`ship-by-loop.services.requested`	A shipment was created that this provider can fulfill.
`ship-by-loop.purchase.requested`	Services have been selected and are ready for purchase.
`ship-by-loop.cancellation.requested`	The shipment was cancelled.

ship-by-loop.services.requested: submit the services this provider can offer for the shipment’s packages with POST /ship-by-loop/shipments/{shipmentId}/services. The shopper-facing portal polls for a response roughly every 5 seconds, up to 12 times (roughly 30-60 seconds total). If nothing arrives in that window, the shopper falls back to whichever standard (non-carrier-choice) return methods were already available — no error is shown. The API still accepts a POST .../services call after that window, but the portal has stopped polling for it by then, so the shopper who already fell back will not see it.
ship-by-loop.purchase.requested: record the resulting purchase, including tracking and label details, with POST /ship-by-loop/shipments/{shipmentId}/orders.
ship-by-loop.cancellation.requested: stop any work in progress for this shipment and void/refund any carrier label already purchased. Loop does not expect a response beyond the 200 acknowledgement.

Acknowledge every delivery with a 200 response.

Package field state by trigger

service, label_url, qr_code_url, and tracking_number on each packages entry are populated over the lifetime of a shipment rather than all at once:

Trigger	`service`	`label_url`	`qr_code_url`	`tracking_number`
`services.requested`	`null`	`null`	`null`	`null`
`purchase.requested`	set	`null`	`null`	`null`
`cancellation.requested`	see below	see below	see below	see below

service is null at services.requested (nothing has been chosen yet) and always set by purchase.requested — Loop only asks a provider to purchase once every package has a service selected. label_url / qr_code_url / tracking_number stay null through both of those triggers; they’re populated only once the provider calls POST .../orders, which happens after purchase.requested is received. For cancellation.requested, every field reflects whatever had already been recorded before the cancellation — null for any of them the provider hadn’t gotten to yet.

WEBHOOK

ShipByLoopShipment

{
  "topic": "ship-by-loop.shipment",
  "trigger": "ship-by-loop.services.requested",
  "shop_id": 4321,
  "shipment": {
    "id": "ff8a4470-41e0-4cc3-9bfe-44564f4286b7",
    "type": "return",
    "status": "draft",
    "origin": {
      "name": "Jane Shopper",
      "address1": "123 Main Street",
      "address2": null,
      "city": "Columbus",
      "state": "OH",
      "zip": "43215",
      "country": "US",
      "email": "jane@example.com",
      "phone": "5555555555"
    },
    "destination": {
      "name": "Returns Processing",
      "address1": "500 Industrial Pkwy",
      "address2": null,
      "city": "Reno",
      "state": "NV",
      "zip": "89501",
      "country": "US",
      "email": "returns@example.com",
      "phone": "5555550199"
    },
    "outbound_order": {
      "order_number": "#1001",
      "carrier": "USPS",
      "tracking_number": "1Z888",
      "total_value": {
        "value": 4565,
        "currency": "USD"
      },
      "shipped_date": "2026-08-01T14:32:00+00:00",
      "commercial_invoice_number": null
    },
    "packages": [
      {
        "id": "900a8671-35ad-4743-9b6c-2540d3bb1faf",
        "dimensions": {
          "length": 12,
          "width": 9,
          "height": 4,
          "unit": "in"
        },
        "weight": {
          "value": 24,
          "unit": "oz"
        },
        "items": [
          {
            "id": "3c6e9d0a-9b1a-4e9f-8c3e-5a2b1d4f6e7a",
            "name": "Classic Tee",
            "sku": "SKU1234567890",
            "country_of_origin": "US",
            "hs_code": "6109.10.00",
            "weight": {
              "value": 8,
              "unit": "oz"
            },
            "price": {
              "value": 2800,
              "currency": "USD"
            }
          }
        ],
        "service": null,
        "label_url": null,
        "qr_code_url": null,
        "tracking_number": null
      }
    ]
  }
}

Body

application/json

The envelope delivered on every Ship by Loop webhook

topic

string

required

Allowed value: "ship-by-loop.shipment"

trigger

enum<string>

required

The event that produced this delivery

Available options:

ship-by-loop.services.requested,

ship-by-loop.purchase.requested,

ship-by-loop.cancellation.requested

Example:

"ship-by-loop.services.requested"

shop_id

integer

required

The Loop shop the shipment belongs to

Example:

4321

shipment

object

required

Show child attributes

Response

200

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