Fulfillment webhook events

Guide to integrating with ReturnBear's fulfillment webhook events

Fulfillment Webhook Events

A fulfillment request is a request to ship a specific set of items belonging to a fulfillment order. This may be inventory items or return cases. Here are the webhook events which can be currently subscribed to:

fulfillment/tracking_status_updated

• Description: Triggered when a fulfillment order request's tracking status changes as the shipment moves through the fulfillment process.

• Status Progression:

  1. READY_FOR_SHIPPING: The shipment has been prepared and is ready to be picked up by the carrier from the ReturnBear hub
  2. IN_TRANSIT: The shipment has been picked up by the carrier and is in transit to its destination
  3. DELIVERED: The shipment has been successfully delivered to the intended recipient
  4. DELAYED: The shipment has encountered an issue causing a delay in delivery

• Key Fields to Monitor:

  • tracking_status: Current status of the shipment
  • tracking_events: Historical timeline of status changes with location information

In the case of a cross-border shipment, the webhook payload will contain a commercial invoice in documents array. For all shipments, the webhook payload will contain a shipping manifest and packing slips.

All fulfillment related events have a payload that contains Fulfillment model properties and follow the schema below:

JSON

{
  // The webhook subscription id generated by Retrunbear
  "id": 33783993003,
  // The webhook event
  "event": "fulfillment/tracking_status_updated",
  // The timestamp at which webhook event was sent
  "timestamp": "2024-03-20T15:30:00Z",
  "data": {
    // Status of the shipment (READY_FOR_SHIPPING/IN_TRANSIT/DELAYED/DELIVERED)
    "tracking_status": "READY_FOR_SHIPPING",
    // Description of the shipment status. For delayed shipments, this will contain the reason for the delay.
    "description": "Ready for Shipping",
    // Tracking number of the shipment. Note that this is not always available
    // and may be null for LTL shipments.
    "tracking_number": "1234567890",
    // Courier used for the shipment if available.
    "courier": "UPS",
    // Unique identifier generated by ReturnBear for a fulfillment request.
    "id": "01JBVTTP55Z7YVJANCBVTJ82ZA",
    // Timestamp at which the shipment even occurred
    "occurred_at": "2024-11-05T14:37:53.000000Z",
    // All returns belonging to the shipment. More details on this can be found in the content of documents below.
    "returns": [
      {
        // Unique identifier generated by ReturnBear for the return case.
        // This can be used as a tracking number for the return case when using ReturnBear for reverse logistics.
        "short_uid": "RB-1936EE",
        // External ID generated by e-commerce platform (i.e. Shopify in most cases)
        "external_references": [
          {
            "type": "SHOPIFY_RETURN_GID",
            "value": "gid://shopify/Return/7393739105"
          }
        ]
      }
      // ... additional returns omitted for brevity ...
    ],
    // All required shipment documents will be available here.
    // Note that there is always only one document of specific type generated for a shipment.
    // COMMERCIAL_INVOICE document is only available for cross-border shipments.
    // EPOST document detailing requirements for CBSA will be present for cross-border shipments involving Canada.
    // US_ENTRY will be present for cross-border shipments entering the US.
    // SHIPPING_MANIFEST will be present for all shipments.
    "documents": [
      {
        "type": "SHIPPING_MANIFEST",
        // The MIME type of the document.
        "content_type": "application/pdf",
        // Pre-signed downloadable URL with an expiry of 7 days.
        "url": "https://example.amazonaws.com/shipping_manifests/shipping_manifest_01JBVTTP55Z7YVJANCBVTJ82ZA.pdf?...",
        // The expiry date of the URL.
        "expiry_date": "2025-01-14T20:08:47.000000Z"
      },
      {
        "type": "COMMERCIAL_INVOICE",
        // The MIME type of the document.
        "content_type": "application/pdf",
        // Pre-signed downloadable URL with an expiry of 7 days.
        "url": "https://example.amazonaws.com/commercial_invoices/commercial_invoice_01JBVTTP55Z7YVJANCBVTJ82ZA.pdf?...",
        "expiry_date": "2025-01-14T20:10:10.000000Z"
      }
    ],
    // History of tracking events which outline the fulfillment request's physical movement through the fulfillment process
    "tracking_events": [
      {
        "status": "READY_FOR_SHIPPING",
        "occurred_at": "2024-07-18T12:00:00Z",
        "origin_location": {
          "city": "Mississauga",
          "country_code": "CA",
          "postal_code": "L5T 1C1",
          "name": "ReturnBear Hub"
        }
      },
      {
        "status": "IN_TRANSIT",
        "occurred_at": "2024-07-19T14:00:00Z",
        "origin_location": {
          "city": "Mississauga",
          "country_code": "CA",
          "postal_code": "L5T 1C1",
          "name": "ReturnBear Hub"
        }
      },
      {
        "status": "DELIVERED",
        "occurred_at": "2024-07-20T16:00:00Z",
        "origin_location": {
          "city": "Los Angeles",
          "country_code": "US",
          "postal_code": "90028",
          "name": "Skims Body"
        }
      }
    ],
  }
}