Unified Shipping Module - Data Model
Types used in configuration options
Contents
- ShippingOption
- PickupShippingOption
- ServiceLevelShippingOption
- PorterbuddyShippingOption
- ShippingLocation
- ShippingServiceLevel
- Price
- DeliveryWindow
- DeliveryTime
- ShippingCategory
- SelectedShipping
- SelectedPorterbuddyOption
- RecipientInfo
- CheckoutCallbacks
Type Reference
Fields marked in bold are required (i.e. always defined for types that are output from the module).
ShippingOption
A ShippingOption configures the look of a user selectable simple shipping option, without a location or selectable delivery windows
| Key | Type | Allowed values | Description |
|---|---|---|---|
| id | string | Unique identifier for the shipping option | |
| name | string | Name of the shipping option to be displayed | |
| price | Price | Price for the shipping option, if not specified, free is assumed | |
| description | string | Additional description for the shipping text, displayed below the delivery time if specified | |
| deliveryTime | DeliveryTime | When the order will be delivered. See the type documentation for the available formats. | |
| logoUrl | string | A url to a logo image to be displayed for the shipping option. Maximum displayable logo size is 70x37 px. The logo url can be specified as relative to the embedding host, or absolute | |
| additionalData | any | Any arbitrary data that should be returned when the option is selected. This data is not used by the checkout anywhere, it is just passed through as-is. | |
| updateInterval | number | Interval for periodic updates of this shipping option in seconds. Periodic updates will only be performed if an update handler function is defined as well | |
| onUpdateOption | (callback: updatedProps => void) => void | Update handler function for periodic updates. The function passed here gets called on each periodic update with a callback function to pass the updated properties of this shipping option. | |
| default | boolean | Pre-select this option after initialization |
PickupShippingOption
A shipping option where the user can select a location from a list, e.g. for pickup point delivery or self-pickup at a store
| Key | Type | Allowed values | Description |
|---|---|---|---|
| id | string | Unique identifier for the shipping option | |
| name | string | Name of the shipping option to be displayed | |
| price | Price | Price for the shipping option, if not specified, free is assumed | |
| description | string | Additional description for the shipping text, displayed below the delivery time if specified | |
| deliveryTime | DeliveryTime | When the order will be delivered. See the type documentation for the available formats. | |
| logoUrl | string | A url to a logo image to be displayed for the shipping option. Maximum displayable logo size is 70x37 px. The logo url can be specified as relative to the embedding host, or absolute | |
| additionalData | any | Any arbitrary data that should be returned when the option is selected. This data is not used by the checkout anywhere, it is just passed through as-is. | |
| updateInterval | number | Interval for periodic updates of this shipping option in seconds. Periodic updates will only be performed if an update handler function is defined as well | |
| onUpdateOption | (callback: updatedProps => void) => void | Update handler function for periodic updates. The function passed here gets called on each periodic update with a callback function to pass the updated properties of this shipping option. | |
| default | boolean | Pre-select this option after initialization | |
| locations | ShippingLocation[] | A list of pickup locations, at least one needs to be specified. If more than one location is specified, a dropdown list is shown |
ServiceLevelShippingOption
A shipping option where users can select different levels of service with varying prices and delivery times from a list, e.g. tracked or untracked parcels, standard or premium shipping, etc...
| Key | Type | Allowed values | Description |
|---|---|---|---|
| id | string | Unique identifier for the shipping option | |
| name | string | Name of the shipping option to be displayed | |
| price | Price | Will be ignored, as the price is individually specified for each service level | |
| description | string | Additional description for the shipping text, displayed below the delivery time if specified | |
| deliveryTime | DeliveryTime | When the order will be delivered. See the type documentation for the available formats. | |
| logoUrl | string | A url to a logo image to be displayed for the shipping option. Maximum displayable logo size is 70x37 px. The logo url can be specified as relative to the embedding host, or absolute | |
| additionalData | any | Any arbitrary data that should be returned when the option is selected. This data is not used by the checkout anywhere, it is just passed through as-is. | |
| updateInterval | number | Interval for periodic updates of this shipping option in seconds. Periodic updates will only be performed if an update handler function is defined as well | |
| onUpdateOption | (callback: updatedProps => void) => void | Update handler function for periodic updates. The function passed here gets called on each periodic update with a callback function to pass the updated properties of this shipping option. | |
| default | boolean | Pre-select this option after initialization | |
| levels | ShippingServiceLevel[] | The different service levels for the delivery service to choose from |
PorterbuddyShippingOption
Porterbuddy Shipping presents a matrix where the user can select a delivery window.
| Key | Type | Allowed values | Description |
|---|---|---|---|
| id | string | Unique identifier for the shipping option | |
| name | string | Name of the shipping option to be displayed | |
| price | Price | Will be ignored, as the price is individually specified for each delivery window | |
| description | string | Additional description for the shipping text, displayed below the delivery time if specified | |
| deliveryTime | DeliveryTime | When the order will be delivered. See the type documentation for the available formats. | |
| logoUrl | String | Will be ignored, the Porterbuddy logo is built into the consolidated checkout | |
| additionalData | any | Any arbitrary data that should be returned when the option is selected. This data is not used by the checkout anywhere, it is just passed through as-is. | |
| updateInterval | number | Interval for periodic updates of this shipping option in seconds. Periodic updates will only be performed if an update handler function is defined as well | |
| onUpdateOption | (callback: updatedProps => void) => void | Update handler function for periodic updates. The function passed here gets called on each periodic update with a callback function to pass the updated properties of this shipping option. | |
| default | boolean | Pre-select this option after initialization | |
| availabilityResponse | AvailabilityResponse | An availabilityResponse from Porterbuddy availability API. See https://developer.porterbuddy.com/#availability-check-api | |
| discount | number | Discount to be applied on all delivery window shown, specified as hundreds of a value unit (e.g. discount=5000 for a price reduction by 50 NOK) |
ShippingLocation
A location for either pickup point delivery or store pickup
| Key | Type | Allowed values | Description |
|---|---|---|---|
| id | string | A unique id for the shipping location | |
| name | string | Name of the location, to be displayed in the option card | |
| address | string | Address of the location, to be displayed in the option card | |
| openingHours | string | Opening hours of the location (arbitrary string) | |
| logoUrl | string | A url to a logo image to be displayed for the location. Maximum displayable logo size is 70x37 px. The logo url can be specified as relative to the embedding host, or absolute. If a location with a logo is selected, the logo for the whole option is set to the one for the location | |
| description | string | Additional description for the shipping location, will be displayed below the other fields if present |
ShippingServiceLevel
A selected service level for a shipping carrier
| Key | Type | Allowed values | Description |
|---|---|---|---|
| id | string | A unique id for the shipping service level | |
| name | string | Name of the shipping service level, to be displayed in the option card | |
| deliveryTime | DeliveryTime | When the order will be delivered. See the type documentation for the available formats. | |
| price | Price | Price for the shipping option, if not specified, free is assumed | |
| description | string | Additional description for the shipping service level, will be displayed below the other fields if present |
Price
A price for a shipping option
| Key | Type | Allowed values | Description |
|---|---|---|---|
| fractionalDenomination | number | The price amount on a base of 1/100 of the specified currency, e.g. a fractional denomination of 4900 describes a price of 49,00 | |
| currency | string | NOK | A currency code. Currently, only "NOK" is supported |
DeliveryWindow
A delivery window for Porterbuddy deliveries
| Key | Type | Allowed values | Description |
|---|---|---|---|
| product | string | delivery | The delivery product. Currently, only "delivery" is available |
| start | string | Start time of the delivery window in iso format | |
| end | string | End time of the delivery window in iso format | |
| price | Price | Price for this delivery window | |
| displayPrice | Price | Display price for this delivery window, shown instead of the price | |
| consolidated | boolean | Indicates if this delivery window can be used to consolidate with an existing delivery |
DeliveryTime
A specification of delivery time. The value is an object where the "format" field is a discriminator to declare exactly what the other properties mean. The various formats (not fields) are listed below.
| Variant | Type | Allowed values | Description |
|---|---|---|---|
| text | { format: 'text', line1: string, line2: string } | Rendered as "${line1}, ${line2}" | |
| exactDate | { format: 'exactDate', date: "YYYY-MM-DD" } | Rendered as e.g. "om 4 dg, 4. okt" / "I dag, 30. sept" / "I morgen, 1. okt" | |
| estimatedDate | { format: 'estimatedDate', date: "YYYY-MM-DD" } | Rendered as e.g. "ca 4 dg, forventet 4. okt" / "I dag, 30. sept" / "I morgen, forventet 1. okt" | |
| rangeOfWeekdays | { format: 'rangeOfWeekdays', minDays: number, maxDays: number } | Rendered as e.g. "1-4 dg, innen 4. okt" | |
| rangeOfDays | { format: 'rangeOfDays', minDays: number, maxDays: number } | Rendered as e.g. "1-4 dg, innen 4. okt" | |
| exactNumberOfWeekdays | { format: 'exactNumberOfWeekdays', days: number } | Rendered as e.g. "4 dg, 4. okt" | |
| exactNumberOfDays | { format: 'exactNumberOfDays', days: number } | Rendered as e.g. "4 dg, 4. okt" | |
| estimatedNumberOfWeekdays | { format: 'estimatedNumberOfWeekdays', days: number } | Rendered as e.g. "ca 4 dg, forventet 4. okt" | |
| estimatedNumberOfDays | { format: 'estimatedNumberOfDays', days: number } | Rendered as e.g. "ca 4 dg, forventet 4. okt" |
ShippingCategory
A shipping category. Supported values are "home", "pickupPoint" and "store"
SelectedShipping
Data for the currently selected shipping option
| Key | Type | Allowed values | Description |
|---|---|---|---|
| id | string | Unique id of the selected shipping option | |
| price | Price | Price of the selected shipping option as displayed | |
| deliveryTime | DeliveryTime | The deliveryTime specified for the option. Whatever was sent in what be what you will get out. For porterbuddy delivery the format will be exactDate. For consolidated porterbuddy delivery it will be blank. | |
| data | ShippingLocation | ShippingServiceLevel | SelectedPorterbuddyOption | Additional data to describe the selected option. Only present if the selected option is PickupShippingOption or PorterbuddyShippingOption | |
| additionalData | any | Arbitrary data that was specified in the Shipping Option definition and was passed-through as-is. |
SelectedPorterbuddyOption
Additional data for a currently selected porterbuddy delivery option
| Key | Type | Allowed values | Description |
|---|---|---|---|
| deliveryWindow | DeliveryWindow | The selected delivery window | |
| deliveryWindowIndex | number | index of the selected delivery window |
RecipientInfo
Info about the recipient of a delivery
| Key | Type | Allowed values | Description |
|---|---|---|---|
| string | E-Mail address of the recipient | ||
| postCode | string | Recipient's postcode | |
| streetAddress | string | Recipient's street address |
CheckoutCallbacks
Callback functions to interact with the widget from external scripts
| Key | Type | Allowed values | Description |
|---|---|---|---|
| forceRefresh | () => Promise<void> | Completely refreshes the checkout with the current value of the options object. Current selections and form data will be lost. Returns a promise that will resolve when the refresh is complete. | |
| setRecipientInfo | (recipientInfo: RecipientInfo) => void | Sets the recipient info and updates the delivery option properties from the current state of the options object | |
| refreshShippingOptions | () => void | Refreshes the currently displayed shipping options with the values from the configuration object | |
| setRecipientInfoLocked | (recipientInfoLocked: boolean) => void | Locks the address form and prevents further editing if recipientInfoLocked is true. Call with recipientInfoLocked false to unlock the form again. Should be used in conjunction with setRecipientInfo or onRecipientInfo. If the form is locked with invalid values behaviour is undefined. |