The Webshipper API is a RESTful JSON API that gives full control over your Webshipper account. The API is scoped to your account name, and is accessed via the endpoint https://<account name>.api.webshipper.io/v2/. Your account name is the same as you see when you access the Webshipper web UI at https://<account name>.webshipper.io.
This API conforms to the JSON API standard with the following conventions:
id
, which is a server-side generated sequential integerorder_lines
page[number]
created_at
and updated_at
which are ISO 8601 timestamps like 2018-03-07T14:01:18.000Z
It is also possible to download the documentation in the OpenAPI 3.0 here
{
"data": {
"type": "orders",
"attributes": {
"drop_point": {
"drop_point_id": 12,
"address_1": "Street 123",
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"carrier_code": "DUMMY"
},
"delivery_address": {
"address_1": "Lyngbygade 8",
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK"
},
"sender_address": {
"address_1": "Example street 2",
"zip": "7400",
"city": "Herning",
"country_code": "DK"
},
"order_lines": [
{
"sku": "ZB420",
"description": "Zebra GK420d label printer",
"quantity": 1,
"location": "LOC 3563-67",
"tarif_number": "844332",
"country_of_origin": "DK",
"unit_price": 24.0,
"vat_percent": 25.0,
"order_id": 12,
"status": null,
"ext_ref": "342342",
"weight": 500.0,
"weight_unit": "g",
"discount_value": 0.0,
"discount_type": "fixed",
"discounted_unit_price": 24.0
}
]
},
"relationships": {
"order_channel": {
"data": {
"id": 9,
"type": "order_channels"
}
},
"shipping_rate": {
"data": {
"id": 6,
"type": "shipping_rates"
}
}
}
}
}
Service Quotes provides a way to quote carriers directly to find a set of suitable services.
Assuming a Carrier exists with id 1.
{
"data": {
"type": "service_quotes",
"attributes": {
"carrier_id": 1,
"send_time": "2018-04-03T10:19:53.9+01:00",
"sender_address": {
"address_1": "Lyngbygade 8",
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK"
},
"delivery_address": {
"address_1": "Lyngbygade 8",
"zip": "9190",
"city": "Tromsø",
"country_code": "NO"
}
}
}
}
Expected response
{
"data": {
"id": "1",
"type": "service_quotes",
"links": {
"self": "http://you.api.webshipper.io/v2/service_quotes/1"
},
"attributes": {
"carrier_id": 1,
"packages": null,
"send_time": "2018-04-03T10:19:53.9+01:00",
"sender_address": {
"address_1": "Lyngbygade 8",
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK"
},
"delivery_address": {
"address_1": "Lyngbygade 8",
"zip": "9190",
"city": "Tromsø",
"country_code": "NO"
},
"items": null,
"services": [
{
"service_name": "MyPack Home",
"service_code": "MYPACK_HOME",
"is_return": false,
"supports_paperless": false,
"requires_drop_point": false,
"cost_price": null,
"currency": null,
"vat_percent": null,
"estimated_delivery_date_from": null,
"estimated_delivery_date_to": null,
"add_ons": [
{
"add_on_name": "Pakke med omtanke",
"add_on_code": "Z22"
},
{
"add_on_name": "Flexlevering",
"add_on_code": "Z41"
},
{
"add_on_name": "Transportforsikring i Europa",
"add_on_code": "Z60"
}
],
"parameters": null,
"country_combinations": [
{
"sender_country": "DK",
"recipient_countries": [
"NO"
]
}
],
"barcode_requirement": {
"barcode_type": "SSCC",
"scope": "global"
},
"waybill_requirement": null,
"booking_quote_info": null
},
{
"service_name": "Storbrev",
"service_code": "STORBREV",
"is_return": false,
"supports_paperless": false,
"requires_drop_point": false,
"cost_price": null,
"currency": null,
"vat_percent": null,
"estimated_delivery_date_from": null,
"estimated_delivery_date_to": null,
"add_ons": null,
"parameters": null,
"country_combinations": [
{
"sender_country": "DK",
"recipient_countries": [
"EE",
"FI",
"FR",
"GR",
"IE",
"IS",
"IT",
"HR",
"LV",
"LT",
"LU",
"NL",
"NO",
"AF",
"PL",
"PT",
"CH",
"SK",
"SI",
"ES",
"GB",
"SE",
"CZ",
"DE",
"HU",
"AT"
]
}
],
"barcode_requirement": {
"barcode_type": "LZ",
"scope": "local"
},
"waybill_requirement": null,
"booking_quote_info": null
}
]
},
"meta": {
"copyright": "© 2018 Webshipper ApS"
}
}
}
Order Channel Rate Quotes can quote an order channel for matching shipping rates. These quotes are used to display shipping options in e-commerce systems.
Request:
{
"data": {
"type": "rate_quotes",
"attributes": {
"order_channel_id": 16,
"price": 199,
"weight": 100,
"delivery_address": {
"zip": "7400",
"country_code": "DK"
},
"items": [
{
"quantity": 5,
"sku": "sku123"
}
]
}
}
}
Response
{
"data": {
"id": "1",
"type": "rate_quotes",
"links": {
"self": "/v2/rate_quotes/1"
},
"attributes": {
"quotes": [
{
"price": 45,
"tax_percent": 0,
"currency": "EUR",
"carrier_logo": "data:image/png;base64,iVBORw...",
"carrier_name": "PostNord",
"shipping_rate": {
"id": 16,
"order_channel_id": 16,
"carrier_id": 4,
"name": "Levering til døren",
"carrier_service_code": "MYPACK_HOME",
"zip_policy": null,
"require_drop_point": false,
"visible_for": null,
"created_at": "2018-03-19 10:15:27 UTC",
"updated_at": "2018-04-06 09:06:13 UTC",
"is_return": false,
"carriers_email": false,
"carriers_sms": false,
"mail_template_id": null,
"comment_map": "{{order.external_comment}}",
"reference_map": "O{{order.id}}",
"dutiable": null
}
},
{
"price": 0,
"tax_percent": 0,
"currency": "EUR",
"carrier_logo": "data:image/png;base64,iVBORw0KGgo....",
"carrier_name": "Your GLS ",
"shipping_rate": {
"id": 17,
"order_channel_id": 16,
"carrier_id": 2,
"name": "GLS Pakkeshop",
"carrier_service_code": "PARCELSHOP",
"zip_policy": null,
"require_drop_point": true,
"visible_for": null,
"created_at": "2018-03-19 12:57:36 UTC",
"updated_at": "2018-03-19 12:57:36 UTC",
"is_return": false,
"carriers_email": true,
"carriers_sms": true,
"mail_template_id": null,
"comment_map": "{{order.external_comment}}",
"reference_map": "O{{order.id}}",
"dutiable": null
}
}
],
"success": true,
"delivery_address": {
"zip": "7400",
"country_code": "DK"
},
"price": 199,
"weight": 100,
"height": null,
"length": null,
"width": null,
"sender_address": null,
"items": [
{
"quantity": 5,
"sku": "sku123"
}
],
"order_channel_id": 16
},
"meta": {
"copyright": "© 2018 Webshipper ApS"
}
}
}
The Webshipper API can be used as a shipping engine for booking shipments and automatically printing labels. Shipments can be created with or without having created an Order first.
Assuming a Carrier exists with id 1 and that it provides a service called MYPACK_HOME
{
"data": {
"type": "shipments",
"attributes": {
"reference": "ref65436",
"service_code": "MYPACK_HOME",
"packages": [
{
"weight": 1000,
"weight_unit": "g",
"customs_lines": [
{
"sku": "SKU1",
"description": "Black pants",
"quantity": 1,
"tarif_number": "234343332",
"country_of_origin": "DE",
"unit_price": 15,
"vat_percent": 15.0,
"currency": "EUR",
"weight": 1000,
"weight_unit": "g"
}
],
"dimensions": {
"height": 15,
"width": 15,
"length": 15,
"unit": "cm"
}
}
],
"delivery_address": {
"company_name": "Webshipper ApS",
"address_1": "lyngbygade 8",
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"email": "support@webshipper.com",
"address_type": "recipient"
},
"sender_address": {
"company_name": "Webshipper ApS",
"address_1": "lyngbygade 8",
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"email": "support@webshipper.com",
"address_type": "recipient"
}
},
"relationships": {
"carrier": {
"data": {"id": 1, "type": "carriers"}
}
}
}
}
Assumes an order exists with id 1
{
"data": {
"type": "shipments",
"attributes": {
},
"relationships": {
"order": {
"data": {"id": 1, "type": "orders"}
}
}
}
}
Assumes a Shipping Rate exists with id 1 and requires a drop point
{
"data": {
"type": "shipments",
"attributes": {
"sender_address": {
"company_name": "Webshipper",
"address_1": "Lyngbygade 8",
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK"
},
"delivery_address": {
"att_contact": "Guy McPerson",
"address_1": "Dummystreet 123",
"zip": "7430",
"city": "Ikast",
"country_code": "DK"
},
"drop_point": {
"name": "PostNord Drop Point 2",
"address_1": "Nørreallé 12",
"zip": "7430",
"city": "Ikast",
"country_code": "DK"
},
"packages": [
{
"weight": 1000,
"weight_unit": "g"
}
]
},
"relationships": {
"shipping_rate": {
"data": {"id": 1, "type": "shipping_rates"}
}
}
}
}
Search for the nearest drop points by carrier using drop_point_locators
.
POST https://<account name>.api.webshipper.io/v2/drop_point_locators
{
"data": {
"type": "drop_point_locators",
"attributes": {
"carrier_id": 1,
"service_code": "MYPACK_COLLECT",
"delivery_address": {
"address_1": "Lynbgbygade 8",
"city": "Silkeborg",
"zip": "7400",
"country_code": "DK"
}
}
}
}
Response
{
"data": {
"id": "1",
"type": "drop_point_locators",
"links": {
"self": "http://mads.api.staging.webshipper.io/v2/drop_point_locators/1"
},
"attributes": {
"carrier_id": 4,
"service_code": "MYPACK_COLLECT",
"shipping_rate_id": null,
"delivery_address": {
"address_1": "Lynbgbygade 8",
"city": "Silkeborg",
"zip": "8600",
"country_code": "DK"
},
"drop_points": [
{
"name": "Posthus Superbrugsen",
"longitude": 9.51366,
"latitude": 56.1849,
"address_1": "Øster Bordingvej 1",
"address_2": null,
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"state": null,
"phone": null,
"drop_point_id": "8603",
"carrier_code": "POSTNORD",
"created_at": "2018-04-04T12:49:36.000Z",
"updated_at": "2018-04-10T11:08:48.000Z",
"routing_code": null
},
{
"name": "Pakkeboks 5143 Fakta",
"longitude": 9.49539,
"latitude": 56.1719,
"address_1": "Padborgvej 298",
"address_2": null,
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"state": null,
"phone": null,
"drop_point_id": "5143",
"carrier_code": "POSTNORD",
"created_at": "2018-04-04T12:49:40.000Z",
"updated_at": "2018-04-10T11:09:00.000Z",
"routing_code": null
},
{
"name": "Pakkeboks 3947 Fakta",
"longitude": 9.57671,
"latitude": 56.1881,
"address_1": "Randersvej 12",
"address_2": null,
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"state": null,
"phone": null,
"drop_point_id": "3947",
"carrier_code": "POSTNORD",
"created_at": "2018-04-04T12:49:40.000Z",
"updated_at": "2018-04-10T11:09:00.000Z",
"routing_code": null
},
{
"name": "Pakkeboks 3842 Super Brugsen",
"longitude": 9.51366,
"latitude": 56.1849,
"address_1": "Øster Bordingvej 1",
"address_2": null,
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"state": null,
"phone": null,
"drop_point_id": "3842",
"carrier_code": "POSTNORD",
"created_at": "2018-04-04T12:49:53.000Z",
"updated_at": "2018-04-10T11:09:37.000Z",
"routing_code": null
},
{
"name": "Posthus Spar",
"longitude": 9.62954,
"latitude": 56.2267,
"address_1": "Grønbækvej 9",
"address_2": null,
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"state": null,
"phone": null,
"drop_point_id": "8607",
"carrier_code": "POSTNORD",
"created_at": "2018-04-04T12:49:41.000Z",
"updated_at": "2018-04-10T11:09:03.000Z",
"routing_code": null
},
{
"name": "Posthus Lokalbrugsen",
"longitude": 9.40918,
"latitude": 56.1947,
"address_1": "Engesvangvej 9",
"address_2": null,
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"state": null,
"phone": null,
"drop_point_id": "8604",
"carrier_code": "POSTNORD",
"created_at": "2018-04-04T12:49:41.000Z",
"updated_at": "2018-04-10T11:09:03.000Z",
"routing_code": null
},
{
"name": "Pakkeboks 340 V/ Silkeborg Station",
"longitude": 9.54492,
"latitude": 56.1646,
"address_1": "Drewsensvej 5",
"address_2": null,
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"state": null,
"phone": null,
"drop_point_id": "340",
"carrier_code": "POSTNORD",
"created_at": "2018-04-04T12:49:41.000Z",
"updated_at": "2018-04-10T11:09:03.000Z",
"routing_code": null
},
{
"name": "Posthus Føtex",
"longitude": 9.54973,
"latitude": 56.1692,
"address_1": "Torvet 4",
"address_2": null,
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"state": null,
"phone": null,
"drop_point_id": "8605",
"carrier_code": "POSTNORD",
"created_at": "2018-04-04T12:49:53.000Z",
"updated_at": "2018-04-10T11:09:38.000Z",
"routing_code": null
},
{
"name": "Pakkeboks 3946 Kvickly",
"longitude": 9.55464,
"latitude": 56.1729,
"address_1": "Søtorvet 1",
"address_2": null,
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"state": null,
"phone": null,
"drop_point_id": "3946",
"carrier_code": "POSTNORD",
"created_at": "2018-04-04T12:49:50.000Z",
"updated_at": "2018-04-10T11:09:28.000Z",
"routing_code": null
},
{
"name": "Posthus Kvickly",
"longitude": 9.55464,
"latitude": 56.1729,
"address_1": "Søtorvet 1",
"address_2": null,
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"state": null,
"phone": null,
"drop_point_id": "8601",
"carrier_code": "POSTNORD",
"created_at": "2018-04-04T12:49:46.000Z",
"updated_at": "2018-04-10T11:09:18.000Z",
"routing_code": null
}
]
},
"meta": {
"copyright": "© 2018 Webshipper ApS"
}
}
}
The Webshipper API has a rate limiter. It is implemented with a leaky bucket algoritm, which allows you to make up to 2 API calls per second with a bucket size of 40. In other words you are able to make infrequent bursts and if you keep API calls below 2 calls per second, you won't ever be restricted. The rate limit is scoped per token.
In case you need to have this limit increased, please contact your Webshipper sales representative.
The API uses OAuth2 for authorization. The following grant_types are supported by the API:
Please see the OAuth2 specification for more details or read DigitalOcean's guide on OAuth2.
The attributes client_id and client_secret are not used with the password grant_type.
curl -X POST https://<account name>.api.webshipper.io/v2/
oauth/token\?grant_type=password\&username=user@example.com&password=muchs2cret
Response:
{
"access_token":"4f6e6c041914116a30b5cdd16fda38db43d24327fa841e005d20b26074dedd81",
"token_type":"bearer",
"expires_in":3599,
"refresh_token":"c6ea647e6a99fd568fa4907469c763ae631f3aeab11ebb5c9317000bf9f06873",
"scope":"read_orders read_shipments",
"created_at":1515749820
}
Authorised requests to Webshipper are made by setting the Authorization
header. Example:
curl -H "Authorization: Bearer <token>" https://<account name>.api.webshipper.io/v2/orders
Most tokens are issued with a refresh_token
. This is used to obtain a new access token.
curl -X POST https://<account name>.api.webshipper.io/v2/oauth/token\?grant_type=refresh_token\&refresh_token=<refresh_token>
Response:
{
"access_token":"9bfc1c29a1820481ea56b72d61964b5863f2a7151e011a450f543916d5787a09",
"token_type":"bearer",
"expires_in":3599,
"refresh_token":"2b3c5a3504432ae6c5ea2844b6de3c8c6492991a666e93a48310259bc57e3374",
"scope":"read_orders read_shipments",
"created_at":1515751219
}
Most entities have relationships that can be sideloaded. To see which relationships an entity has, please look at the "relationships" part of any given GET request or look at the entity in this documentation.
When you GET a resource you can request to include relationships by addding ?include=(resource_name)
to the query.
Some relations are flattened, i.e. not using the JSON API relationships, but present them as simple JSON objects in the attributes
Flattened relations are replaced for each update operation if the id attribute is not present. If id is given the relation is updated.
One order line is updated and one is added, this is useful for preserving relations to e.g. packages.
{
"data": {
"id": 12,
"type": "orders",
"attributes": {
"order_lines": [
{
"id": 23,
"sku": "sk1231",
},
{
"sku": "sk853",
"description": "Black Hat, good for putting on your head"
}
]
}
}
}
As the JSON API is agnostic about filtering strategies the following conventions are used:
filter[name]=Webshipper
filter[name]
. Example: filter[name][value]=Webshipper&filter[name][operator]=%3D
(%3D is the url encoding of '='). The following operators are supported:
!=
, =
, <
, <=
, >
, >=
, LIKE
, NOT LIKE
. Operators share the semantics as their SQL counterparts, e.g. you can do fuzzy search like
filter[city][value]=Aarhus%25&filter[city][operator]=LIKE
to find addresses where the city begins with 'Aarhus'
Return all pending orders:
{tenant}.api.webshipper.io/v2/orders?filter[status]=pending
Some resources do not follow this convention or have additional filter for things like customised search or filtering by associated resources.
If you want to get all orders with status pending
or dispatched
, it can simply be achived by comma-separating the filter value.
So it will look like this:
/v2/orders?filter[status]=pending,dispatched
Another advanced filter example could be to fetch all orders created between two dates.
To do that, you need to use the explicit method of defining filters, with seperate [value]
and [operator]
.
Furthermore, the [name]
(eg. [created_at]
) needs to be forced into an array structure like this [created_at][0][value]
So it will look like this:
/v2/orders?filter[created_at][0][operator]=%3C%3D&filter[created_at][0][value]=2021-03-29&filter[created_at][1][operator]=%3E%3D&filter[created_at][1][value]=2021-03-26
Note the addition of [0]
and [1]
.
Both those advanced filters can be merged together, so if you want to get all orders with status dispatch
or pending
, which was created between 2021-03-29
and 2021-03-26
, it will look like this:
/v2/orders?filter[status]=pending,dispatched&filter[created_at][0][operator]=%3C%3D&filter[created_at][0][value]=2021-03-29&filter[created_at][1][operator]=%3E%3D&filter[created_at][1][value]=2021-03-26
read_orders
write_orders
read_shipments
write_shipments
read_rates
write_rates
read_order_channels
write_order_channels
read_carries
write_carriers
read_templates
write_templates
read_carrier_types
read_order_channel_types
read_user_groups
read_slip_templates
write_slip_templates
read_mail_templates
write_mail_templates
read_users
write_users
read_order_channel_acls
write_order_channel_acls
write_carrier_acls
read_carrier_acls
read_printers
write_printers
read_barcode_ranges
write_barcode_ranges
read_access_tokens
write_access_tokens
read_reports
write_reports
read_waybills
write_waybills
read_shipping_addresses
write_shipping_addresses
This section describes how to implement a carrier that complies with Webshipper's carrier-standard. A Webshipper carrier can be hosted externally, and the interface works over an HTTP JSON protocol. In order to implement a Webshipper carrier, you must build a web service that has the specified endpoints and it must respond in the format specified later.
All endpoints must use the HTTP header Content-Type: application/json
for responses
If the attribute test_mode
is set to true, the implementation must treat the request as a dummy request
and must not charge the customer for that booking.
This specification does not distinguish between integers and float for numeric types, but instead use generic number values as defines in the JSON specification.
The following endpoints are required
The following endpoints are optional
When creating a Carrier Implementation with Webshipper, you must specify which credentials that you need to authenticate your customers. Often an API-token or a username and password is used.
It is your role as the implementer to provide us with a list of required credentials, as well as a list of your URL endpoints. When a customer adds your Carrier to his or her account, the customer will be asked to fill in the provided credentials, e.g. a username and password. The provided credentials are included in every request to the endpoints in the field carrier_attributes
.
carrier_attributes
{
"carrier_attributes": {
"username": "user@example.com",
"password": "verySec0re",
"account_id", "2"
},
[...]
}
X-WEBSHIPPER-HMAC-SHA256
.
As the name suggests, it contains a HMAC SHA256 generated
with the POST message body and the shared secret. The shared secret is provided when you enter the
carrier agreement with Webshipper.
Example in Ruby
def verify_request!(data, hmac_header)
secret = 'SHARED SECRET'
calculated_hmac = Base64.strict_encode64(OpenSSL::HMAC.digest('sha256', secret, data))
is_valid = ActiveSupport::SecurityUtils.secure_compare(calculated_hmac, hmac_header)
raise "Request not from Webshipper! No hackers here" unless is_valid
end
end
# Make sure to get the raw post body
verify_request! request.raw_post, env['HTTP_X_WEBSHIPPER_HMAC_SHA256']
Example in PHP
function verify_request($data, $hmac_header)
{
$secret = 'SHARED SECRET';
$calculated_hmac = base64_encode(hash_hmac('sha256', $data, $secret, true));
íf( !hash_equals($hmac_header, $calculated_hmac)) {
throw new Exception("Hackers beware!");
}
}
$hmac_header = $request->headers->get('X-WEBSHIPPER-HMAC-SHA256');
$data = $request->getContent();
verify_request($data, $hmac_header);
The endpoint should respond with a suitable HTTP status code, such as 422 or 500.
Error messages should be supplied in the response body as a JSON object with a single key called errors
containing an array of error messages.
422 UNPROCESSABLE ENTITY
{
"errors": [
"Drop point not supplied",
"Weight is too high"
]
}
Parameters allows for additional infomation to be included in the booking request. This could for instance be details like goods type, special transportation requirements or Cash on Delivery details. Say you offer Cash on Delivery as an optional additional service, we can specify it by added a parameter and an add on to your service list and service quote response:
{
"services": [
{
"service_name": "B2C delivery",
"service_code": "B2C",
"add_ons": [
{
"add_on_name": "Cash on Delivery",
"add_on_code": "COD"
}
],
"parameters": [
{
"attr_name": "Cash on Delivery Amount",
"attr_key": "cod_amount",
"attr_type": "integer",
"add_on_dependency": "COD"
}
]
}
]
}
By adding the add_on_dependency
to the parameter, we indicate that the parameter should only by made visible to the user when the add on "Cash on Delivery" is checked.
If the user checks "Cash on Delivery" and fill in 499 the "Cash on Delivery Amount" input, the resulting booking request will look like this:
{
[...],
"service_code": "B2C",
"add_ons": ["COD"],
"service_attributes": {
"cod_amount": "499"
},
[...]
}
Valid values for parameters attr_type
are string
, time_of_day
, datetime
, integer
and enum
. If the type is enum then you must specify a attribute enum
of
possible values like this where the first value is presented to the user and the last is of passed to service_attributes:
{
"attr_name": "Goods Type",
"attr_key": "goods_type",
"attr_type": "enum",
"enum": [
["Paper documents", "documents"],
["Gravel, Sand, or Dirt", "big_bag_materials"],
["Boxed packages", "boxed_items"],
]
}
Add ons have the following fields:
add_on_name |
The readable name for the add on. |
add_on_code |
The code for the add on. If the add on is selected, this code will the included in the booking request. |
scope |
Optional, defaults to "shipment". If set to "package" the add on will we selectable for each package in the shipment, i.e. each package can have different add ons. |
Service attributes have the following fields:
attr_name |
The name to be displayed. |
attr_key |
This is the key that will be included in the booking request. |
attr_type |
Attr type can be one of: integer, string, time_of_day, datetime or enum. time_of_day is formatted as "HH:MM". |
attr_description |
Optional. The description of the attribute that can guide the user. |
add_on_dependency |
Optional. You can use this to set if the service attribute are dependent on an add_on. Insert the 'add_on_code'. |
scope |
Optional. It defaults to "shipment". If set to "package" the service attribute will we selectable for each package in the shipment, i.e. different packages can have different service attributes. |
required |
Optional. If set to true, it must be filled out. |
enum |
Must be present if attr_type is enum. Should be an array of pairs like: [ ["Option 1 label", "option_1_value"], ["Option 2 label", "option_2_value"] ] |
To test your implementation:
The service list endpoint must return all supported services for the carrier. This endpoint will mainly be called when creating preconfigured shipping rates. Webshipper will make a POST request to this endpoint.
{
"carrier_code": "YOURCARRIER",
"carrier_attributes": {
"username": "TEST USER",
"api_token": "TEST TOKEN"
}
}
{
"services": [
{
"service_name": "Express Europe",
"service_code": "EE",
"is_return": false,
"supports_paperless": false,
"requires_drop_point": false,
"barcode_requirement": { "scope": "global", "barcode_type": "SSCC" },
"waybill_requirement": {
"waybill_code": "PNVAREBREV",
"waybill_name": "Post nord varebrev",
"barcode_requirement": {
"scope": "local",
"barcode_type": "LYDK"
}
},
"estimated_delivery_date_from":"2017-10-04 09:30:07 +0200",
"estimated_delivery_date_to":"2017-10-04 09:30:07 +0200",
"add_ons": [
{
"add_on_name": "Cash on delivery",
"add_on_code": "COD"
},
{
"add_on_name": "Returnable goods",
"add_on_code": "RETURNABLE",
"scope": "package"
}
],
"parameters": [
{
"attr_name": "COD Amount",
"attr_key": "cod_amount",
"attr_type": "integer",
"add_on_dependency": "COD"
},
{
"attr_name": "Ladmeter",
"attr_key": "ladmeter",
"attr_type": "integer",
"required": true
},
{
"attr_name": "Gods type",
"attr_key": "transport_type",
"attr_type": "enum",
"scope": "package",
"enum": [
[
"Halv palle",
"half_pallet"
],
[
"Hel palle",
"pallet"
]
]
}
],
"country_combinations": [
{
"sender_country": "DK",
"recipient_countries": [
"DK",
"SE",
"NO"
]
},
{
"sender_country": "SE",
"recipient_countries": [
"DK"
]
}
],
supported_colli_types: [
{
"colli_type": "eur",
"name": "EUR pallet",
"dimensions": {
"width": 80,
"length": 120,
"height": 14,
"unit": "cm"
}
},
{
"colli_type": "eur_half",
"name": "EUR half pallet",
"dimensions": {
"width": 0.80,
"length": 0.60,
"height": 0.14,
"unit": "m"
}
},
{
"colli_type": "eur_quarter",
"name": "EUR quarter pallet",
"dimensions": {
"width": 60,
"length": 40,
"height": 14,
"unit": "cm"
}
}
]
}
]
}
Barcode requirements can be used when your waybill, package or shipment requires a barcode. There are 3 different ways to require barcodes as shown below:
Notice that barcode requirements have local and global scopes. This allows you to use the webshipper issued SSCC barcodes. Or you can use a local scope, to allow the individual customer to create his own barcode ranges for the customer account.
If you dont know what to do with barcode_requirements, please leave them out. They are not mandatoryThe field supported_colli_types can be used to define carrier specific colli_types, these colli types can be used to define a packages nature, i.e. if the package is a EUR pallet, half pallet or similar.
supported_colli_types can be left out from the service list/quote response and be populated by webshipper defaults. This can be configured in the Webshipper backend and should be informed when requesting Webshipper to add your carrier integration.
It is recommended to use the Webshipper defaults if possible and translate to carrier specific values inside the carrier implementation.
Name and dimensions are not required but recommended to give the best user experience.
Webshipper default supported_colli_types are as follows
Webshipper will make a POST request to the specified endpoint containing data about the quoted shipment, recipient and sender. A service quote request can contain a service code. In case that a service code is included, only that specific service should be calculated and returned.
Note that country_combinations can leave "recipient_countries" empty, which will result in all destination countries being whitelisted.
The service quote endpoint is used when creating a manual shipment. It will also be called before every booking to ensure service availability.
{
"packages": [
{
"colli_type": "eur",
"weight": 1000,
"weight_unit": "g",
"dimensions": {
"height": 15,
"length": 15,
"width": 15,
"unit": "cm"
},
"service_attributes": {
"packaging_type": "cardboard_box"
}
}
],
"send_time": "2017-10-04T10:19:53.9+01:00",
"service_code": "EE",
"add_ons": ["COD"],
"service_attributes": {
"ladmeter": 12
},
"carrier_code": "MYCARRIER",
"carrier_attributes": {
"username": "TEST USER",
"api_token": "TEST TOKEN"
},
"sender_address": {
"att_contact": "Test contact",
"company_name": "Test company",
"address_1": "Test address",
"address_2": "Test address 2 ",
"city": "Silkeborg",
"zip": "8600",
"country_code": "DK",
"state": ""
},
"delivery_address": {
"att_contact": "Test contact",
"company_name": "Test company",
"address_1": "Test address",
"address_2": "Test address 2 ",
"city": "Silkeborg",
"zip": "8600",
"country_code": "DK",
"state": ""
}
}
Expected response from the carrier implementation
{
"services": [
{
"service_name": "Express Europe",
"service_code": "EE",
"is_return": false,
"supports_paperless": false,
"requires_drop_point": false,
"cost_price": 39,
"currency": "DKK",
"vat_percent": 25.0,
"estimated_delivery_date_from":"2017-10-04 09:30:07 +0200",
"estimated_delivery_date_to":"2017-10-04 09:30:07 +0200",
"add_ons": [
{
"add_on_name": "Cash on delivery",
"add_on_code": "COD"
},
{
"add_on_name": "Returnable goods",
"add_on_code": "RETURNABLE",
"scope": "package"
}
],
"parameters": [
{
"attr_name": "Ladmeter",
"attr_key": "ladmeter",
"attr_type": "integer",
"required": true
},
{
"attr_name": "Gods type",
"attr_key": "transport_type",
"attr_type": "enum",
"scope": "package",
"enum": [
[
"Halv palle",
"half_pallet"
],
[
"Hel palle",
"pallet"
]
]
}
],
"country_combinations": [
{
"sender_country": "DK",
"recipient_countries": [
"DK",
"SE",
"NO"
]
},
{
"sender_country": "SE",
"recipient_countries": [
"DK"
]
}
],
supported_colli_types: [
{
"colli_type": "eur",
"name": "EUR pallet",
"dimensions": {
"width": 80,
"length": 120,
"height": 14,
"unit": "cm"
}
},
{
"colli_type": "eur_half",
"name": "EUR half pallet",
"dimensions": {
"width": 0.80,
"length": 0.60,
"height": 0.14,
"unit": "m"
}
},
{
"colli_type": "eur_quarter",
"name": "EUR quarter pallet",
"dimensions": {
"width": 60,
"length": 40,
"height": 14,
"unit": "cm"
}
}
]
}
]
}
The booking endpoint is mandatory. This is the endpoint that Webshipper will call every time a shipment is generated or updated.
Support for updates are not mandatory, but Webshipper can be configured to allow update requests to be sent to the carrier. Update requests are identical to booking requests with the exception that request_type is "shipment_update_request". All information is sent in a update request so the carrier should "overwrite" the existing booking and return new updated labels. Currently Webshipper only supports updates for certain information such as package information, e.g. number of packages, weight, dimensions, etc. For a full list of updatable fields please look at the Shipment model documentation.
Documents are not mandatory, but can be used in case you want to return, for example, customs documents.
Valid document sizes are:
Valid label sizes are:
The carrier code returned must correspond to any currently registered carrier in Webshipper.
Webshipper might send documents like customs documents or invoices with the shipment request. The documents
attribute will only be present in the request if the carrier implementation is configured to receive documents.
Additionally the carrier implementation may return documents like customs declarations. Documents in the booking request are always in base64 encoded PDF format. Documents sent in the booking request should not be returned in the response data.
Documents include a document_type
attribute which will be one of customs_document
, invoice
, certificate
or other
.
Fields for documents in request:
customs_document
, invoice
, certificate
or other
.customs_document
, invoice
, certificate
or other
. Default to other
label_format
.
{
"request_type": "shipment_request",
"test_mode": true,
"shipment_id": 12,
"carrier_code": "MYCARRIER",
"service_code": "MYSERVICECODE",
"reference": "MYREFERENCE",
"label_format": "ZPL",
"carrier_attributes": {
"barcode_prefix": "57125",
"customer_id": "12345"
},
"service_attributes": {
"delivery_message": "Deliver before 19:00"
},
"add_ons": ["COD"],
"sms_notification": {
"phone": "80808080"
},
"email_notification": {
"email": "support@webshipr.com"
},
"sender_address": {
"att_contact": "Att contact",
"company_name": "Company name",
"address_1": "Address 1",
"address_2": "Address 2",
"city": "City",
"zip": "8600",
"country_code": "DK",
"state": ""
},
"billing_address": {
"att_contact": "Att contact",
"company_name": "Company name",
"address_1": "Address 1",
"address_2": "Address 2",
"city": "City",
"zip": "8600",
"country_code": "DK",
"state": ""
},
"delivery_address": {
"att_contact": "Att contact",
"company_name": "Company name",
"address_1": "Address 1",
"address_2": "Address 2",
"city": "City",
"zip": "8600",
"country_code": "DK",
"state": ""
},
"pickup_address": {
"att_contact": "Att contact",
"company_name": "Company name",
"address_1": "Address 1",
"address_2": "Address 2",
"city": "City",
"zip": "8600",
"country_code": "DK",
"state": ""
},
"return_address": {
"att_contact": "Att contact",
"company_name": "Company name",
"address_1": "Address 1",
"address_2": "Address 2",
"city": "City",
"zip": "8600",
"country_code": "DK",
"state": ""
},
"drop_point": {
"drop_point_id": "123",
"name": "Gls pakkeshop, Circle-K",
"address_1": "Frederiksberggade 99",
"address_2": null,
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"state": null,
"routing_code": "ABC"
},
"comment": "Drop the package in my garage",
"packages": [
{
"id": 13,
"weight": 1000.0,
"weight_unit": "g",
"customs_lines": [
{
"sku": "SKU",
"description": "Goods description",
"quantity": 1,
"tarif_number": "234234234234",
"country_of_origin": "DK",
"unit_price": 99,
"vat_percent": 25.0,
"currency": "EUR"
}
],
"add_ons": ["FRAGILE"],
"service_attributes": {
"transport_type": "pallet"
},
"dimensions": {
"height": 10,
"width": 20,
"length": 30,
"unit": "cm"
}
}
],
"documents": [
{
"document_data": "JVBERi0xLjMKJf////8K......=",
"document_type": "invoice",
"document_format": "PDF",
"document_size": "A4"
}
]
}
Expected response from the carrier implementation
{
"success": true,
"carrier_code":"MYCARRIER",
"tracking_links": [
{
"url": "http://tracking.no?no=123",
"number": "123",
"package_id": 13
}
],
"labels": [
{
"label_size": "100X150",
"label_format": "PDF",
"label_data": "JVBERi0xLjMKJf////8KM.....="
}
],
"documents": [
{
"document_size": "A4",
"document_format": "PDF",
"document_data": "JVBERi0xLjMKJf////8K......="
}
]
}
Drop points are locations from where recipients can pick up their parcels. To provide this, you must provide a service that returns drop points in the specified format.
Please notice that, the implementation must be able to search for drop points solely on the basis of the country and the zip code.
If you need the customers to be able to only provide a drop_point_id when booking a shipment, the drop_point_id attribute will be filled in the request, with the corresponding ID. It's expected that the drop_points array in the response, will then contain the full address of the requested drop_point_id
{
"carrier_code":"GLS",
"service_code":"PARCELSHOP",
"delivery_address":{
"company_name":"Webshipr ApS",
"att_contact":"Att contact",
"address_1":"Test address",
"address_2":"",
"city":"Silkeborg",
"zip":"8600",
"country_code":"DK",
"state":"",
"routing_code": "ABC"
},
"drop_point_id": "",
"test_mode": false
}
Expected response from the carrier implementation
Please note that days in the opening hours array are 0-indexed, starting with Monday as 0
{
"drop_points":[
{
"drop_point_id":"234",
"name": "Pakkeshop Cirkel-K",
"address_1": "Frederiksberggade 29",
"address_2": "",
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"state": "",
"routing_code": "ABC",
"latitude":"7.45456",
"longitude":"4.3453444",
"opening_hours": [
{
"day": 0,
"opens_at": "00:00",
"closes_at": "23:59"
},
{
"day": 1,
"opens_at": "00:00",
"closes_at": "23:59"
},
{
"day": 2,
"opens_at": "00:00",
"closes_at": "23:59"
},
{
"day": 3,
"opens_at": "00:00",
"closes_at": "23:59"
},
{
"day": 4,
"opens_at": "00:00",
"closes_at": "23:59"
},
{
"day": 5,
"opens_at": "00:00",
"closes_at": "23:59"
},
{
"day": 6,
"opens_at": "00:00",
"closes_at": "23:59"
}
]
}
]
}
A waybill is a group of shipments, typically used for bulk shipments. The waybill endpoint is not mandatory.
When a waybill is opened and closed, Webshipper will make a POST request in both cases. The action code will be either open
or close
.
{
"carrier_code":"POSTNORDDK",
"action_code": "open",
"reference": null,
"barcode_serial": "234234234",
"carrier_attributes": {
"username": "TEST USER",
"api_token": "TEST TOKEN"
}
shipments: [
{
"service_code": "VAREBREV",
"delivery_address": {},
"billing_address": {},
"drop_point": {},
"order_lines": [],
"packages" : []
}
]
}
Expected response from the carrier implementation ( Open ) 200 OK
{
"reference": "REF134"
}
Expected response from the carrier implementation ( Close ) 200 OK
{
"status": "closed",
"documents": [
{
"document_size": "A4",
"document_format": "PDF",
"document_data": "JVBERi0xLjMKJf////8K......="
}
]
}
The pickup endpoint can enable customers to create pickup requests through the webshipper interface.
This endpoint is not mandatory.
{
"carrier_code":"DHLEXPRESS",
"carrier_attributes": {
"username": "TEST USER",
"api_token": "TEST TOKEN"
},
"pickup_time": "2018-09-24 11:44:54 +0200",
"pickup_location_close_time": "2018-09-24 16:00:00 +0200",
"pickup_instruction": "Please use the doorbell on the right side of the building.",
"time_zone": "Europe/Copenhagen",
"shipping_address": {
"att_contact": "Att contact",
"company_name": "Company name",
"address_1": "Address 1",
"address_2": "Address 2",
"city": "City",
"zip": "8000",
"country_code": "DK",
"state": ""
},
"shipments": [
{
"service_code": "DHLDOMESTIC",
"delivery_address": {},
"billing_address": {},
"drop_point": {},
"order_lines": [],
"packages" : []
}
]
}
Expected response from the carrier implementation ( 200 OK )
{
"reference": "REF134"
}
This endpoint enables the possibility to override the native webshipper End Of Day report.
The endpoint is not mandatory.
{
"test_mode": false,
"carrier_code":"DHLEXPRESS",
"start_time": "2018-10-18 10:17:29 +0200",
"end_time": "2018-10-18 10:17:29 +0200",
"carrier_attributes": {
"username": "TEST USER",
"api_token": "TEST TOKEN"
},
"shipments": [
{
"service_code": "DHLDOMESTIC",
"delivery_address": {},
"billing_address": {},
"drop_point": {},
"order_lines": [],
"packages" : []
}
]
}
Expected response from the carrier implementation ( 200 OK )
{
"report": "JVBERi0xLjMKJf////8KM.....="
}
The report data must contain Base64 encoded PDF in A4 format.
This endpoint is used to get information about tracking and transit events. This endpoint is not mandatory.
The response must be list of "tracking_responses", each containing a tracking number and a list of tracking events, each with following attributes:
status
One of the tracking event statuses defined on the Tracking Event resource.
time
An ISO 8601 timestamp for the time the event occured.
details
Human friendly description of the tracking event.
location
Description of where the event occured. No specific format is required. Optional.
event_id
Unique identifier for the tracking event. An event_id should be unique across all tracking numbers, and consistent for each call to this endpoint for each tracking number.
It is not necessary to return all tracking events for each request, as events are saved by Webshipper. Changes to previously sent tracking events are ignored.
{
"test_mode": false,
"carrier_code":"DHLEXPRESS",
"carrier_attributes": {
"username": "TEST USER",
"api_token": "TEST TOKEN"
},
"tracking_numbers": ["8655349872"]
}
Tracking numbers are consistent with those returned from the Booking endpoint.
Expected response from the carrier implementation (200 OK)
{
"tracking_responses": [
{
"tracking_number": "8655349872",
"tracking_events": [
{
"status": "information_received",
"time": "2018-11-23T14:09:18+01:00",
"details": "We received infomation about the order, but have yet to pick it up",
"location": null,
"event_id": "7904d334-efa2-4483-b23a-358d4839531e"
},
{
"status": "in_transit",
"time": "2018-11-24T05:01:10+01:00",
"details": "Picked up by our truck",
"location": "Streetname 123, DK-7400",
"event_id": "c4be3fd4-f525-40cc-b45b-914eac45f2ee"
},
{
"status": "in_transit",
"time": "2018-11-24T06:58:32+00:00",
"details": "Being sorting in our hub",
"location": "Aarhus Hub, Warehouse Street 53, DK-8000",
"event_id": "66a7192f-78e0-4bb7-90fe-6f9afd335bc8"
},
{
"status": "delivered_to_drop_point",
"time": "2018-11-26T04:10:25+00:00",
"details": "Delivery to parcel shop",
"location": "Kvickly Strøget, Strøget 1, DK-9000",
"event_id": "701d18c0-6992-44c0-98c1-949a871579b8"
},
{
"status": "delivered",
"time": "2018-11-26T06:17:38+00:00",
"details": "Handed over to customer. Great!",
"location": null,
"event_id": "fa49833b-ce3a-4955-ae4f-531a2238c60f"
}
]
}
]
}
This endpoint is used to validate a carrier and is sent when a carrier is updated in Webshipper. Any errors returned with this endpoint is presented to the user. A carrier cannot be created in Webshipper until this endpoint returns a success response (that is, if this endpoint is used).
{
"test_mode": false,
"carrier_code":"DHLEXPRESS",
"carrier_attributes": {
"username": "TEST USER",
"api_token": "TEST TOKEN"
},
}
Expected response from the carrier implementation (200 OK)
{
"valid": true
}
This endpoint is used when a carrier needs information about orders in Webshipper that is to be shipped with the carrier, but before a shipment is booked. If your carrier needs intermediate information to better provide better delivery times, better plan ahead or just for early statistics you can use the prebooking endpoint to get information about the potential shipment. The request to the prebooking endpoint is made based on the selected shipping rate in Webshipper. If the selected shipping rate has a carrier that supports prebooking a request is sent immediately. A prebooking is also sent later if the shipping rate is changed to a carrier that supports prebookings.
Note: No cancellation of the prebooking is sent if the shipping rate changes after a prebooking request is sent.
{
"request_type": "prebooking_request",
"test_mode": false,
"carrier_code": "MYCARRIER",
"service_code": "MYSERVICECODE",
"carrier_attributes": {
"barcode_prefix": "57125",
"customer_id": "12345"
},
"service_attributes": {
"delivery_message": "Deliver before 19:00"
},
"add_ons": ["COD"],
"sender_address": {
"att_contact": "Att contact",
"company_name": "Company name",
"address_1": "Address 1",
"address_2": "Address 2",
"city": "City",
"zip": "8600",
"country_code": "DK",
"state": ""
},
"billing_address": {
"att_contact": "Att contact",
"company_name": "Company name",
"address_1": "Address 1",
"address_2": "Address 2",
"city": "City",
"zip": "8600",
"country_code": "DK",
"state": ""
},
"delivery_address": {
"att_contact": "Att contact",
"company_name": "Company name",
"address_1": "Address 1",
"address_2": "Address 2",
"city": "City",
"zip": "8600",
"country_code": "DK",
"state": ""
},
"drop_point": {
"drop_point_id": "123",
"name": "Gls pakkeshop, Circle-K",
"address_1": "Frederiksberggade 99",
"address_2": null,
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"state": null,
"routing_code": "ABC"
},
"comment": "Drop the package in my garage"
}
Expected response from the carrier implementation (200 OK)
{
"success": true
}
The Webshipper Expression Language (WEL) is an expression language created by Webshipper for the purpose of writing highly customisable matchers. WEL expressions are used for finding the correct price for a Shipping Rate as well as for triggering automations. WEL expressions are given JSON-like objects as input.
If this expression
(delivery_address.country_code = 'NO' and weight in 1000-2000 and not (sender_address.zip in 1000-5000) and price > 200 ) or (packages.count >= 2)
Is given the following input:
{
"weight": 1100,
"delivery_address": {
"zip": "10200",
"country_code": "NO"
},
"sender_address": {
"zip": "8000",
"country_code": "DK"
},
"packages": [
{
"weight": 500
},
{
"weight": 600
}
]
}
It will evaluate to true.
x
and y
are any WEL expressions
Syntax | Example |
---|---|
12
|
|
12.0
|
|
'String literal'
|
|
true
|
order.order_lines all is_virtual = true
|
false
|
order.order_lines any is_virtual = false
|
x and y
|
delivery_address.country_code = 'DK' and weight > 1000
|
x or y
|
delivery_address.country_code = 'DK' or weight > 1000
|
x = y
|
delivery_address.country_code = 'DK'
|
x like y
|
delivery_address.sku like 'Loc123-'
|
x > y
|
weight > 1000
|
x < y
|
weight < 1000
|
x >= y
|
weight >= 1000
|
x <= y
|
weight <= 1000
|
( x )
|
delivery_address.country_code = 'DK' and (weight < 10 or weight > 100)
|
x in i-j
, where i and j are integers
|
delivery_address.zip in 3000-9999
|
not x
|
not (delivery_address.county_code = 'DK')
|
x.count
|
order.order_lines.count
|
x.some_allowed_attribute
|
order.visible_ref
|
x any y
|
order.order_lines any sku = '1245'
|
x all y
|
order.order_lines all is_virtual = true
|
x present?
|
order.drop_point present?
|
x in 'a', 'b', 'c'
|
order.order_lines any sku in '213', '543', '978'
|
The Webshipper Template Language (WTL) is a template language created by Webshipper for the purpose of designing e-mail templates for tracking notifications and parcel slips. WTL may be utilised through several different mechanisms, such as placeholders, conditions etc.
Placeholders make it possible to insert dynamic data. Data may be inserted by accessing objects inside curly brackets. For example, a shipment object is available for tracking mails and it may be used as follows:
Order {{shipment.reference}}
Conditions allow you to render content conditionally, this may be done through if-conditions as follows:
{% if order.order_channel_id == 1 or order.visible_ref contains 'SHOP1' %}
This is order channel 1
{% else %}
This is not order channel 1
{% endif %}
The following operators are supported for conditions:
Operator | Function |
---|---|
== | equals |
!= | not equals |
> | greater than |
< | less than |
<= | less than or equal |
>= | greater than or equal |
or | Condition A or condition B |
and | Condition A and condition B |
You may iterate through collections using 'for'-loops.
{% for tracking in shipment.tracking_links %}
<a href="{{tracking.url}}" class="button">Track #{{tracking.number}}</a>
{% endfor %}
Filters allow you to pipe information, manipulate the input and return any desired output. In the following example, we pipe 'DK' through the country-filter and the resulting output is then piped through the downcase-filter, which will return 'denmark'.
{{ 'DK' | country | downcase }}
Currently supported filters:
Filter | Description |
---|---|
country | Converts ISO 3166-1 alpha-2 to the name of the country |
append | Lets you append something to a string. Example: {{ 'Webshipper' | append: '.com' }} |
capitalize | Will capitalize the first word in a string |
downcase | Will downcase a word |
upcase | Will upcase a word |
escape | Will escape any html content |
md5 | Converts string into a md5 hash |
hmac_sha256 | Converts string into SHA-256 hash using HMAC. Example: {{ 'stringtohash' | hmac_sha256: 'secret' }} |
pluralize | Outputs singular or plural version. Example: {{ 5 | pluralize: 'package', 'packages' }} outputs 5 packages |
prepend | Prepends to a string. Example: {{ 'car' | prepend: 'Just bought a' }} becomes Just bought a car |
remove | Removes all occurrences og a sub-string. Example: {{ 'Just bought something weird' | remove: 'weird' }} becomes 'Just bought something' |
replace | Replace a string: {{ 'Just bought something weird' | replace: 'weird', 'nice' }} becomes 'Just bought something nice' |
split | Split a string into substrings. Example: {% assign words = "I like webshipper" | split: ' ' %}. Will split the sentence into 3 words which can be iterated. |
url_escape | Escape a URL |
join | Joins collection. Example {{ shipment.add_ons | join: ', ' }} |
pdf_attachment | Include a label or document as a downloadable link. Example {{ label | pdf_attachment('Download Label', 'return-label.pdf') }} |
mail_attachment | Include a label or document as an attachment to an email. Example {{ invoice | mail_attachment('invoice.pdf') }} |
map | Pick a element from a array. Example {{ order.order_lines | map: 'sku' }} |
sum | Gets the sum from an array of numbers. Example {{ [20,50,100] | sum }} |
product_sum | Multiplies the two fields for element in the array and computes the total sum. Example {{ order.order_lines | product_sum: 'quantity', 'unit_price' }} |
group_by | Group an array of object by some path. The key can be a single attribute or a deep dot-separated path. Item will we grouped under 'N/A' if no path or attribute is found. Example {{ shipments | group_by: 'order.order_channel.order_channel_type' }} could yield the object {"Shopify": [{...}, {...}], "WooCommerce": [{...}]} ; |
in_time_zone | Sets the time zone for formatting a timestamp. Example {{ order.created_at | in_time_zone: 'Copenhagen' | date: '%d-%m-%Y %H:%M' }} gives '19-10-2018 09:51'. Valid values can be found in the TZ column here: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
barcode | Adds the possibility to add barcodes to A4 slip templates and in report columns. Takes 2 arguments - first argument is xdim ( width ) second argument is height. Usage: {{'234234'|barcode: '2','20')}}. Will only take effect when this is the only column content. When used in report column, recommended minimum width of column for a xdim of 2 is 35% and xdim of 1 is 20% |
round_nearest | Round integer to nearest defined integer defined in the argument. Can take up to 2 arguments. Example {{ 22.34 | round_rearest: 9 }} will equal 19 or {{ 22.34 | round_rearest: 9, 'up' }}, which will equal 29 |
total_weight_in | Returns the total weight of all products/items in given array, which has a weight attribute. Example {{ order.order_lines | total_weight_in: 'kg' }} |
flatten | Flattens the given array. Can be used to chain the map filter on multiple array properties. Example {{ shipment | map: 'packages' | flatten | map: 'customs_lines' | flatten | map: 'unit_price' | sum }} |
id
Actions as part of automations
Name of a supported job:
If true, this action runs as a background process, if not it runs immediately
Array of objects containing keys attr_values
and attr_value
id
Resource for activity.
Details of the activity
Latitude of the activity
Longitude of the activity
Base64 encoded signature of the activity
Name of the signature
Base64 encoded photo of the activity
Initiator of the activity
id
Read only resource for activity types.
Description of the activity
Key for the activity
Model for the activity
Status of the model
Does the activity require a signature
Does the activity require a photo
Is the activity active
Priority of the activity
id
, active
, model
This resource is used to attach info to orders and order lines
Visible name of the attribute
Key for the attribute
Value of the attribute
id
Attachment are used to associate existing Documents with Orders and Shipments.
id
Attaching to an Order
{
"data": {
"type": "attachments",
"relationships": {
"document": {
"data": {
"type": "documents",
"id": 532
}
},
"has_documents": {
"data": {
"type": "orders",
"id": 532
}
}
}
}
}
Attaching to a Shipment
{
"data": {
"type": "shipments",
"attributes": {
"included_documents": [
{
"document_id": 1
}
]
},
"relationships": {
"order": {
"data": {
"type": "orders",
"id": 123
}
}
}
}
}
With Automations you can build custom workflows on the Webshipper platform using highly flexible Triggers and Actions.
Flattened resource of type Trigger
Array of flattened resources of type Action
id
id
This resource is used to describe the barcode ranges provided to you by a carrier.
String like DPD or SSCC
The first barcode in the range
The last barcode in the range
id
Bulk import orders based on an array of ids
Order ids to import from the order channel
Id of the order channel to import orders from
Run the import asyncronously, default is false unless importing more than one order or from more than one order channel
Reimport orders from the order channel. WARNING: This will overwrite any changes to the order made in Webshipper and import the order as it is in the order channel
Time from when orders should be imported, all orders after this time is imported from the order channel. This option is not supported by all order channels and there might be some limitations depending on the order channel
Time to when orders should be imported, all orders before this time is imported from the order channel. This option is not supported by all order channels and there might be some limitations depending on the order channel
Statuses of orders to import, all orders with the given statuses are imported from the order channel. This option is not supported by all order channels and there might be some limitations depending on the order channel
List of bulk imports with the same attributes as above. This can be used to import multiple orders from multiple order channels at once. Options specified in the root object is used globally, but is overridable by specififying the option for specific bulk_import in the list.
Source of the orders to import. This will default to API
id
Describes how to parse an uploaded CSV file
The seperator in the file. Normally ';' or ','
Must be one of the models Order
or Shipment
Must be the index of the Order ID
The sub-model which you are grouping. For order: order_lines_attributes
Determines if there is an ignorable header line in the file
Name of the configuration
Example input to make it easier to create the mapping in the UI.
Array of flattened resources of the type CSV Rule
id
Describes how an entry in a CSV file should map to an attribute in a resource.
Path of the attribute to update
The index of the field in the CSV file to be mapped
Value to use if the value in the CSV file is empty or missing
A key/value mapping for converting values before creating the object
id
Used to import records from CSV files (or similar formats). CSV Mapping Rules provides the details for how to import the records.
The raw CSV data
If set to true, the import will be performed in background. Highly recommended for imports larger than 100 rows.
id
Your name for the carrier
Array of services provided by this Carrier
Array of hashes with keys: attr_key
, attr_value
, attr_name
, attr_type
, is_required
, only_visible_on_creation
, enums. See
documentation for Local Attributes
id
, billable
, carrier_type_codes
, carrier_group_id
Grants access to the carrier's shipments for a single user. This has no effect if the user has access to all carriers.
id
Read-only endpoint to fetch information of the available carrier types.
Logo for the carrier
Logo for the carrier
Name of the carrier
Code identifying the carrier
Description of the carrier
Details required to use the carrier
Boolean indicating wether the carrier supports shipment updates
Number of minutes before shipment time a shipment can be updated
Determines whether the carrier supports colli types.Values should be one of the following. null: Not supported, "carrier_provided": Values are determined by the carrier, "webshipper_provided": Default Webshipper colli types, "customer_provided": The customer can input colli types specific to their aggreement with the carrier.
id
, carrier_code
, carrier_group_id
Customs Lines is generally created as part of a shipment creation and should it should never be necessary to call this resource directly.
Stock Keeping Unit
Goods description
Quantity of the customs line
Tariff number / HS code
Country of origin of the customs line - ISO 3166-1 alpha-2
Unit price of a single quantity customs line
Vat percent of the customs line
Currency ISO-4217
Weight of a single quantity customs line
Weight unit of the customs line - One of 'g', 'oz', 'lbs' or 'kg'
Discount of a single quantity customs line
Optional object of key value pairs used for providing information of dangerous goods. For use with DGOffice, use keys: article_no, package_type_id and packaging_instruction_type.
id
Additional shipment documents. This is used for customs declarations etc. Documents are limited to 5mb.
Id of the shipment it belongs to
Enum for the paper size. valid values: A4
Enum for the document format. Valid values: PDF
Base64 representation of the document. Only required when creating.
Used to indicate if this document is a special document, like static customs documents. Special documents will be displayed in Webshipper under Settings > Documents.
Used for special documents
Used for special documents
One of: 'shipping_document', 'other', 'customs_document', 'invoice', 'certificate', 'proforma', 'nafta_certificate', 'commercial', 'awb'. Documents returned from the carrier are always shipping_document.
Used to indicate if a shipment is paperless
id
, is_special
Read only resource for document templates.
Number of copies
Type of document
Overrides for the document
Defaults for the document
Notify
Email address
Email body
Email filename
id
, document_type
Drop point for orders. To locate drop points, please refer to 'Drop Point Locator'
The carriers ID of the drop point.
Name of the drop point
Address line 1 of the drop point
Address line 2 of the drop point
Zip code for the drop point
City for the drop point
Country Code for the drop point. ISO 3166-1 Alfa 2
State code. ISO 3166-2 Alfa 2
Phone of the drop point
Text base code to identify the carrier of the drop point ( not mandatory )
Routing code for the drop point.
Longitude
Latitude
id
Used to find the geographically closest drop points.
ID of the carrier that you want to quote. This is only mandatory if no shipping_rate_id is given.
Service code for the service that you want to quote. This is only mandatory if no shipping_rate_id is given.
ID of the shipping rate that you want to quote. This is only mandatory if no carrier_id is given..
Flattened shipping address object. zip
and country_code
are required and address_1
is optional.
Array of drop points near delivery_address. This will be populated in the response.
id
Query droppoints near address by carrier and service code
{
"data": {
"type": "drop_point_locators",
"attributes": {
"carrier_id": 1,
"service_code": "PARCELSHOP",
"delivery_address": {
"address_1": "Lyngbygade 8",
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK"
}
}
}
}
Query droppoints near address by shipping rate ID
{
"data": {
"type": "drop_point_locators",
"attributes": {
"shipping_rate_id": 1,
"delivery_address": {
"address_1": "Lyngbygade 8",
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK"
}
}
}
}
This resource describes an EDI file. This file will be uploaded to an FTP server configured by the carrier.
Must be one of 'pending', 'on_hold' or 'sent'
The file contents (as text)
Must be either 'utf8' or 'ascii'
id
, shipment_id
, waybill_id
A report of all shipment for the day of start_time.
Base64 encoding of the PDF document. This must explicitly be included with fields[end_of_day_reports]='base64'
Datetime representing the start time for the report
Datetime representing the end time for the report
id
id
Timeline event for orders or shipments
FontAwesome 4 compatible icon like: exclamation, trash, truck, envelope, cog, anchor, map-marker, certificate
Will be set by the Webshipper API
id
Adding event to order
{
"data": {
"type": "events",
"attributes": {
"title": "Unable to capture order",
"details": "Log reference 12333-34-23-342",
"icon": "exclamation"
},
"relationships": {
"model": {
"data": {
"type": "orders",
"id": 100
}
}
}
}
}
id
Favourite page lets you store a list of favourite pages to easily navigate the Webshipper platform. The favourites can quickly be accessed by assigning it a hotkey
Path of the favourite page
Name of the favourite page
id
, user_id
id
Hot key lets you define a key combination for quickly accessing your favourite pages
Key combination of the hotkey
Path the hotkey is assigned to
id
A shipping label. Shipping labels wrap PDF documents.
Accepts a query parameter called 'download_as' which can be either 'PDF' or 'PNG'.
Note: when 'download_as' is set to something other than PDF, the returned value in the base64 attribute will be an array of base64 strings, instead of a single base64 string
Size of the label. Enum with possible values: '100X100', '100X150', '100X192', 'A4'.
Label format. Enum with possible values: 'PDF', 'ZPL'.
Base64 encoding of the pdf document. (Can be an array, see the description above)
id
{
"data": {
"id": "1",
"type": "labels",
"links": {
"self": "/v2/labels/1"
},
"attributes": {
"shipment_id": 2,
"label_size": "100X150",
"label_format": "PDF",
"base64": null,
"updated_at": "2024-03-01T10:12:48.0Z",
"created_at": "2024-03-01T10:12:48.0Z"
},
"relationships": {
"print_jobs": {
"links": {
"self": "/v2/labels/1/relationships/print_jobs",
"related": "/v2/labels/1/print_jobs"
}
}
},
"meta": {
"copyright": "© 2024 Webshipper ApS"
}
}
}
As opposed to Global Attributes, Local Attributes are used for creating Attributes for Order Channels and Carriers.
Visible name of the attribute
Key for the attribute. Used by the system to read the correct information
Data type. Must be either of the following: string
, integer
or password
Determines if the form should require the attr to be filled
Help text to describe the attribute
Determines if the form should only be visible when connecting
id
{
"data": {
"id": "9",
"type": "local_attrs",
"links": {
"self": "/v2/local_attrs/9"
},
"attributes": {
"attr_name": "Shop Access Token",
"attr_key": "access_token",
"attr_type": "password",
"is_required": true,
"description": null,
"requirement_type": "carrier_details",
"category": null,
"priority": null,
"only_visible_on_creation": false
},
"relationships": {
"order_channel_type": {
"links": {
"self": "/v2/local_attrs/9/relationships/order_channel_type",
"related": "/v2/local_attrs/9/order_channel_type"
}
},
"local_attr_enums": {
"links": {
"self": "/v2/local_attrs/9/relationships/local_attr_enums",
"related": "/v2/local_attrs/9/local_attr_enums"
}
},
"local_attr_translations": {
"links": {
"self": "/v2/local_attrs/9/relationships/local_attr_translations",
"related": "/v2/local_attrs/9/local_attr_translations"
}
}
},
"meta": {
"copyright": "© 2024 Webshipper ApS"
}
}
}
A set of predefined values allowed for a Local Attribute.
Visible name for the enum
Value for the enum
id
{
"data": {
"id": "9",
"type": "local_attr_enums",
"links": {
"self": "/v2/local_attr_enums/9"
},
"attributes": {
"enum_name": null,
"enum_value": null
},
"relationships": {
"local_attr": {
"links": {
"self": "/v2/local_attr_enums/9/relationships/local_attr",
"related": "/v2/local_attr_enums/9/local_attr"
}
}
},
"meta": {
"copyright": "© 2024 Webshipper ApS"
}
}
}
id
id
, purpose
ID of order to merge order lines in to
Orders from which to merge order lines from. Orders as nested resources
id
Whether to include labels or not
Whether to include docs or not'
Whether to include slips or not
Whether to use A4 paper size not
A list of shipment ids to include in the merged pdf
A list of order ids to include in the merged pdf
id
id
This resource describes all of the access tokens for the appllication.
The scopes to which access is granted by the access token.
Id of the owner
Epoch timestamp of the expiration date for the token
The access token
Datetime of the time the token was revoked - if revoked
The application to which this tokens grants access
id
{
"data": {
"id": "1",
"type": "oauth_access_tokens",
"links": {
"self": "/v2/oauth_access_tokens/1"
},
"attributes": {
"scopes": "read_orders,read_shipments",
"created_at": null,
"resource_owner_id": null,
"expires_in": null,
"expired": null,
"revoked_at": null,
"resource_owner": null,
"application_id": null
},
"relationships": {
"application": {
"links": {
"self": "/v2/oauth_access_tokens/1/relationships/application",
"related": "/v2/oauth_access_tokens/1/application"
}
}
},
"meta": {
"copyright": "© 2024 Webshipper ApS"
}
}
}
Applications which can act on behalf of users in Webshipper. Application Tokens have infinite lifetime. See the section titled Authentication for more details on using OAuth2.
Application name
Unique id
The scopes which the OAuth application will be granted.
OAuth redirect URI
id
, uid
, active
{
"data": {
"id": "1",
"type": "oauth_applications",
"links": {
"self": "/v2/oauth_applications/1"
},
"attributes": {
"name": "Webshipr Silent Printer",
"uid": "61562ee483af1ce331444013ab8c167201615465e9e5f0067b",
"scopes": "read_orders,read_shipments",
"redirect_uri": null,
"created_at": null,
"updated_at": null
},
"relationships": {
"access_tokens": {
"links": {
"self": "/v2/oauth_applications/1/relationships/access_tokens",
"related": "/v2/oauth_applications/1/access_tokens"
}
}
},
"meta": {
"copyright": "© 2024 Webshipper ApS"
}
}
}
Orders can be used to keep track of items to be shipped, for example when preparing the contents of a parcel and following that, an order can be the basis for one or more shipments. Orders can also handle customs information as well as shipping rates.
DEPRECATED Assign a relation instead
Enum status of the order. Possible values: pending, dispatched, partly_dispatched, cancelled, error, missing_rate, on_hold
External ( hidden ) reference for the order. Used by system to update the order in e.g. order channels. Must be unique in scope of order channels.
Visible reference - the friendly/visible external order number
Flattened resource of type DropPoint. Must be assigned when the order must be delivered to a drop point.
Flattened resource describing the original shipping option from the order channel. This will be used for matching in cases where shipping was not quoted from Webshipper.
Flattened resource of type OrderLine
Flattened resource of type ShippingAddress
Flattened resource of type ShippingAddress. If the address is not assigned - the sender address of the order channel will be used.
Flattened resource of type ShippingAddress. Will be duplicated from delivery address if not assigned.
Flattened resource of type ShippingAddress. Will be duplicated from sender address if not assigned.
Currency code of the order
Latest comment with type 'internal'. Changing this, will create a new comment
External order comment. Will typically be the order comment from e-commerce checkout.
Any error message that resulted from the latest attempt at making a shipment from the order.
When an order is locked, it cannot be modified or sent until it is unlocked. Possible values: locked
or unlocked
.
A description of how the order was created in Webshipper. Possible values: 'api', 'manual' or 'csv'
Array of strings used to tag an order
A string like 'address' or 'carrier_downtime' describe which type of error caused the order to fail
id
, ext_ref
, sorting_id
, created_at
, updated_at
, status
, visible_ref
, slip_printed
, label_printed
, lock_state
, order_channel
, order_channel_id
, shipping_rate
, shipping_rate_id
, carrier
, sku
, free_text
, tag
, delivery_country_code
, activity_type
, order_lines
, billing_contact
, billing_company
, billing_email
{
"data": {
"id": "12",
"type": "orders",
"links": {
"self": "/v2/orders/12"
},
"attributes": {
"order_channel_id": 2,
"status": "pending",
"ext_ref": "ID123",
"visible_ref": "a7g54",
"drop_point": {
"id": null,
"order_id": 12,
"drop_point_id": "141122",
"name": "Cirkel K on Testroad",
"address_1": "Test road 11",
"address_2": null,
"zip": "8000",
"city": "Århus C",
"country_code": "DK",
"state": null,
"created_at": null,
"updated_at": null,
"phone": "99999999",
"email": null,
"longitude": null,
"latitude": null,
"carrier_code": null,
"routing_code": "RTC"
},
"original_shipping": {
"id": null,
"order_id": 12,
"shipping_code": "EXPRESS",
"shipping_name": "Express shipping",
"price": 99.0,
"vat_percent": 25.0,
"created_at": null,
"updated_at": null
},
"order_lines": [
{
"id": 2,
"sku": "ZB420",
"description": "Zebra GK420d label printer",
"quantity": 1,
"location": "LOC 3563-67",
"tarif_number": "844332",
"country_of_origin": "DK",
"unit_price": 24.0,
"vat_percent": 25.0,
"order_id": 12,
"status": null,
"ext_ref": "342342",
"created_at": null,
"updated_at": null,
"package_id": null,
"weight": 500.0,
"weight_unit": "g",
"discount_value": 0.0,
"discount_type": "fixed",
"is_virtual": false,
"dangerous_goods_details": {
},
"discounted_unit_price": 24.0,
"additional_attributes": {
"color": "blue",
"in_stock": "1"
}
}
],
"delivery_address": {
"id": null,
"att_contact": "Awesome developer",
"company_name": "Webshipper",
"address_1": "lyngbygade 8",
"address_2": null,
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"state": null,
"phone": "80808080",
"email": "support@webshipper.com",
"created_at": null,
"updated_at": null,
"address_type": "recipient",
"vat_no": null,
"ext_location": null,
"company_customs_numbers": {
},
"formatted_recipient": "Webshipper att. Awesome developer",
"voec": null,
"eori": null,
"sprn": null,
"personal_customs_no": null
},
"sender_address": {
"id": null,
"att_contact": "",
"company_name": "Printers inc.",
"address_1": "Michael Drewsensvej 21",
"address_2": null,
"zip": "8000",
"city": "Århus",
"country_code": "DK",
"state": null,
"phone": null,
"email": null,
"created_at": null,
"updated_at": null,
"address_type": "recipient",
"vat_no": null,
"ext_location": null,
"company_customs_numbers": {
},
"formatted_recipient": "Printers inc.",
"voec": null,
"eori": null,
"sprn": null,
"personal_customs_no": null
},
"billing_address": {
"id": null,
"att_contact": "Awesome developer",
"company_name": "Webshipper",
"address_1": "lyngbygade 8",
"address_2": null,
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"state": null,
"phone": "80808080",
"email": "support@webshipper.com",
"created_at": null,
"updated_at": null,
"address_type": "recipient",
"vat_no": null,
"ext_location": null,
"company_customs_numbers": {
},
"formatted_recipient": "Webshipper att. Awesome developer",
"voec": null,
"eori": null,
"sprn": null,
"personal_customs_no": null
},
"sold_from_address": null,
"currency": "DKK",
"internal_comment": "Internal comment",
"external_comment": "We need the order ASAP. If no one on the office, place the package in front of the door",
"error_message": null,
"updated_at": null,
"created_at": null,
"lock_state": "unlocked",
"source": "api",
"tags": [
"PRIORITY",
"BEFORE_10"
],
"error_class": null,
"slip_printed": null,
"label_printed": null,
"create_shipment_automatically": false,
"latest_activity": null,
"latest_status_event": null,
"shipping_rate_id": null,
"csv_upload_id": null
},
"relationships": {
"order_channel": {
"links": {
"self": "/v2/orders/12/relationships/order_channel",
"related": "/v2/orders/12/order_channel"
}
},
"shipping_rate": {
"links": {
"self": "/v2/orders/12/relationships/shipping_rate",
"related": "/v2/orders/12/shipping_rate"
}
},
"error_type": {
"links": {
"self": "/v2/orders/12/relationships/error_type",
"related": "/v2/orders/12/error_type"
}
},
"printer_client": {
"links": {
"self": "/v2/orders/12/relationships/printer_client",
"related": "/v2/orders/12/printer_client"
}
},
"shipments": {
"links": {
"self": "/v2/orders/12/relationships/shipments",
"related": "/v2/orders/12/shipments"
}
},
"additional_attributes": {
"links": {
"self": "/v2/orders/12/relationships/additional_attributes",
"related": "/v2/orders/12/additional_attributes"
}
},
"print_jobs": {
"links": {
"self": "/v2/orders/12/relationships/print_jobs",
"related": "/v2/orders/12/print_jobs"
}
},
"packages": {
"links": {
"self": "/v2/orders/12/relationships/packages",
"related": "/v2/orders/12/packages"
}
},
"events": {
"links": {
"self": "/v2/orders/12/relationships/events",
"related": "/v2/orders/12/events"
}
},
"attachments": {
"links": {
"self": "/v2/orders/12/relationships/attachments",
"related": "/v2/orders/12/attachments"
}
},
"documents": {
"links": {
"self": "/v2/orders/12/relationships/documents",
"related": "/v2/orders/12/documents"
}
},
"activities": {
"links": {
"self": "/v2/orders/12/relationships/activities",
"related": "/v2/orders/12/activities"
}
},
"status_events": {
"links": {
"self": "/v2/orders/12/relationships/status_events",
"related": "/v2/orders/12/status_events"
}
},
"returns": {
"links": {
"self": "/v2/orders/12/relationships/returns",
"related": "/v2/orders/12/returns"
}
},
"comments": {
"links": {
"self": "/v2/orders/12/relationships/comments",
"related": "/v2/orders/12/comments"
}
},
"stores": {
"links": {
"self": "/v2/orders/12/relationships/stores",
"related": "/v2/orders/12/stores"
}
}
},
"meta": {
"copyright": "© 2024 Webshipper ApS"
}
}
}
Creating an order with a drop point
{
"data": {
"type": "orders",
"attributes": {
"drop_point": {
"drop_point_id": 12,
"address_1": "Street 123",
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"carrier_code": "DUMMY"
},
"delivery_address": {
"address_1": "Lyngbygade 8",
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK"
},
"sender_address": {
"address_1": "Example street 2",
"zip": "7400",
"city": "Herning",
"country_code": "DK"
},
"order_lines": [
{
"sku": "ZB420",
"description": "Zebra GK420d label printer",
"quantity": 1,
"location": "LOC 3563-67",
"tarif_number": "844332",
"country_of_origin": "DK",
"unit_price": 24.0,
"vat_percent": 25.0,
"order_id": 12,
"ext_ref": "342342",
"weight": 500.0,
"weight_unit": "g",
"discount_value": 0.0,
"discount_type": "fixed",
"discounted_unit_price": 24.0
}
]
},
"relationships": {
"order_channel": {
"data": {
"id": 9,
"type": "order_channels"
}
},
"shipping_rate": {
"data": {
"id": 6,
"type": "shipping_rates"
}
}
}
}
}
An order channel models a specific integration with a webshop or ERP-system. Order channels are configured with attributes. During setup, 'additional_parameters' can be used to support customer authorisation flow (like the OAuth2 Authorisation Code grant type).
Label to identify the order channel.
Array of hashed with keys: attr_key
, attr_value
, attr_name
, attr_type
, is_required
, only_visible_on_creation
enums. See
documentation for Local Attributes
Optional hash, this is used when creating new order channels.
Possible values: 'dont_print', 'print_immediately' or 'print_with_shipment'.
Possible values: 'dont_print', 'print_immediately'.
Possible values: 'dont_print', 'print_immediately'.
Possible values: 'dont_print', 'print_immediately'.
Base64 representation of the logo of the order channel.
Token to use for Webshipper modules. Tokens will only be generated for modules that require a configuration token.
Determines if the order channel is currently synchronising. Possible values are: synchronize
, suspended
, paused
.
Shows if recent synchronisation events have failed.
Whether or not to fulfill the order in the original order channel when a shipment is created. Default: true
id
, attr
{
"data": {
"id": "2",
"type": "order_channels",
"links": {
"self": "/v2/order_channels/2"
},
"attributes": {
"channel_label": "My Shopify Shop",
"attrs": [
{
"attr_key": "shop_name",
"attr_value": "myshop.myshopify.com",
"attr_name": "Shop name",
"attr_type": "text",
"description": null,
"is_required": true,
"only_visible_on_creation": false,
"category": null,
"priority": null,
"enums": [
]
}
],
"additional_parameters": null,
"slip_print_mode": "print_immediately",
"return_label_print_mode": "print_immediately",
"shipping_label_print_mode": "print_immediately",
"document_print_mode": "print_immediately",
"logo": null,
"configuration_token": null,
"sync_status": "synchronize",
"failed_sync_count": 0,
"fulfill_automatically": true,
"drop_point_limit": 10,
"create_shipment_automatically": false,
"health": {
"health": 1,
"health_1h": 1,
"health_1d": 1,
"health_1w": 1
},
"convert_currency_on_rate_quotes": null,
"sync_additional_attributes_to_shipments": false,
"auto_order_import": false,
"has_configuration_token": false
},
"relationships": {
"orders": {
"links": {
"self": "/v2/order_channels/2/relationships/orders",
"related": "/v2/order_channels/2/orders"
}
},
"shipping_rates": {
"links": {
"self": "/v2/order_channels/2/relationships/shipping_rates",
"related": "/v2/order_channels/2/shipping_rates"
}
},
"shipping_mappings": {
"links": {
"self": "/v2/order_channels/2/relationships/shipping_mappings",
"related": "/v2/order_channels/2/shipping_mappings"
}
},
"order_channel_sync_entries": {
"links": {
"self": "/v2/order_channels/2/relationships/order_channel_sync_entries",
"related": "/v2/order_channels/2/order_channel_sync_entries"
}
},
"order_channel_type": {
"links": {
"self": "/v2/order_channels/2/relationships/order_channel_type",
"related": "/v2/order_channels/2/order_channel_type"
}
},
"slip_template": {
"links": {
"self": "/v2/order_channels/2/relationships/slip_template",
"related": "/v2/order_channels/2/slip_template"
}
},
"sender_address": {
"links": {
"self": "/v2/order_channels/2/relationships/sender_address",
"related": "/v2/order_channels/2/sender_address"
}
},
"return_address": {
"links": {
"self": "/v2/order_channels/2/relationships/return_address",
"related": "/v2/order_channels/2/return_address"
}
},
"pickup_address": {
"links": {
"self": "/v2/order_channels/2/relationships/pickup_address",
"related": "/v2/order_channels/2/pickup_address"
}
},
"sold_from_address": {
"links": {
"self": "/v2/order_channels/2/relationships/sold_from_address",
"related": "/v2/order_channels/2/sold_from_address"
}
},
"default_printer_client": {
"links": {
"self": "/v2/order_channels/2/relationships/default_printer_client",
"related": "/v2/order_channels/2/default_printer_client"
}
},
"additional_attributes": {
"links": {
"self": "/v2/order_channels/2/relationships/additional_attributes",
"related": "/v2/order_channels/2/additional_attributes"
}
}
},
"meta": {
"copyright": "© 2024 Webshipper ApS"
}
}
}
Grants a user access to an order channel. This has no effect if the user has been granted access to all order channels.
id
Order Channel Types are used to create Order Channels
id
, by_name
Stock Keeping Unit of the order line
Description of the goods
Quantity of goods
The warehouse location of the items.
HS Tarif code for paperless customs
The country of origin of the goods.
The unit price of goods in the currency of the order
Whether the items are associated with a parcel of a shipment.
The unit price after discounts has been applied in the currency of the order
The discount for the order line, in the type given by discount_type
The type of discount, eg. percent or fixed
The VAT rate in percentage.
Possible enum values: pending, dispatched or returned
External reference of the order line.
Weight per unit.
Weight unit. Possible values: oz
, g
, lbs
, kg
. Defaults to g
Optional object of key value pairs used for providing information of dangerous goods. For use with DGOffice, use keys: article_no, package_type_id and packaging_instruction_type.
id
Weight of the package
One of 'g', 'oz', 'lbs' and 'kg'
Colli type of the package. Can be used to specify if the colli is a pallet, package, letter, etc. Should use values from the supported_colli_types field from the service quote/list response for the given service.
A predefined SSCC barcode. Can be used if the barcode already has been created outside of Webshipper.
id
Pickups facilitates the booking of a pickup from a given carrier. Not all carriers supports pickup.
Instruction to the carrier.
When the pickup location is closing.
The time you want the carrier to arrive at the pickup address.
The reference returned by the carrier.
Decides if the pickup is requested
or cancelled
. To cancel a pickup you must update the status to cancelled.
The address where the shipments must be picked up.
The carrier that should pickup the shipments.
id
Bulk add slips to the printer queue
id
id
Printers are loaded automatically when connecting to your account from the Webshipper Silent Printer application.
Name of the printer.
Determines if the printer is configured on the printer station
Last connection time
Paper width
Paper height
id
Printer clients are created automatically when connecting Webshipper Silent Printer and should not be created manually.
Unique ID of the printer client
DEPRECATED
Defaults to the host name of the machine running the client
Shows if the printer client is online
Shows when the printer client was last connected
id
Printer Jobs are used to print documents, labels etc. After a Printer Job is created, it will the sent to the printer client installed on one of your machines. After the printer client has accepted the job, it will mark the Printer Job as completed.
This will return as true
when the printer client has accepted the job.
Any error message that resulted.
id
, printer_client_id
, created_at
, completed
, error
, try_count
, printer_id
id
Get rates for an order channel. This provides a list of all shipping rates whose conditions matched the input. Quotes are not persistent. The id field is always returned as 1 and should be ignored.
Delivery address for the quote. Flattened resource of 'Shipping Address'
The total price of the items
Weight for the quote.
The weight unit. Possible values: g, kg, lbs, oz.
Height for the quote. The unit must match the unit you are using for shipping rate configurations.
Length for the quote. The unit must match the unit you are using for shipping rate configurations.
Width for the quote. The unit must match the unit you are using for shipping rate configurations.
Dimensions unit. Possible values: cm, m, in, ft
Delivery address for the quote. Flattened resource of 'Shipping Address'
Array of items, each item should have fields quantity
, sku
, description
The id of the order channel for which to get shipping rates.
Also include shipping rates which are normally hidden during checkout.
Set to true to quote for return rates. If false standard rates are quoted. Default: false.
Possibility to add hash of additional attributes for filtering.
id
{
"data": {
"id": "1",
"type": "rate_quotes",
"links": {
"self": "/v2/rate_quotes/1"
},
"attributes": {
"quotes": [
{
"price": 99,
"carrier_name": "Test carrier",
"currency": "EUR",
"carrier_logo": "",
"shipping_rate": {
"name": "Test name",
"carrier_id": 4,
"carrier_service_code": "testcode"
}
}
],
"success": true,
"delivery_address": {
"country_code": "DK"
},
"price": 99,
"weight": 10,
"weight_unit": null,
"height": 56,
"length": 12,
"width": 35,
"dimensions_unit": null,
"sender_address": {
"country_code": "NO"
},
"items": [
{
"quantity": 2,
"description": "Black T-shirts",
"sku": "BLK 238"
}
],
"order_channel_id": 12,
"currency": null,
"include_hidden": null,
"is_return": null,
"additional_attributes": null,
"filter_by_currency": null
},
"meta": {
"copyright": "© 2024 Webshipper ApS"
}
}
}
Order Channel Rate Quotes can quote an order channel for matching shipping rates. These quotes are used to display shipping options in e-commerce systems.
{
"data": {
"type": "rate_quotes",
"attributes": {
"order_channel_id": 16,
"price": 199,
"weight": 100,
"delivery_address": {
"zip": "7400",
"country_code": "DK"
},
"items": [
{
"quantity": 5,
"sku": "sku123"
}
]
}
}
}
Reports are generated by using Report Types which specify how a report should look and which records to include in the report.
id
This resource acts a template for creating resource.
Array of objects with keys header
and content
Array of objects with keys parameter_key
and parameter_value
Array of objects with keys header
and content
that will be used to display the header content of the report
Array of objects describing how to load the resources. Contains keys condition_key
, condition_operator
, condition_value
.
If true the report will included deleted records. Default: false
When set to true it will attempt to fetch the end of day list directly from the carrier. When this option is enabled, only pdf reports are available.
id
Find and requeue failed printer jobs within the given timeframe
id
Description of the cause
Does the cause require a comment
Does the cause limit refund methods
Does the cause support image required
id
Read only resource for return lines.
Description of the cause
Quantity of the return line
Refund method for the return line
id
One of pending, sent, arrived, processed, error or approved
Array of ReturnLine objects. Contains fields order_line_id, quantity, cause_id, cause_description and images. When creating, images should be an array of data uri containing the base64 encoding of the image, example: data:image/jpeg;base64,AAQSkZJ......RgABAQEAlgCWAAD
Base 64 encoding of return slip
id
, secret
, activity_type
, status
, portal_id
, free_text
, return_causes
{
"data": {
"id": "1",
"type": "returns",
"links": {
"self": "/v2/returns/1"
},
"attributes": {
"status": "pending",
"error_message": null,
"return_lines": [
{
"id": null,
"return_id": 1,
"order_line_id": 6436,
"cause_id": 53,
"cause_description": "It was too small",
"quantity": 1,
"deleted_at": null,
"created_at": null,
"updated_at": null,
"images": [
],
"refund_method": {
"id": null,
"name": "Gift card",
"description": null,
"portal_id": null,
"created_at": null,
"updated_at": null,
"allowed_days": null,
"payment_required": false,
"excluded_skus": [
]
}
}
],
"secret": null,
"latest_activity": null,
"updated_at": null,
"created_at": null,
"order_channel_id": null,
"internal_session_id": null
},
"relationships": {
"activities": {
"links": {
"self": "/v2/returns/1/relationships/activities",
"related": "/v2/returns/1/activities"
}
},
"events": {
"links": {
"self": "/v2/returns/1/relationships/events",
"related": "/v2/returns/1/events"
}
},
"comments": {
"links": {
"self": "/v2/returns/1/relationships/comments",
"related": "/v2/returns/1/comments"
}
},
"order": {
"links": {
"self": "/v2/returns/1/relationships/order",
"related": "/v2/returns/1/order"
}
},
"portal": {
"links": {
"self": "/v2/returns/1/relationships/portal",
"related": "/v2/returns/1/portal"
}
},
"shipping_method": {
"links": {
"self": "/v2/returns/1/relationships/shipping_method",
"related": "/v2/returns/1/shipping_method"
}
},
"shipment": {
"links": {
"self": "/v2/returns/1/relationships/shipment",
"related": "/v2/returns/1/shipment"
}
}
},
"meta": {
"copyright": "© 2024 Webshipper ApS"
}
}
}
id
id
Service Quotes are used to find suitable services by quoting the carriers directly.
The id of the carrier to quote
Service code of the carrier. This is optional. When omitted, all supported services will be returned.
ISO 8601 formatted
Array of objects, each containing key weight
. At least one package is required.
Delivery address for the quote
Sender address for the quote
service_name
service_code
is_return
supports_paperless
requires_drop_point
cost_price
currency
vat_percent
estimated_delivery_date_from
estimated_delivery_date_to
add_ons
add_on_name
add_on_code
parameters
attr_name
attr_key
attr_type
country_combinations
barcode_requirement
waybill_requirement
booking_quote_info
supported_colli_types
Carrier add-ons for the quote
Service attributes for the carrier
Determines if you are quoting for return (inbound) services or standard (outbound) services.
Determines if the goods for the quote are dutiable
Used if you want only a price from a specific cost sheet
Timeout for request in seconds. Will default to 15 seconds
id
Query available services by carrier ID. Assuming a Carrier exists with id 1.
{
"data": {
"type": "service_quotes",
"attributes": {
"carrier_id": 1,
"is_return": false,
"send_time": "2024-03-01T11:12:48+01:00",
"delivery_address": {
"address_1": "Søndergade 2B",
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK"
},
"sender_address": {
"address_1": "Lyngbygade 8",
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK"
},
"packages": [
{
"weight": 500,
"weight_unit": "g",
"dimensions": {
"width": 15,
"length": 15,
"height": 15,
"unit": "cm"
}
}
]
}
}
}
When a shipment is created, a booking is made with the carrier.
Once shipments have been created only packages can be modified. Existing packages can be updated and packages can be added or removed.
Creating a shipment with only a single relationship to an order will populate the shipment with attributes from the order.
This will result in a single package containing all of the order lines of the order. Creating multiple shipments from the same order will create shipments with empty packages with the default weight of 1000g.
Carrier, carrier service, service attributes and add-ons can either be assigned manually by filling in the respective relations and attributes or by using shipping rates.
Shipping rates are pre-configurations of these relations and attribute, and thus you are able to omit all of these relations and attributes by using shipping rates.
All addresses, customs details etc. can be omitted by assigning an order relation to the shipment, and hence all of this information will be fetched directly from the order. Once the shipment has been sent, the order status will be automatically updated.
Updating a shipment
Only the below fields are updateable. Shipment updates are intended for making smaller changes to a shipment before shipping time, i.e. adding or removing a package or pallet, changing number of exchange pallets, etc.
If you need to make larger changes to a shipment you should instead delete the shipment and create a new one. Please note that deleting the shipment in Webshipper might not cancel the shipment with the carrier and as such might still incur charges from the carrier.
The reference you want to identify the shipment form. For example order number.
An optional comment for the carrier
The carrier's service code. This should only be assigned if you are not using a shipping rate.
Determines whether the shipment is a return shipment.
Flattened array of packages to be sent. At least one package is mandatory. For structure refer to 'Package' entity
Flattened Shipping Address representing the delivery address for the shipment.
Duplicated from order if order relation given..
Flattened Shipping Address representing the sender address of shipment.
Duplicated from order if order relation given..
Flattened Shipping Address representing the billing address of shipment. Duplicated from delivery address if empty.
Duplicated from order if order relation given..
Flattened Shipping Address representing the pickup address of shipment. Is necessary for some carriers. This is duplicated from sender address if empty.
Duplicated from order if order relation given..
Flattened Shipping Address represnting return addres of shipment. Will be duplicated from sender address if empty ( Not used by all carriers ).
Duplicated from order if order relation given..
Array of hashes to assign parameters for any specific carrier service. It is only required if you are not using shipping rates and the service has additional required parameters. The hash must have the keys attr_key and attr_value. The type of attr_value should match the attr_type defined by the parameter. To see all possible attributes, please see the list of parameters from the carrier service.
Array of add-ons. Add-ons are simply arrays of strings. To see possible add-ons, please refer to the carrier services. Should only be assigned if you are not using a shipping rate.
Must be passed if the carrier should be allowed to send SMS notifications. It should be assigned with a hash including the key phone containing the phone number to be notified. Should only be assigned if you are not using a shipping rate.
Must be passed if the carrier should be allowed to send e-mail notifications. It should be assigned with a hash including the key email containing the e-mail address to be notified. Should only be assigned if you are not using a shipping rate.
Flattened array of Document - can be used to upload documents to the shipment which will be sent to the carrier.
Flattened Drop Point - should only be assigned if you are sending to a drop point.
An array of objects with the keys:
url
: The full URL to the tracking page.number
: The tracking identifier.latest_transit_event
: The latest tracking/transit event. Same options as Tracking Event statuses.tracking_events
: Array of objects. Object has same attributes as the Tracking Event resourceDeprecated
The external (carrier) reference
Flattened hash with optional key/value pairs.
The cost price of the shipment, either directly from the carrier or from a cost sheet
The price presented to the customer in checkout
An optional link to the original shipment, when creating a return-shipment
id
, reference
, sorting_id
, created_at
, updated_at
, order
, carrier
, send_time
, status
, is_return
, printer_client
, delivery_country_code
, order_channel
, shipping_rate
, delivery_address
, without_shadow_shipments
, tracking_number
, free_text
, has_pickup
, activity_type
, order_lines
, billing_contact
, billing_email
, billing_company
, delivery_email
, delivery_contact
, delivery_company
Get shipment example
{
"data": {
"id": "432",
"type": "shipments",
"links": {
"self": "/v2/shipments/432"
},
"attributes": {
"reference": null,
"comment": null,
"service_code": null,
"is_return": null,
"packages": [
{
"id": 5634,
"weight": 1000.0,
"shipment_id": 432,
"created_at": null,
"updated_at": null,
"weight_unit": "g",
"barcode_usage_id": null,
"barcode_usage_type": null,
"ext_ref": "ref123",
"labelless_code": null,
"colli_type": null,
"dangerous_goods_details": {
},
"add_ons": [
],
"customs_lines": [
{
"id": null,
"package_id": 5634,
"sku": "SKU1",
"description": "Black pants",
"quantity": 1,
"tarif_number": "234343332",
"country_of_origin": "DE",
"unit_price": 15.0,
"vat_percent": 15.0,
"currency": "EUR",
"created_at": null,
"updated_at": null,
"weight": 1000.0,
"weight_unit": "g",
"discount": 0,
"ext_ref": "ref123",
"dangerous_goods_details": {
}
}
],
"dimensions": {
"id": null,
"package_id": 5634,
"height": 15.0,
"width": 15.0,
"length": 15.0,
"created_at": null,
"updated_at": null,
"unit": "cm",
"load_meters": 0.009375,
"volume": 3375.0
},
"order_lines": [
{
"id": null,
"sku": "SKU1",
"description": "Black pants",
"quantity": 1,
"location": null,
"tarif_number": "234343332",
"country_of_origin": "DE",
"unit_price": 15.0,
"vat_percent": 15.0,
"order_id": null,
"status": null,
"ext_ref": null,
"created_at": null,
"updated_at": null,
"package_id": 5634,
"weight": 1000.0,
"weight_unit": "g",
"discount_value": 0.0,
"discount_type": "fixed",
"is_virtual": false,
"dangerous_goods_details": {
},
"discounted_unit_price": 15.0,
"additional_attributes": {
}
}
],
"service_attributes": [
]
}
],
"delivery_address": {
"id": null,
"att_contact": null,
"company_name": "Webshipper ApS",
"address_1": "lyngbygade 8",
"address_2": null,
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"state": null,
"phone": null,
"email": "support@webshipper.com",
"created_at": null,
"updated_at": null,
"address_type": "recipient",
"vat_no": null,
"ext_location": null,
"company_customs_numbers": {
},
"formatted_recipient": "Webshipper ApS",
"voec": null,
"eori": null,
"sprn": null,
"personal_customs_no": null
},
"sender_address": {
"id": null,
"att_contact": null,
"company_name": "Webshipper ApS",
"address_1": "lyngbygade 8",
"address_2": null,
"zip": "8600",
"city": "Silkeborg",
"country_code": "DK",
"state": null,
"phone": null,
"email": "support@webshipper.com",
"created_at": null,
"updated_at": null,
"address_type": "recipient",
"vat_no": null,
"ext_location": null,
"company_customs_numbers": {
},
"formatted_recipient": "Webshipper ApS",
"voec": null,
"eori": null,
"sprn": null,
"personal_customs_no": null
},
"billing_address": null,
"pickup_address": null,
"return_address": null,
"service_attributes": [
{
"id": null,
"shipment_id": null,
"attr_key": "invoice_type",
"attr_value": "proforma",
"created_at": null,
"updated_at": null,
"service_attributable_id": 432,
"service_attributable_type": "Shipment",
"attr_type": "string"
},
{
"id": null,
"shipment_id": null,
"attr_key": "cod_amount",
"attr_value": "532.2",
"created_at": null,
"updated_at": null,
"service_attributable_id": 432,
"service_attributable_type": "Shipment",
"attr_type": "string"
}
],
"add_ons": [
"COD"
],
"sms_notification": null,
"email_notification": null,
"drop_point": null,
"tracking_links": [
{
"id": 743,
"url": "https://tracking.example.com?number=1234567",
"number": "1234567",
"latest_transit_event": "information_received",
"delivered": false,
"package_id": 5634,
"tracking_events": [
{
"status": "information_received",
"description": "We have been notified about the package but have not yet picked it up yet",
"time": null,
"event_id": null,
"location": null,
"latitude": null,
"longitude": null
}
]
}
],
"fulfill_immediately": true,
"test_mode": null,
"dutiable": null,
"created_at": null,
"ext_ref": null,
"original_shipment_id": null,
"send_time": null,
"status": "booked",
"latest_update_time": null,
"supports_updates": false,
"additional_attributes": {
},
"cost_price": null,
"sales_price": null,
"currency": null,
"manual_order_shipment_creation": false,
"carrier_type_name": "PostNord",
"carrier_alias": "PostNord domestic",
"carrier_id": null,
"invoice_settings": null,
"latest_activity": null,
"latest_status_event": null,
"shadow_booking_as_parent": null,
"source": "api",
"document_template": null,
"csv_upload_id": null,
"omit_print": false
},
"relationships": {
"carrier": {
"links": {
"self": "/v2/shipments/432/relationships/carrier",
"related": "/v2/shipments/432/carrier"
}
},
"order": {
"links": {
"self": "/v2/shipments/432/relationships/order",
"related": "/v2/shipments/432/order"
}
},
"shipping_rate": {
"links": {
"self": "/v2/shipments/432/relationships/shipping_rate",
"related": "/v2/shipments/432/shipping_rate"
}
},
"printer_client": {
"links": {
"self": "/v2/shipments/432/relationships/printer_client",
"related": "/v2/shipments/432/printer_client"
}
},
"original_shipment": {
"links": {
"self": "/v2/shipments/432/relationships/original_shipment",
"related": "/v2/shipments/432/original_shipment"
}
},
"pickup": {
"links": {
"self": "/v2/shipments/432/relationships/pickup",
"related": "/v2/shipments/432/pickup"
}
},
"shadow_shipment": {
"links": {
"self": "/v2/shipments/432/relationships/shadow_shipment",
"related": "/v2/shipments/432/shadow_shipment"
}
},
"return": {
"links": {
"self": "/v2/shipments/432/relationships/return",
"related": "/v2/shipments/432/return"
}
},
"document_template": {
"links": {
"self": "/v2/shipments/432/relationships/document_template",
"related": "/v2/shipments/432/document_template"
},
"data": null
},
"mail_template": {
"links": {
"self": "/v2/shipments/432/relationships/mail_template",
"related": "/v2/shipments/432/mail_template"
},
"data": null
},
"return_label_mail_template": {
"links": {
"self": "/v2/shipments/432/relationships/return_label_mail_template",
"related": "/v2/shipments/432/return_label_mail_template"
},
"data": null
},
"labels": {
"links": {
"self": "/v2/shipments/432/relationships/labels",
"related": "/v2/shipments/432/labels"
}
},
"documents": {
"links": {
"self": "/v2/shipments/432/relationships/documents",
"related": "/v2/shipments/432/documents"
}
},
"attachments": {
"links": {
"self": "/v2/shipments/432/relationships/attachments",
"related": "/v2/shipments/432/attachments"
}
},
"edis": {
"links": {
"self": "/v2/shipments/432/relationships/edis",
"related": "/v2/shipments/432/edis"
}
},
"additional_attributes": {
"links": {
"self": "/v2/shipments/432/relationships/additional_attributes",
"related": "/v2/shipments/432/additional_attributes"
}
},
"events": {
"links": {
"self": "/v2/shipments/432/relationships/events",
"related": "/v2/shipments/432/events"
}
},
"return_shipments": {
"links": {
"self": "/v2/shipments/432/relationships/return_shipments",
"related": "/v2/shipments/432/return_shipments"
}
},
"activities": {
"links": {
"self": "/v2/shipments/432/relationships/activities",
"related": "/v2/shipments/432/activities"
}
},
"status_events": {
"links": {
"self": "/v2/shipments/432/relationships/status_events",
"related": "/v2/shipments/432/status_events"
}
},
"stores": {
"links": {
"self": "/v2/shipments/432/relationships/stores",
"related": "/v2/shipments/432/stores"
}
}
},
"meta": {
"copyright": "© 2024 Webshipper ApS"
}
}
}
Create shipment for an order, with overridden printer client - shipping rate fetched from the order
{
"data": {
"type": "shipments",
"relationships": {
"order": {
"data": {
"type": "orders",
"id": 2341
}
},
"printer_client": {
"data": {
"type": "printer_clients",
"id": 12
}
}
}
}
}
Partially send an order
{
"data": {
"type": "shipments",
"attributes": {
"packages": [
{
"ext_ref": "ref123",
"weight": 100,
"weight_unit": "g",
"dimensions": {
"unit": "cm",
"height": 15,
"width": 15,
"length": 15
},
"order_lines": [
{
"id": 2
},
{
"id": 3
}
]
}
]
},
"relationships": {
"order": {
"data": {
"type": "orders",
"id": 2341
}
}
}
}
}
Create a shipment with documents by attachemnt (attaching document with id 1) and direct upload
{
"data": {
"type": "shipments",
"attributes": {
"included_documents": [
{
"document_id": 1
},
{
"base64": "....",
"document_format": "PDF",
"document_size": "A4",
"document_type": "invoice"
}
]
},
"relationships": {
"order": {
"data": {
"type": "orders",
"id": 123
}
}
}
}
}
Create a shipment with service attributes and addons, the addon name, attribute key, type and potential dependencies are gotten from the addons and parameters fields in a service quote.
{
"data": {
"type": "shipments",
"attributes": {
"service_attributes": [
{
"attr_key": "invoice_type",
"attr_value": "proforma"
},
{
"attr_key": "cod_amount",
"attr_value": 512.5
}
],
"add_ons": [
"COD"
]
},
"relationships": {
"order": {
"data": {
"type": "orders",
"id": 123
}
}
}
}
}
Create shipment with a shipping rate
{
"data": {
"type": "shipments",
"attributes": {
"sender_address": {
"company_name": "Webshipper ApS",
"att_contact": "Thomas",
"address_1": "Lyngbygade 8",
"zip": "8600",
"city": "Silkeborg"
},
"delivery_address": {
"company_name": "Test company",
"att_contact": "Peter hansen",
"address_1": "Silkeborgvej 291",
"zip": "8230",
"city": "Åbyhøj",
"country_code": "DK"
},
"packages": [
{
"ext_ref": "ref123",
"weight": 100,
"weight_unit": "g",
"dimensions": {
"unit": "cm",
"height": 15,
"width": 15,
"length": 15
}
}
]
},
"relationships": {
"shipping_rate": {
"data": {
"type": "shipping_rates",
"id": 234
}
}
}
}
}
Update shipment with new package and service attributes (Use shipment id as path parameter in endpoint, i.e. /shipments/id)
{
"data": {
"id": "id",
"type": "shipments",
"attributes": {
"packages": [
{
"id": "existing_package_id",
"ext_ref": "ref123",
"weight": 500,
"weight_unit": "g",
"dimensions": {
"unit": "cm",
"height": 20,
"width": 30,
"length": 10
},
"service_attributes": [
{
"attr_key": "colli_description",
"attr_value": "This package exists before the update and should still exist"
}
]
},
{
"ext_ref": "ref123",
"weight": 100,
"weight_unit": "g",
"dimensions": {
"unit": "cm",
"height": 15,
"width": 15,
"length": 15
},
"service_attributes": [
{
"attr_key": "colli_description",
"attr_value": "This package is added as a new package as it has no id attribute"
}
]
}
],
"service_attributes": [
{
"attr_key": "prebooking_status",
"attr_value": "Prebook"
}
]
}
}
}
Att person. To generate parcels either att_contact or company_name is required
Company name. To generate parcels either att_contact or company_name is required
Address line 1
Address line 2
ISO 3166-1 alpha-2 code
Sub-division of country, if applicable. State code. ISO 3166-2 alpha-2
Phone number of the entity. This can be used for SMS notifications.
E-mail address of the entity. This can be used for e-mail notifications.
Postal code of the entity. This is required for most destination countries.
City of the entity. This is required for most destination countries.
The VAT number of the entity. This is only required for address_type sold_from
Used for special addresses for order channels. This will be one of the following: recipient
, sender
, sold_from
, pickup
, return
, order_address
id
, att_contact
, company_name
, address_1
, address_2
, country_code
, state
, zip
, address_type
, search
A shipping mapping maps unknown shipping methods to one of the order channel's known shipping rates after an order is created. In the Webshipper user interface, this feature is known as linking shipping rates.
Shipping code is a unique identifier from the order channel that will be mapped to a shipping rate
Shipping name is a human readable identifier of the shipping method
Shipping rate id is the id of the shipping rate which you want to map to.
Order channel id of the order channel
id
, order_channel_id
, order_channel
, shipping_code
In most e-commerce systems, a shipping rate is displayed as a selectable option.
Shipping rates have many regions, and each of these regions has one or more expressions. Expressions are strings that are evaluated to see if the shipping rate matches the input, please see section 1.2 Common use Cases, Quoting an Order Channel for Shipping Rates.
Name to be displayed in the e-commerce system.
The carrier's service code which must be used when generating parcels with this shipping rate.
Determines if the shipping rate requires a drop point to be assigned.
Enum - determines whether the rate is returned for all customers, private_customers or business customers. This must be one of the following values: any
, privat_customers
, business_customers
Array of flattened resources of type Service Attribute
. Depends on the carrier service's requirements. Service Attribute has the following attributes: attr_key
, attr_value
. You may use the Webshipper Template Language (WTL) for the values.
Predefined dimensions which are a assigned when using the shipping rate. Attributes are: height
,width
and length
. The Webshipper Template Language (WTL) may be used for the values.
Array of add_ons supported by the carrier service.
Defines whether the rate is a return (inbound) rate or a standard rate (outbound). Please be aware that this attribute must match the carrier's service type.
When this is set to true, the shipping rate will enable e-mail notifications from the carrier.
Defines what content is included in the comment field. The Webshipper Template Language (WTL) may be used in this field. For example: {{order.external_comment}}
Defines what content is included in the reference field. The Webshipper Template Language (WTL) may be used in this field. For example: {{order.visible_ref}}
When this is set to true, the shipping rate will enable SMS notifications from the carrier.
Defines whether the goods sent using this shipping rate are dutiable.
Attribute to indicate if the shipping rate is visible to order channels
Predefined colli type to be used when using the shipping rate. Must be supported by the carrier.
Custom message to be displayed for the shipping rate
Flattended array of Regions. See section on Shipping Regions and Expressions for more details
id
, order_channel_id
, is_return
, is_hidden
, service_code
, shadow_bookings
Shipping rate expressions wraps expressions from the Webshipper Expression Language (WEL) with price details. When the WEL evaluates to true, the shipping rate will be returned in a rate quote. Please see section 8 for details regarding expressions.
Is the actual WEL expression to be evaluated
VAT rate in percentage which must be added to the price.
Currency of the price
The cost price displayed to the end user
id
Shipping regions handle multiple countries as a group, e.g. the European Union.
Name
Flattened array of expressions. Please see section 8 for more details regarding expressions.
id
Templates for generating parcel slips. The Webshipper Template Language (WTL) may be used when creating templates.
Name to identify the template.
Size of the parcel slip. Possible values: A4
and 4X6
Content after the table of order lines for A4-based parcel slips.
Alignment of additional_content. Possible values: center
, right
, left
Content of the barcode
Content of the slip header
Header of the top left corner
Header of the top right corner
Content of the top left corner
Content of the top right corner
Content of the footer
Array of columns. Column objects contains: name
content
, text_alignment
(right, left, center), width
(in percentage)
HEX color including #
HEX color including #
The key to sort the order-lines by
which order_channels use slip_template. If not used by any, it will return empty list
id
, returns_only
id
Used for click n collect if activated on the shipping rate.
id
Read only resources describing all tags used. The index action returns a unique list of all tags currently
id
One of information_received, in_transit, out_for_delivery, customs_clearance_delayed, attempted_delivery, ready_for_pickup, delivered_to_drop_point, delivered, returned, undeliverable or unknown
Time the event occured at the carrier
Readable description of the event
The tracking number for this event, if availiable
Unique event of the id
ID of shipment
The tracking link for this event, if availiable
id
, created_at
, shipment_id
Trigger for automations. When evaluated to true, the automation will start.
WEL expression for the trigger
Model for the trigger. E.g. Order
created
or updated
id
The user's first name.
The user's last name.
The user's e-mail address.
The user's password. This can only be used for changing the password.
The time of the most recent sign-in by the user.
Specifies whether the user has access to all order channels on the tenant.
Specifies whether the user has access to all of the carriers for tenant.
Specifies whether the user should be hidden in the user interface.
This must be set when changing the password of the user.
Locale enum. da
or en
Locked until specified datetime
Amount of failed login attempts since last login
Read only. Will be true when the user is temporarily locked due to too many login attempts
The home page set by the user
id
Name of the user group
Array of scopes. Please see section 6 for more details regarding scopes.
id
Name of the waybill type
Code identifying the type of waybill
Unique reference returned from the carrier implementation when a waybill is opened.
This will be assigned by the API if the waybill type has a barcode requirement.
Indicates whether the waybill is open or closed. When you want to close the waybill, you simply need to update the status of the way bill and set it to closed.
This is a read-only attribute which returns the total number of shipments.
Array of documents. This is available when the waybill is closed.
id
, status
, carrier
Webhooks allow you to receive events from the Webshipper platform when resources are created, updated and changed. Endpoints must reply with a status code 200 for successful requests within the timeout of 7 seconds. Any validation error on you side must not result in the error response. Other statuses (including redirects) are treated as errors.
Webhook payloads are formatted as JSONAPI resources similar to other resources in the API. Webhook payloads for tracking events have the related shipment and order sideloaded under 'included'. Webhook payloads for shipments have the related order sideloaded under 'included'.
Webhooks are retried 21 times over a period of 8 days. An e-mail message will be sent to your account's technical contact if a webhook has been failing for 4 hours. After all retries have been exhaused, the webhook is disabled entirely and a new one must be created. The account's technical contact will also be notified by e-mail when a webhook is disabled in this scenario.
All webhooks are sent using the X-Webshipper-Hmac-SHA256 header, which contains the Base64 encoding of the HMAC of the JSON request body signed with your customer secret using SHA256. Webhooks also include the X-Webshipper-Topic header used to indicate the webhook topic.
Example in Ruby:
Base64.strict_encode64(OpenSSL::HMAC.digest('sha256', secret, data))
Example in .NET
var request_body = "RAW REQUEST BODY GOES HERE: IT IS UTF8 ENCODED ✅";
var hmac = new HMACSHA256( Encoding.UTF8.GetBytes("secret123"));
var digest = System.Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(request_body)));
Console.WriteLine(digest);
Note that for 'deleted' webhooks, not all attributes can be expected to be present
The HTTP endpoint to be called. Webhooks always use POST as the request method.
Which event should trigger the webhooks. Supported topics:
This is a boolean attribute that specifies whether the webhook is active.
The secret used to sign the HMAC.
The most recent error message.
null
otherwise.
id
A log entry with details of a failed webhook request the last 7 days.
id