Skip to main content

Resources and actions

Shipmondo supports the following resources:

  • orders
  • shipments
  • shipment drafts
  • shipment monitor (used for tracking delivery status changes).

Each of the resources have a list of supported actions that triggers an event. All of the actions for a resource result in a payload with the same format. Below are some examples of the payloads of the events that the webhooks will send.

Sales Order​

The Sales Order resource is an representation of orders, and provides a way of picking, packing, and creating shipments. It can be used to keep track of the state of your orders, whenever changes are made.

You can subscribe to the following actions:

  • Created: Triggered when a new sales order is created.
  • Update status: Fires when the status of a sales order is updated (e.g., from "processing" to "shipped").
  • Fulfillment created: Occurs when a fulfillment record is created for an order, indicating the order is being prepared.
  • Shipment created: Triggered when a shipment is created, signaling the order is ready to be dispatched.
  • Payment captured: Fires when the payment for an order is successfully captured.
  • Payment refunded: Triggered when a payment is refunded for an order.
  • Payment voided: Occurs when a payment is voided, i.e., authorization on the payment was canceled before the funds were captured
  • Deleted: Fires when a sales order is deleted from the system.

You can read more about the sales order structure here

{
  "webhook": "Sales Order",
  "data": {
    "id": 83837161,
    "order_id": "56623",
    "ordered_at": "2024-07-08T10:08:32.000+02:00",
    "order_status": "open",
    "fulfillment_status": "fulfilled",
    "payment_status": "authorized",
    "shipped_percent": 0,
    "fulfilled_percent": 100,
    "archived": false,
    "source_name": "Min Virksomhed ApS",
    "order_note": null,
    "created_at": "2024-07-08T10:08:58.541+02:00",
    "updated_at": "2024-07-08T10:08:58.541+02:00",
    "ship_to": {
      "name": "Lene Hansen",
      "attention": null,
      "address1": "Skibhusvej 52",
      "address2": null,
      "zipcode": "5000",
      "city": "Odense C",
      "country_code": "DK",
      "email": "lene@email.dk",
      "mobile": "70 40 04 07",
      "phone": "70 40 04 07",
      "instruction": null,
      "vat_id": null,
      "address_validation": {
        "state": null,
        "suggestion": null
      }
    },
    "bill_to": {
      "name": "Lene Hansen",
      "attention": null,
      "address1": "Skibhusvej 52",
      "address2": null,
      "zipcode": "5000",
      "city": "Odense C",
      "country_code": "DK",
      "email": "lene@email.dk",
      "mobile": "70400407",
      "phone": "70400407"
    },
    "service_point": {
      "id": "99333",
      "name": "Kvickly Skibhusvej",
      "address1": "Skibhusvej 70A",
      "zipcode": "5000",
      "city": "Odense C",
      "country_code": "DK",
      "shipping_agent": "gls"
    },
    "sender": {
      "name": "Min Virksomhed ApS",
      "address1": "Hvilehøjvej 25",
      "address2": null,
      "zipcode": "5220",
      "city": "Odense SØ",
      "country_code": "DK",
      "email": "info@minvirksomhed.dk",
      "telephone": "70400407",
      "mobile": "70400407"
    },
    "payment_details": {
      "amount_excluding_vat": "1015.0",
      "amount_including_vat": "1268.75",
      "authorized_amount": "1268.75",
      "captured_amount": null,
      "refunded_amount": null,
      "currency_code": "DKK",
      "vat_amount": "253.75",
      "vat_percent": "0.25",
      "payment_method": "Bambora",
      "transaction_id": "373998052"
    },
    "order_lines": [
      {
        "id": 1234567810,
        "line_type": "item",
        "item_name": "T-Shirt",
        "item_sku": "TS001-WH",
        "item_variant_code": "White",
        "item_barcode": null,
        "quantity": "2.0",
        "unit_price_excluding_vat": "500.0",
        "discount_amount_excluding_vat": "0.0",
        "amount_excluding_vat": "1000.0",
        "amount_including_vat": "1250.0",
        "vat_amount": "250.0",
        "vat_percent": "0.25",
        "currency_code": "DKK",
        "shipped_quantity": "0.0",
        "unit_weight": 350,
        "cost_price": null,
        "country_code_of_origin": null,
        "customs_code": null,
        "customs_description": null,
        "image_url": null,
        "item_bin": "100",
        "item_id": 12345678
      },
      {
        "id": 1234567811,
        "line_type": "shipping",
        "item_name": "GLS PakkeShop",
        "item_sku": "shipping",
        "item_variant_code": null,
        "item_barcode": null,
        "quantity": "1.0",
        "unit_price_excluding_vat": "15.0",
        "discount_amount_excluding_vat": "0.0",
        "amount_excluding_vat": "15.0",
        "amount_including_vat": "18.75",
        "vat_amount": "3.75",
        "vat_percent": "0.25",
        "currency_code": "DKK",
        "shipped_quantity": "0.0",
        "unit_weight": null,
        "cost_price": null,
        "country_code_of_origin": null,
        "customs_code": null,
        "customs_description": null,
        "image_url": null,
        "item_bin": null,
        "item_id": 12345679
      }
    ],
    "order_fulfillments": [
      {
        "id": 12345678,
        "code": "56623-1",
        "type": "outbound",
        "shipment_id": null,
        "fulfilled_by_third_party": false,
        "order_packaging_id": null,
        "cancelled": false,
        "created_at": "2024-07-08T10:16:55.314+02:00",
        "updated_at": "2024-07-08T10:16:55.314+02:00",
        "fulfillment_lines": [
          {
            "id": 12345678,
            "shipped_quantity": "2.0",
            "order_line_id": 1234567810
          }
        ]
      }
    ]
  },
  "url": "https://example.com/webhook"
}

Shipment​

The Shipment resource is the representation of carrier-booked shipping, and can be used to track what and where you ship.

You can subscribe to the following actions:

  • Shipment created: Triggered when new shipment is successfully created.
  • Shipment cancelled: Triggered when an existing shipment is canceled

You can read more about the shipment structure here

{
  "webhook": "Shipment",
  "data": {
    "id": 123456789,
    "created_at": "2024-06-20T11:14:55.639+02:00",
    "updated_at": "2024-06-20T11:14:55.700+02:00",
    "carrier_code": "gls",
    "description": "ShopDelivery",
    "contents": null,
    "product_id": 54,
    "services": "15",
    "price": "50.00",
    "reference": null,
    "order_id": null,
    "pkg_no": "012345678910",
    "receiver": {
      "name": "Lene Hansen",
      "attention": null,
      "address1": "Skibhusvej 52",
      "address2": "",
      "zipcode": "5000",
      "city": "Odense C",
      "country_code": "DK",
      "vat_id": null,
      "email": "lene@email.dk",
      "mobile": "12345678",
      "telephone": null,
      "instruction": null,
      "access_code": null,
      "date": "2024-06-20",
      "from_time": null,
      "to_time": null,
      "member_id": null
    },
    "sender": {
      "name": "Min Virksomhed ApS",
      "attention": null,
      "address1": "Hvilehøjvej 25",
      "address2": "",
      "zipcode": "5220",
      "city": "Odense SØ",
      "country_code": "DK",
      "vat_id": null,
      "email": "info@minvirksomhed.dk",
      "mobile": "12345678",
      "telephone": "12345678"
    },
    "parcels": [
      {
        "quantity": 1,
        "weight": 1000,
        "content": null,
        "package_type": null,
        "pkg_no": "012345678910",
        "pkg_nos": [
          "012345678910"
        ],
        "weight_kg": "1.0",
        "dangerous_goods": []
      }
    ],
    "service_point": {
      "id": "99333",
      "name": "Kvickly Skibhusvej",
      "address1": "Skibhusvej 70A",
      "address2": "Pakkeshop: 99333",
      "zipcode": "5000",
      "city": "Odense C",
      "country_code": "DK",
      "shipping_agent": "gls"
    },
    "pick_up": {
      "name": null,
      "attention": null,
      "address1": null,
      "address2": null,
      "zipcode": null,
      "city": null,
      "country_code": null,
      "telephone": null,
      "phone": null,
      "date": null,
      "instruction": null,
      "from_time": null,
      "to_time": null,
      "pickup_custom": false
    },
    "paperless_trade": false,
    "pallet_exchange": {
      "pallets1": null,
      "pallets2": null,
      "pallets4": null
    },
    "source_id": null,
    "source_type": "manual",
    "return_shipment_id": null,
    "origin_shipment_id": null
  },
  "url": "https://example.com/webhook"
}

Drafts​

The Drafts resource is representation of a shipment draft, which can be used to create a shipment. It can be used to track the usage or deletion of drafts.

You can subscribe to the following actions:

  • Draft created: Triggered when a new draft is created in the system.
  • Draft deleted: Triggered when a draft is deleted.
  • Shipment created based on a draft: Triggered when a shipment is generated from a draft.

You can read more about the draft structure here

{
  "webhook": "Draft",
  "data": {
    "id": 12345678,
    "carrier_code": "gls",
    "product_code": null,
    "service_codes": null,
    "sms_notification": null,
    "email_notification": null,
    "order_id": "12345",
    "reference": "12345",
    "source": "minvirksomhed.dk",
    "shop_integration_id": 12345,
    "archived": false,
    "label_created": true,
    "created_at": "2024-07-08T10:09:01.049+02:00",
    "updated_at": "2024-07-08T10:29:25.105+02:00",
    "receiver": {
      "name": "Lene Hansen",
      "attention": null,
      "address1": "Skibhusvej 52",
      "address2": "",
      "zipcode": "5000",
      "city": "Odense C",
      "country_code": "DK",
      "email": "lene@email.dk",
      "mobile": "70 40 04 07",
      "telephone": "70 40 04 07",
      "instruction": null,
      "access_code": null
    },
    "sender": {
      "name": "Min Virksomhed ApS",
      "attention": null,
      "address1": "Hvilehøjvej 25",
      "address2": null,
      "zipcode": "5220",
      "city": "Odense SØ",
      "country_code": "DK",
      "email": "info@minvirksomhed.dk",
      "mobile": "12345678",
      "telephone": "12345678"
    },
    "service_point": {
      "id": "99333",
      "name": "Kvickly Skibhusvej",
      "address1": "Skibhusvej 70A",
      "zipcode": "5000",
      "city": "Odense C",
      "country_code": "DK",
      "shipping_agent": "gls"
    }
  },
  "url": "https://example.com/webhook"
}

Shipment Monitor​

The Shipment Monitor resource represents the tracking status of one shipment, and provides a way of tracking the current status of your shipments.

Shipment Monitor fetches the carrier's tracking events for a shipment about once a day, starting 8 hours after the shipment was created. It stops when the parcel is delivered, or when the monitoring period for the carrier and route runs out (14 days after the shipment was created, unless the carrier and route have their own limit). DHL Express, and DSV Road (db_schenker) shipments within Denmark, are imported every hour, so events for those can arrive between the daily checks. A webhook is only sent when new tracking events arrive, so a check with no new events sends nothing.

You can subscribe to the following actions:

  • Latest: Triggered whenever new tracking events arrive for the shipment, even when current_status does not change. The payload contains the most recent status of the shipment.
  • Delivered: Triggered when a delivery event arrives. A delivery sends both a Latest and a Delivered event.

The id of the payload, also sent in the SMD-Resource-Id header, is the ID of the Shipment Monitor entry, not of the shipment. The shipment's ID is shipment_id.

weight, length, height and width are the carrier's own text from its tracking, usually with a unit (for example "2.5 kg"), or null when the carrier doesn't report them. location, city and country_code come from the tracking event the payload is about, and are null when the carrier doesn't report them.

Statuses​

current_status tells you where the shipment is. It comes from the carrier's most recent tracking event, mapped to one of the following statuses so it means the same for every carrier:

  • GENERAL: A tracking event that doesn't match any of the other statuses, such as a customs or clearance delay.
  • INFORMED: The carrier has received the shipment information, but has not yet received the parcel.
  • EN_ROUTE: The carrier has the parcel, and it is moving through the carrier's network, for example picked up, sorted at a terminal or out for delivery. A failed delivery attempt also has this status, because the parcel is still in transit.
  • AVAILABLE_FOR_DELIVERY: The parcel has reached its final location, usually a service point, and is waiting to be collected by the receiver.
  • DELIVERED: The parcel has been delivered to the receiver, or collected from the service point.
  • PICKUP_REQUESTED: The carrier has registered a request to collect the parcel, but has not yet collected it.

States​

current_state tells you whether the shipment is progressing as expected. Shipment Monitor works out the state from the shipment's tracking events and the expected transit times for the carrier and route:

  • NEUTRAL: Shipment Monitor has not assessed the shipment. This is the state before the shipment is on its way, when the shipment can't be monitored (for example because it was cancelled at the carrier), and always for carriers and routes where Shipment Monitor does not assess the state, even after delivery.
  • PROGRESSING: The parcel is on its way and within the expected transit time.
  • WARNING: The shipment is delayed. Either the carrier has not received the parcel more than 5 days after the shipment was created, the parcel has been in transit longer than expected, or it has waited at the service point longer than expected.
  • DANGER: The shipment has a problem, because a delay has passed a stricter limit than for WARNING. The parcel may be stuck or lost, or may soon be returned because it was not collected.
  • SUCCESS: The parcel has been delivered. For carriers and routes where Shipment Monitor does not assess the state, a delivered shipment stays NEUTRAL instead, so use current_status to tell whether a shipment has been delivered.

WARNING and DANGER are only set for accounts whose subscription includes Shipment Monitor, and never for DHL Express.

Example​

{
  "webhook": "Shipment Monitor",
  "data": {
    "id": 98765432,
    "shipment_id": 123456789,
    "current_status": "DELIVERED",
    "current_state": "SUCCESS",
    "current_status_text": "Your package has been delivered.",
    "current_status_registered_at": "2024-06-21T07:59:00.000+02:00",
    "carrier_code": "gls",
    "carrier_track_id": "012345678910",
    "weight": "2.5 kg",
    "length": null,
    "height": null,
    "width": null,
    "location": null,
    "city": "Odense SØ",
    "country_code": "DK"
  },
  "url": "https://example.com/webhook"
}