{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Sharing Consignee Engagement Data","siteUrl":"https://docs.bettermile.com","jsonLd":{"@context":"https://schema.org","@type":"Organization","name":"Bettermile","url":"https://bettermile.com","logo":"https://docs.bettermile.com/images/logo.png"},"description":"How tenants who run their own invites, tracking pages or feedback tools send consignee engagement data back to Bettermile via webhook."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"sharing-consignee-engagement-data","__idx":0},"children":["Sharing Consignee Engagement Data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you send your own invites, host the tracking experience in your own website or app, or collect ratings with your own"," ","tool, Bettermile no longer sees how consignees engage with their parcels. Sharing that engagement data closes the loop: it"," ","lets Bettermile measure the tracking experience end to end, compare channels, and improve ETAs and features for your"," ","consignees."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You share it by sending one request per parcel and day to the consignee engagement webhook."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-you-need-it","__idx":1},"children":["When you need it"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Share engagement data if any of the following is true for your integration:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You send the tracking invites yourself. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/tracking/shadow-orchestrate/invitations/tenant"},"children":["Invites via Tenant"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The tracking page lives in your website or app. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/tracking/shadow-orchestrate/user-interface/co-owned-experience"},"children":["Co Owned Experience"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/tracking/shadow-orchestrate/user-interface/deep-integration"},"children":["Deep Integration"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You collect ratings with a third-party or custom tool. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/tracking/shadow-orchestrate/user-feedback/third-party-tool"},"children":["3rd Party Tool"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/tracking/shadow-orchestrate/user-feedback/custom-rating"},"children":["Custom Rating"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-you-send","__idx":2},"children":["What you send"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each request describes one parcel on one day. Only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tenantId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parcelNumber"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["date"]}," are required. All other sections"," ","are optional: send only the ones you collect. For example, if you only send your own invites, send only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invites"]},"; if you"," ","only run your own feedback tool, send only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ratings"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Section"},"children":["Section"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it describes"},"children":["What it describes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invites"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The tracking invite you sent: channel, whether it was delivered, opened and clicked."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clicks"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Every visit to the tracking page or app, with the ETA window the consignee saw and how they arrived (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["utmSource"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ratings"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The rating and feedback the consignee gave, including the scale and the tool used."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["outOfHome"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An out-of-home delivery option the consignee chose, such as a parcel locker or a safe place."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["otherFeatures"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Other tracking features the consignee used, such as the map view."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/tracking/apis/consignee-engagement/consignee-engagement"},"children":["Consignee Engagement API reference"]}," lists every field, its format and the allowed values,"," ","with an example request for each section on its own."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The example below shows a tenant that sends its own invites, hosts the tracking page and collects ratings:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"tenantId\": \"gls-de\",\n \"parcelNumber\": \"P123456789\",\n \"date\": \"2026-09-16\",\n \"invites\": {\n \"createdAt\": \"2026-09-16T09:06:00Z\",\n \"inviteMedium\": \"EMAIL\",\n \"destinationUrl\": \"https://www.example.com/track/P123456789\",\n \"delivered\": true,\n \"opened\": true,\n \"clicked\": true\n },\n \"clicks\": [\n {\n \"createdAt\": \"2026-09-16T09:20:00Z\",\n \"platform\": \"WEB\",\n \"url\": \"https://www.example.com/track/P123456789?utm_source=invite-email\",\n \"etaLowerBound\": \"2026-09-16T10:15:00Z\",\n \"etaUpperBound\": \"2026-09-16T10:35:00Z\",\n \"utmSource\": \"invite-email\"\n }\n ],\n \"ratings\": {\n \"createdAt\": \"2026-09-16T12:03:00Z\",\n \"platform\": \"WEB\",\n \"scale\": \"ONE_TO_FIVE\",\n \"tool\": \"STARS\",\n \"ratingValue\": 5,\n \"feedbackMessage\": \"Perfect service!\",\n \"errors\": []\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":3},"children":["How it works"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","align":"center","diagramType":"mermaid","diagramSource":"%%{\n init: {\n 'theme': 'base',\n 'themeVariables': {\n 'fontFamily': 'Poppins, Inter, sans-serif',\n 'actorBkg': '#C0D7F4',\n 'actorBorder': '#1A31D5',\n 'actorTextColor': '#161B21',\n 'actorLineColor': '#1A31D5',\n 'signalColor': '#1A31D5',\n 'signalTextColor': '#161B21',\n 'noteBkgColor': '#F5F6FB',\n 'noteBorderColor': '#1A31D5',\n 'noteTextColor': '#161B21',\n 'activationBkgColor': '#C0D7F4',\n 'activationBorderColor': '#1A31D5',\n 'labelBoxBkgColor': '#EEF0FE',\n 'labelBoxBorderColor': '#1A31D5',\n 'labelTextColor': '#161B21',\n 'loopTextColor': '#161B21'\n }\n }\n}%%\nsequenceDiagram\n actor C as Consignee\n participant T as Tenant\n participant B as Bettermile\n T->>C: Tracking invite\n T->>+B: POST /parcel-consignee-engagement (invite)\n B-->>-T: 202 Accepted\n C->>T: Visits tracking page, rates delivery\n T->>+B: POST /parcel-consignee-engagement (invite + clicks + rating)\n B-->>-T: 202 Accepted\n note over T,B: Each request replaces the previous one
for the same parcel and day\n","diagramHtml":"BettermileTenantBettermileTenantEach request replaces the previous onefor the same parcel and dayConsigneeTracking invitePOST /parcel-consignee-engagement (invite)202 AcceptedVisits tracking page, rates deliveryPOST /parcel-consignee-engagement (invite + clicks + rating)202 AcceptedConsignee","diagramHtmlDark":"BettermileTenantBettermileTenantEach request replaces the previous onefor the same parcel and dayConsigneeTracking invitePOST /parcel-consignee-engagement (invite)202 AcceptedVisits tracking page, rates deliveryPOST /parcel-consignee-engagement (invite + clicks + rating)202 AcceptedConsignee"},"children":["%%{\n init: {\n 'theme': 'base',\n 'themeVariables': {\n 'fontFamily': 'Poppins, Inter, sans-serif',\n 'actorBkg': '#C0D7F4',\n 'actorBorder': '#1A31D5',\n 'actorTextColor': '#161B21',\n 'actorLineColor': '#1A31D5',\n 'signalColor': '#1A31D5',\n 'signalTextColor': '#161B21',\n 'noteBkgColor': '#F5F6FB',\n 'noteBorderColor': '#1A31D5',\n 'noteTextColor': '#161B21',\n 'activationBkgColor': '#C0D7F4',\n 'activationBorderColor': '#1A31D5',\n 'labelBoxBkgColor': '#EEF0FE',\n 'labelBoxBorderColor': '#1A31D5',\n 'labelTextColor': '#161B21',\n 'loopTextColor': '#161B21'\n }\n }\n}%%\nsequenceDiagram\n actor C as Consignee\n participant T as Tenant\n participant B as Bettermile\n T->>C: Tracking invite\n T->>+B: POST /parcel-consignee-engagement (invite)\n B-->>-T: 202 Accepted\n C->>T: Visits tracking page, rates delivery\n T->>+B: POST /parcel-consignee-engagement (invite + clicks + rating)\n B-->>-T: 202 Accepted\n note over T,B: Each request replaces the previous one
for the same parcel and day\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"send-snapshots-not-changes","__idx":4},"children":["Send snapshots, not changes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each request is a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["snapshot"]},": the complete state of one parcel on one day, not what changed since your last request."," ","Whenever something new happens, send everything you know about the parcel and day again, including all earlier clicks."," ","A later request for the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parcelNumber"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["date"]}," replaces the earlier one, so if you collect several sections, send"," ","them together in each request rather than one section per request."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This also makes retries safe: sending the same snapshot twice has no side effects."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You decide when to send. Sending after every new event gives Bettermile the most current picture; sending once at the end of"," ","the delivery day is also fine, as long as the snapshot is complete."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authentication","__idx":5},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Requests are authenticated with an API key in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," header. Bettermile issues one key per tenant; request it from"," ","your Bettermile representative. The tenant is taken from the key, so keep it secret and use it only from your backend."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://data-solutions.bettermile.com/parcel-consignee-engagement \\\n -H \"x-api-key: $BETTERMILE_ENGAGEMENT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d @engagement.json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"validation","__idx":6},"children":["Validation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The request body is validated strictly. Every object is closed, so a field that is not part of the"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/tracking/apis/consignee-engagement/consignee-engagement"},"children":["schema"]}," is rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},", as is a wrongly formatted ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["date"]}," or a value"," ","outside the allowed range. If you want to send data that does not fit the schema yet, contact Bettermile first so the field"," ","can be added."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"responses-and-retries","__idx":7},"children":["Responses and retries"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP status"},"children":["HTTP status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What to do"},"children":["What to do"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Accepted for storage."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Nothing. Do not retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The body failed validation."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fix the request. Do not retry it unchanged."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The API key is missing, unknown or not allowed to send engagement data."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," header. Do not retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Throttled."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry with exponential backoff and jitter."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Temporary failure."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry with exponential backoff and jitter."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Successful and throttled responses include a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requestId"]},". Log it and quote it when contacting Bettermile about a request."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":8},"children":["Best practices"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Send only what you collect."]}," Leave out sections you have no data for instead of sending them empty."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Always send the full snapshot."]}," A request with only the newest click replaces the earlier clicks for that parcel and day."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use UTC timestamps"]}," in ISO 8601 format, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2026-09-16T09:06:00Z"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use the documented values"]}," for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scale"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tool"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["utmSource"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["outOfHome.type"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["featureType"]},", so your data can be compared with that of other channels and tenants."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use the same UTM sources as in your invites"]},", for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["utm_source=invite-email"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["utm_source=invite-sms"]},". See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/tracking/shadow-orchestrate/invitations/tenant"},"children":["Invites via Tenant"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry only on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]}]},", with exponential backoff and jitter. Retrying on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}," will not succeed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Test in the development environment first."]}," Ask your Bettermile representative for a development API key."]}]}]},"headings":[{"value":"Sharing Consignee Engagement Data","id":"sharing-consignee-engagement-data","depth":1},{"value":"When you need it","id":"when-you-need-it","depth":2},{"value":"What you send","id":"what-you-send","depth":2},{"value":"How it works","id":"how-it-works","depth":2},{"value":"Send snapshots, not changes","id":"send-snapshots-not-changes","depth":3},{"value":"Authentication","id":"authentication","depth":3},{"value":"Validation","id":"validation","depth":3},{"value":"Responses and retries","id":"responses-and-retries","depth":3},{"value":"Best practices","id":"best-practices","depth":2}],"frontmatter":{"title":"Sharing Consignee Engagement Data","rbac":{"anonymous":"read","authenticated":"read"},"seo":{"description":"How tenants who run their own invites, tracking pages or feedback tools send consignee engagement data back to Bettermile via webhook.","title":"Sharing Consignee Engagement Data"}},"lastModified":"2026-10-12T15:13:34.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/tracking/shadow-orchestrate/consignee-engagement","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}