- Download OpenAPI specification
- 1 Introduction
- 2 Authorisation
- 3 Relationships
- 4 Flattened Relations
- 5 Sorting and Filtering
- 6 Scopes
- 7 Carrier Implementation
- 8 Webshipper Expression Language
- 9 Webshipper Template Language
- Primary Resources
- All Resources
- Action
- Activity
- Activity Types
- Additional Attribute
- Attachment
- Automation
- Automations Dry Run
- Barcode Range
- Bulk import orders
- CSV Mapping
- CSV Mapping Rule
- CSV Upload
- Carrier
- Carrier Access
- Carrier Type
- Customs Line
- Document
- Document Templates
- Drop Point
- Drop Point Locator
- EDI
- End-of-day report
- Error Type
- Event
- EventModel
- Favourite Page
- Has Documents
- HotKey
- Label
- Local Attribute
- Local Attribute Enums
- Mail Template Preview
- Mail Templates
- Merged Order
- Merged PDF
- Model
- OAuth Access Token
- OAuth Application
- Order
- Order Channel
- Order Channel Access
- Order Channel Type
- Order Line
- Package
- Pickup
- Print Bulk Slips
- Printable
- Printer
- Printer Client
- Printer Job
- Quote Object
- Rate Quote
- Report
- Report Type
- Requeueable Printer Jobs
- Return Causes
- Return Lines
- Return Order
- Return Portal
- Return Shipping Method
- Service Quote
- Shipment
- Shipping Address
- Shipping Mapping
- Shipping Rate
- Shipping Rate Expression
- Shipping Region
- Slip Template
- Slip Template Preview
- Store
- Tag
- Tracking Event
- Trigger
- User
- User Group
- Waybill
- Webhook
- Webhook Failure
1 Introduction
1.1 Conventions
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:
- Resources are identified with the attribute
id, which is a server-side generated sequential integer - Resource types are pluralised and underscored, like
order_lines - The API has a fixed page limit of 30 records. To fetch more records use the query parameter
page[number] - All resources have the attributes
created_atandupdated_atwhich are ISO 8601 timestamps like2018-03-07T14:01:18.000Z - All country codes are ISO 3166-1 alpha-2 codes
It is also possible to download the documentation in the OpenAPI 3.0 here
1.2 Common Use Cases
Creating an Order with 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,
"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"
}
}
}
}
}
Quoting for Services
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"
}
}
}
Quoting an Order Channel for Shipping Rates
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"
}
}
}
Creating Shipments without an Order
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"}
}
}
}
}
Creating a Shipment from an Order
Assumes an order exists with id 1
{
"data": {
"type": "shipments",
"attributes": {
},
"relationships": {
"order": {
"data": {"id": 1, "type": "orders"}
}
}
}
}
Creating a Shipment from a Shipping Rate
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"}
}
}
}
}
Searching Drop Points
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"
}
}
}
1.3 Rate limiting
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.
2 Authorisation
The API uses OAuth2 for authorization. The following grant_types are supported by the API:
- Resource Owner Password Credentials. Obtain an access token with a username and password. Tokens issued with this grant type will always have same scopes as the user's group
- Authorization Code Grant. Authorise an application to access the user's account data using a web based form.
- Implicit Grant. Used in cases where the client cannot be trusted
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
}3 Relationships
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.
4 Flattened Relations
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"
}
]
}
}
}
5 Sorting and Filtering
As the JSON API is agnostic about filtering strategies the following conventions are used:
- Simple filtering with strict equality ('=') can by done with the
filter[name]=Webshipper - Advanced filtering can be done by providing a list of objects to
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 likefilter[city][value]=Aarhus%25&filter[city][operator]=LIKEto 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.
Advanced filtering
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
6 Scopes
read_orderswrite_ordersread_shipmentswrite_shipmentsread_rateswrite_ratesread_order_channelswrite_order_channelsread_carrieswrite_carriersread_templateswrite_templatesread_carrier_typesread_order_channel_typesread_user_groupsread_slip_templateswrite_slip_templatesread_mail_templateswrite_mail_templatesread_userswrite_usersread_order_channel_aclswrite_order_channel_aclswrite_carrier_aclsread_carrier_aclsread_printerswrite_printersread_barcode_rangeswrite_barcode_rangesread_access_tokenswrite_access_tokensread_reportswrite_reportsread_waybillswrite_waybillsread_shipping_addresseswrite_shipping_addresses
7 Carrier Implementation
7.1 Introduction
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.
Required endpoints
The following endpoints are required
- Service list endpoint
- Service quote endpoint
- Booking endpoint
The following endpoints are optional
- Waybill endpoint
- Drop point endpoint
- Pickup endpoint
- EOD endpoint
- Tracking endpoint
Accepting Customer Credentials
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"
},
[...]
}
Validating Requests
To validate that requests originate from Webshipper, each request include the headerX-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);
Error responses
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, Add Ons and Service Attributes
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"] ] |
Testing the integration
To test your implementation:
- Send your endpoints and expected credentials to Webshipper, we will then create a Carrier Type for you in our staging environment (api.staging.webshipper.io). You will also be provided with a testing account for the staging environment.
- Use your testing account at <you>.staging.webshipper.io to create a carrier by navigating to Settings > Carriers > Create Carrier and select your carrier type.
- Finally, create a new shipment. When you fill in the delivery address and select your newly created carrier, a service quote is made to your carrier. You should then be able to select a service. Clicking Create Shipment will call the booking endpoint. If that succeeds, you will be redirected and be able to see the label for the shipment that you have just created.
7.2 Service list endpoint
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
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:
- barcode_requirement for a service as seen in the example. This will return a barcode for each package in a shipment.
- shipment_barcode_requirement for a service, located in the same place as the barcode_requirement in the example above. This will assign unique barcode_serial which will be the same for all the packages in a shipment. Typically called a shipment number or a waybill head.
- waybill_requirement > barcode_requirement Defines that the waybill required, will need a barcode serial. The serial will be assigned when the waybill is closed and sent along with the waybill close request.
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 mandatorySupported colli types
The 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
- eur: EUR pallet (80x120)
- eur_half: EUR half pallet (80x60)
- eur_quarter: EUR quarter pallet (60x40)
- uk: UK pallet (120x100)
- package: Package
- letter: Letter
7.3 Service quote endpoint
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"
}
}
]
}
]
}
7.4 Booking endpoint
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:
- 100X100
- 100X150
- 100X192
- A4
Valid label sizes are:
- 100X100
- 100X150
- 100X192
The carrier code returned must correspond to any currently registered carrier in Webshipper.
Sending and receiving documents
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:
- document_data, a base64 encoded PDF
- document_type, one of
customs_document,invoice,certificateorother.
- document_data, a base64 encoded PDF
- document_format, currently only 'PDF' is supported
- document_size, one of the valid document sizes mentioned above.
- document_type, one of
customs_document,invoice,certificateorother. Default toother - is_paperless, true or false (default), can be used for debugging/inspecting any paperless document generated by the carrier implementation.
label_format.
ZPL labels will only requested if the booking endpoint supports it. ZPL data should not be base64 encoded. Labels must only be returned in one of these formats, but PDF is supported as a fallback method if a ZPL label cannot be generated.
{
"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......="
}
]
}
7.5 Drop point endpoint
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"
}
]
}
]
}
7.6 Waybill endpoint
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......="
}
]
}
7.7 Pickup endpoint
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"
}
7.8 EOD Endpoint
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.
7.9 Tracking Endpoint
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:
-
statusOne of the tracking event statuses defined on the Tracking Event resource. -
timeAn ISO 8601 timestamp for the time the event occured. -
detailsHuman friendly description of the tracking event. -
locationDescription of where the event occured. No specific format is required. Optional. -
event_idUnique 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"
}
]
}
]
}
7.10 Validation Endpoint
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
}
7.11 Prebooking Endpoint
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
}
8 Webshipper Expression Language
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){
"weight": 1100,
"delivery_address": {
"zip": "10200",
"country_code": "NO"
},
"sender_address": {
"zip": "8000",
"country_code": "DK"
},
"packages": [
{
"weight": 500
},
{
"weight": 600
}
]
}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'
|
9 Webshipper Template Language
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 %}| 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 }} |
Attributes
Filters
Routes
Attributes
Relationships
portalreturn_portals . return_line
return_lines .
Filters
id
Routes
Action
Actions as part of automations
Attributes
Name of a supported job:
- CreateShipmentJob
If true, this action runs as a background process, if not it runs immediately
Array of objects containing keys attr_values and attr_value
Relationships
automationautomations .
Filters
id
Routes
Activity
Resource for activity.
Attributes
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
Relationships
activity_typeactivity_types . status_event_type
activity_types . model
Polymorphic.
Filters
id
Routes
Activity Types
Read only resource for activity types.
Attributes
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
Filters
id, active, model
Routes
Additional Attribute
This resource is used to attach info to orders and order lines
Attributes
Visible name of the attribute
Key for the attribute
Value of the attribute
Relationships
orderorders . order_line
order_lines .
Filters
id
Routes
Attachment
Attachment are used to associate existing Documents with Orders and Shipments.
Attributes
Relationships
documentdocuments . has_documents
Polymorphic.
Filters
id
Routes
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
}
}
}
}
}Automation
With Automations you can build custom workflows on the Webshipper platform using highly flexible Triggers and Actions.
Attributes
Flattened resource of type Trigger
Array of flattened resources of type Action
Relationships
activity_typeactivity_types .
Filters
id
Routes
Automations Dry Run
Attributes
Filters
id
Routes
Barcode Range
This resource is used to describe the barcode ranges provided to you by a carrier.
Attributes
String like DPD or SSCC
The first barcode in the range
The last barcode in the range
Relationships
carriercarriers .
Filters
id
Routes
Bulk import orders
Bulk import orders based on an array of ids
Attributes
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
Filters
id
Routes
CSV Mapping
Describes how to parse an uploaded CSV file
Attributes
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
Relationships
carriercarriers . order_channel
order_channels .
Filters
id
Routes
CSV Mapping Rule
Describes how an entry in a CSV file should map to an attribute in a resource.
Attributes
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
Relationships
mappingcsv_mappings .
Filters
id
Routes
CSV Upload
Used to import records from CSV files (or similar formats). CSV Mapping Rules provides the details for how to import the records.
Attributes
The raw CSV data
If set to true, the import will be performed in background. Highly recommended for imports larger than 100 rows.
Relationships
mappingcsv_mappings .
Filters
id
Routes
Carrier
Attributes
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
Relationships
carrier_typecarrier_types . sender_address
shipping_addresses . return_address
shipping_addresses . shipping_rates
shipping_rates . cost_sheets
cost_sheets .
Filters
id, billable, carrier_type_codes, carrier_group_id
Routes
Carrier Access
Grants access to the carrier's shipments for a single user. This has no effect if the user has access to all carriers.
Attributes
Relationships
carriercarriers . user
users .
Filters
id
Routes
Carrier Type
Read-only endpoint to fetch information of the available carrier types.
Attributes
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.
Relationships
local_attrslocal_attrs . carriers
carriers .
Filters
id, carrier_code, carrier_group_id
Routes
Customs Line
Customs Lines is generally created as part of a shipment creation and should it should never be necessary to call this resource directly.
Attributes
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.
Filters
id
Routes
Document
Additional shipment documents. This is used for customs declarations etc. Documents are limited to 5mb.
Attributes
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
Relationships
has_documentsPolymorphic. print_jobs
printer_jobs .
Filters
id, is_special
Routes
Document Templates
Read only resource for document templates.
Attributes
Number of copies
Type of document
Overrides for the document
Defaults for the document
Notify
Email address
Email body
Email filename
Filters
id, document_type
Routes
Drop Point
Drop point for orders. To locate drop points, please refer to 'Drop Point Locator'
Attributes
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
Filters
id
Routes
No routes available for this resource. It can only be accesses as a flattened resource in other resourcesDrop Point Locator
Used to find the geographically closest drop points.
Attributes
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.
Filters
id
Routes
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"
}
}
}
}EDI
This resource describes an EDI file. This file will be uploaded to an FTP server configured by the carrier.
Attributes
Must be one of 'pending', 'on_hold' or 'sent'
The file contents (as text)
Must be either 'utf8' or 'ascii'
Relationships
shipmentshipments .
Filters
id, shipment_id, waybill_id
Routes
End-of-day report
A report of all shipment for the day of start_time.
Attributes
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
Relationships
carriercarriers . print_jobs
printer_jobs .
Filters
id
Routes
Error Type
Attributes
Filters
id
Routes
Event
Timeline event for orders or shipments
Attributes
FontAwesome 4 compatible icon like: exclamation, trash, truck, envelope, cog, anchor, map-marker, certificate
Will be set by the Webshipper API
Relationships
modelPolymorphic.
Filters
id
Routes
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
}
}
}
}
}EventModel
Attributes
Filters
id
Routes
Favourite Page
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
Attributes
Path of the favourite page
Name of the favourite page
Relationships
userusers . hot_key
hot_keys .
Filters
id, user_id
Routes
Has Documents
Attributes
Filters
id
Routes
HotKey
Hot key lets you define a key combination for quickly accessing your favourite pages
Attributes
Key combination of the hotkey
Path the hotkey is assigned to
Relationships
favourite_pagefavourite_pages . user
users .
Filters
id
Routes
Label
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
Attributes
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)
Relationships
print_jobsprinter_jobs .
Filters
id
Routes
{
"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"
}
}
}Local Attribute
As opposed to Global Attributes, Local Attributes are used for creating Attributes for Order Channels and Carriers.
Attributes
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
Relationships
order_channel_typeorder_channel_types . local_attr_enums
local_attr_enums . local_attr_translations
local_attr_translations .
Filters
id
Routes
{
"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"
}
}
}Local Attribute Enums
A set of predefined values allowed for a Local Attribute.
Attributes
Visible name for the enum
Value for the enum
Relationships
local_attrlocal_attrs .
Filters
id
Routes
{
"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"
}
}
}Mail Template Preview
Attributes
Filters
id
Routes
Mail Templates
Attributes
Relationships
brandbrands .
Filters
id, purpose
Routes
Merged Order
Attributes
ID of order to merge order lines in to
Orders from which to merge order lines from. Orders as nested resources
Filters
id
Routes
Merged PDF
Attributes
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
Filters
id
Routes
Model
Attributes
Filters
id
Routes
OAuth Access Token
This resource describes all of the access tokens for the appllication.
Attributes
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
Relationships
applicationoauth_applications .
Filters
id
Routes
{
"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"
}
}
}OAuth Application
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.
Attributes
Application name
Unique id
The scopes which the OAuth application will be granted.
OAuth redirect URI
Relationships
access_tokensoauth_access_tokens .
Filters
id, uid, active
Routes
{
"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"
}
}
}Order
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.
Attributes
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
Relationships
* order_channelorder_channels . shipping_rate
shipping_rates . error_type
error_types . printer_client
printer_clients . shipments
shipments . additional_attributes
additional_attributes . Has many relationship to AdditionalAttribute. To add AdditionalAttribute to orders, they must be created in a separate POST request and then assigned as a relationship to the order. print_jobs
printer_jobs . packages
packages . events
events . attachments
attachments . documents
documents . activities
activities . status_events
activities . returns
returns . comments
comments . stores
stores .
Filters
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
Routes
{
"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"
}
}
}
}
}Order Channel
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).
Attributes
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
Relationships
order_channel_typeorder_channel_types . slip_template
slip_templates . sender_address
shipping_addresses . return_address
shipping_addresses . pickup_address
shipping_addresses . sold_from_address
shipping_addresses . default_printer_client
printer_clients . orders
orders . shipping_rates
shipping_rates . shipping_mappings
shipping_mappings . order_channel_sync_entries
order_channel_sync_entries . additional_attributes
additional_attributes .
Filters
id, attr
Routes
{
"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"
}
}
}Order Channel Access
Grants a user access to an order channel. This has no effect if the user has been granted access to all order channels.
Attributes
Relationships
order_channelorder_channels . user
users .
Filters
id
Routes
Order Channel Type
Order Channel Types are used to create Order Channels
Attributes
Relationships
local_attrslocal_attrs .
Filters
id, by_name
Routes
Order Line
Attributes
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.
Relationships
packagepackages . * order
orders . additional_attributes
additional_attributes .
Filters
id
Routes
Package
Attributes
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.
Relationships
shipmentshipments . order_lines
order_lines .
Filters
id
Routes
Pickup
Pickups facilitates the booking of a pickup from a given carrier. Not all carriers supports pickup.
Attributes
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.
Relationships
carriercarriers . shipping_address
shipping_addresses . shipments
shipments .
Filters
id
Routes
Print Bulk Slips
Bulk add slips to the printer queue
Attributes
Filters
id
Routes
Printable
Attributes
Filters
id
Routes
Printer
Printers are loaded automatically when connecting to your account from the Webshipper Silent Printer application.
Attributes
Name of the printer.
Determines if the printer is configured on the printer station
Last connection time
Paper width
Paper height
Relationships
clientprinter_clients .
Filters
id
Routes
Printer Client
Printer clients are created automatically when connecting Webshipper Silent Printer and should not be created manually.
Attributes
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
Relationships
label_printerprinters . zpl_printer
printers . document_printer
printers . location
shipping_addresses . printers
printers . order_channels
order_channels .
Filters
id
Routes
Printer Job
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.
Attributes
This will return as true when the printer client has accepted the job.
Any error message that resulted.
Relationships
printer_clientprinter_clients . printer
printers . printable
Polymorphic.
Filters
id, printer_client_id, created_at, completed, error, try_count, printer_id
Routes
Quote Object
Attributes
Filters
id
Routes
Rate Quote
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.
Attributes
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.
Filters
id
Routes
{
"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"
}
]
}
}
}Report
Reports are generated by using Report Types which specify how a report should look and which records to include in the report.
Attributes
Relationships
report_typereport_types . carrier
carriers . print_jobs
printer_jobs .
Filters
id
Routes
Report Type
This resource acts a template for creating resource.
Attributes
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.
Filters
id
Routes
Requeueable Printer Jobs
Find and requeue failed printer jobs within the given timeframe
Attributes
Filters
id
Routes
Return Causes
Description of the cause
Attributes
Does the cause require a comment
Does the cause limit refund methods
Does the cause support image required
Relationships
portalreturn_portals . refund_methods
return_refund_methods .
Filters
id
Routes
Return Lines
Read only resource for return lines.
Attributes
Description of the cause
Quantity of the return line
Refund method for the return line
Relationships
returnreturns . cause
return_causes . order_line
order_lines . refund_method
return_refund_methods .
Filters
id
Routes
Return Order
Attributes
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
Relationships
orderorders . portal
return_portals . shipping_method
return_shipping_methods . shipment
shipments . activities
activities . events
events . comments
comments .
Filters
id, secret, activity_type, status, portal_id, free_text, return_causes
Routes
{
"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"
}
}
}Return Portal
Attributes
Relationships
order_channelorder_channels . slip_template
slip_templates . mail_template
mail_templates . confirmation_mail_template
mail_templates . return_address
shipping_addresses . returns
returns . causes
return_causes . refund_methods
return_refund_methods .
Filters
id
Routes
Return Shipping Method
Attributes
Relationships
portalreturn_portals . shipping_rate
shipping_rates .
Filters
id
Routes
Service Quote
Service Quotes are used to find suitable services by quoting the carriers directly.
Attributes
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_nameservice_codeis_returnsupports_paperlessrequires_drop_pointcost_pricecurrencyvat_percentestimated_delivery_date_fromestimated_delivery_date_to-
add_onsArray containing objectsadd_on_nameadd_on_code
parametersattr_nameattr_keyattr_typecountry_combinationsbarcode_requirementwaybill_requirementbooking_quote_infosupported_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
Filters
id
Routes
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"
}
}
]
}
}
}Shipment
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.
- fulfill_immediately
- packages
- service_attributes
- add_ons
- included_documents
- status
- comment
Attributes
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 resource
Deprecated
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
Relationships
carriercarriers . order
orders . shipping_rate
shipping_rates . printer_client
printer_clients . original_shipment
shipments . pickup
pickups . shadow_shipment
shipments . return
returns . document_template
document_templates . mail_template
mail_templates . return_label_mail_template
mail_templates . labels
labels . documents
documents . attachments
attachments . edis
edis . additional_attributes
additional_attributes . events
events . return_shipments
shipments . activities
activities . status_events
activities . stores
stores .
Filters
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
Routes
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"
}
]
}
}
}Shipping Address
Attributes
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
Filters
id, att_contact, company_name, address_1, address_2, country_code, state, zip, address_type, search
Routes
Shipping Mapping
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.
Attributes
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
Relationships
shipping_rateshipping_rates . order_channel
order_channels .
Filters
id, order_channel_id, order_channel, shipping_code
Routes
Shipping Rate
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.
Attributes
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
Relationships
* carriercarriers . The carrier which must be used * order_channel
order_channels . The order channel which the shipping rate belongs to. return_shipping_rate
shipping_rates . sender_address
shipping_addresses . return_address
shipping_addresses . mail_template
mail_templates . return_mail_template
mail_templates . document_template
document_templates . shadow_booking_shipping_rate
shipping_rates . regions
regions . stores
stores .
Filters
id, order_channel_id, is_return, is_hidden, service_code, shadow_bookings
Routes
Shipping Rate Expression
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.
Attributes
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
Filters
id
Routes
Shipping Region
Shipping regions handle multiple countries as a group, e.g. the European Union.
Attributes
Name
Flattened array of expressions. Please see section 8 for more details regarding expressions.
Relationships
shipping_rateshipping_rates .
Filters
id
Routes
Slip Template
Templates for generating parcel slips. The Webshipper Template Language (WTL) may be used when creating templates.
Attributes
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: namecontent, 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
Relationships
order_channelsorder_channels .
Filters
id, returns_only
Routes
Slip Template Preview
Attributes
Filters
id
Routes
Store
Used for click n collect if activated on the shipping rate.
Attributes
Relationships
sender_addressshipping_addresses . return_address
shipping_addresses . pickup_address
shipping_addresses . sold_from_address
shipping_addresses . shipping_rates
shipping_rates .
Filters
id
Routes
Tag
Read only resources describing all tags used. The index action returns a unique list of all tags currently
Attributes
Filters
id
Routes
Tracking Event
Attributes
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
Relationships
packagepackages . The package for this event, if availiable shipment
shipments . The shipment for this event.
Filters
id, created_at, shipment_id
Routes
Trigger
Trigger for automations. When evaluated to true, the automation will start.
Attributes
WEL expression for the trigger
Model for the trigger. E.g. Order
created or updated
Relationships
automationautomations .
Filters
id
Routes
User
Attributes
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
Relationships
user_groupuser_groups . printer_client
printer_clients . The printer client (workstation) which the user is currently assigned to. order_channel_accesses
order_channel_accesses . carrier_accesses
carrier_accesses . store_assignments
store_assignments . stores
stores . favourite_pages
favourite_pages . consents
user_consents .
Filters
id
Routes
User Group
Attributes
Name of the user group
Array of scopes. Please see section 6 for more details regarding scopes.
Relationships
usersusers .
Filters
id
Routes
Waybill
Attributes
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.
Relationships
carriercarriers . sold_to_address
shipping_addresses . sender_address
shipping_addresses . document_template
document_templates . printer_client
printer_clients . shipments
shipments . documents
documents .
Filters
id, status, carrier
Routes
Webhook
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))
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
Attributes
The HTTP endpoint to be called. Webhooks always use POST as the request method.
Which event should trigger the webhooks. Supported topics:
- order/created triggered when an order is created.
- order/updated triggered when an order is updated.
- order/deleted triggered when an order was deleted.
- shipment/created triggered when a shipment is created.
- shipment/updated triggered when a shipment is updated.
- shipment/deleted triggered when a shipment was deleted.
- return/created triggered when a return is created.
- return/updated triggered when a return is updated.
- return/deleted triggered when a return was deleted.
- report/created triggered when a report is created.
- report/updated triggered when a report is updated.
- report/deleted triggered when a report was deleted.
- trackingevent/created triggered when a tracking event is created.
- trackingevent/updated triggered when a tracking event is updated.
- trackingevent/deleted triggered when a tracking event was deleted.
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.
Relationships
ownerPolymorphic. The User or the Application that created the webhook failures
webhook_failures . jobs
webhook_jobs .
Filters
id
Routes
Webhook Failure
A log entry with details of a failed webhook request the last 7 days.
Attributes
Relationships
webhookwebhooks . The Webhook this failures belongs to.
Filters
id