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_at and updated_at which are ISO 8601 timestamps like 2018-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

Webshipper strongly recommends using a client library for utilising this API. Refer to jsonapi.org's list of jsonapi.org's list of client libraries to find one for your language.

1.2 Common Use Cases

Creating an Order with Drop Point

Example of an Order
POST
https://<account name>.api.webshipper.io/v2/orders

{
  "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.

Example a Service Quote

Assuming a Carrier exists with id 1.

POST
https://<account name>.api.webshipper.io/v2/service_quotes

{
  "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.

Quoting Shipping Rates

Request:

POST
https://<account name>.api.webshipper.io/v2/rate_quotes

 {
  "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.

Example of creating a new Shipment without an Order

Assuming a Carrier exists with id 1 and that it provides a service called MYPACK_HOME

POST
https://<account name>.api.webshipper.io/v2/shipments

{
  "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

Example of creating a Shipment from an Order

Assumes an order exists with id 1

POST
https://<account name>.api.webshipper.io/v2/shipments

{
  "data": {
    "type": "shipments",
    "attributes": {
    },
    "relationships": {
      "order": {
        "data": {"id": 1, "type": "orders"}
      }
    }
  }
}

Creating a Shipment from a Shipping Rate

Example of creating a Shipment from an Order

Assumes a Shipping Rate exists with id 1 and requires a drop point

POST
https://<account name>.api.webshipper.io/v2/shipments

{
  "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.

Example of searching drop points

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

If you want to get started as fast as possible - you can create an access token from the UI under "Settings" > "Access and tokens".

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.

Requesting a token using username and password
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:

Making Authorised Requests
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.

Using Refresh tokens
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.

In most use cases, the id attribute can be ignored.
Example of updating OrderLines of an Order

One order line is updated and one is added, this is useful for preserving relations to e.g. packages.

PATCH
https://<account name>.api.webshipper.io/v2/orders/12

{
  "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 like filter[city][value]=Aarhus%25&filter[city][operator]=LIKE to find addresses where the city begins with 'Aarhus'

Return all pending orders:
{tenant}.api.webshipper.io/v2/orders?filter[status]=pending

Some resources do not follow this convention or have additional filter for things like customised search or filtering by associated resources.

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_orders
  • write_orders
  • read_shipments
  • write_shipments
  • read_rates
  • write_rates
  • read_order_channels
  • write_order_channels
  • read_carries
  • write_carriers
  • read_templates
  • write_templates
  • read_carrier_types
  • read_order_channel_types
  • read_user_groups
  • read_slip_templates
  • write_slip_templates
  • read_mail_templates
  • write_mail_templates
  • read_users
  • write_users
  • read_order_channel_acls
  • write_order_channel_acls
  • write_carrier_acls
  • read_carrier_acls
  • read_printers
  • write_printers
  • read_barcode_ranges
  • write_barcode_ranges
  • read_access_tokens
  • write_access_tokens
  • read_reports
  • write_reports
  • read_waybills
  • write_waybills
  • read_shipping_addresses
  • write_shipping_addresses

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.

Example of 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 header X-WEBSHIPPER-HMAC-SHA256. As the name suggests, it contains a HMAC SHA256 generated with the POST message body and the shared secret. The shared secret is provided when you enter the carrier agreement with Webshipper.
Example of validating the HMAC header

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.

Example error response, 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:

Example of returning a parameter and an add on with service list/service quote
{
    "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:

The resulting booking request
{
    [...],
    "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.


Request to endpoint (with sample carrier_attributes)
POST <your service list endpoint>
        
{
  "carrier_code": "YOURCARRIER",
  "carrier_attributes":  {
    "username": "TEST USER",
    "api_token": "TEST TOKEN"
  }
}
        
      
Expected response from the carrier implementation
{
  "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 mandatory
Supported 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.


Requests to the carrier implementation
POST <your service quote endpoint>

  {
    "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, certificate or other.
Fields for documents in response:
  • 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, certificate or other. Default to other
  • is_paperless, true or false (default), can be used for debugging/inspecting any paperless document generated by the carrier implementation.

All PDF files must be base64 encoded. Documents must be PDFs. Labels must be in PDF or ZPL, as defined in 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.
Sample request
POST <your booking endpoint>

{
  "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


Request to the carrier implementation
POST <your drop point endpoint>

{
  "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.


Request to the carrier implementation
POST <your waybill endpoint>
  
    {
      "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.


Request to the carrier implementation
POST <your pickup endpoint>
      
        {
          "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.


Request to the carrier implementation
POST <your eod endpoint>
      
        {
          "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:

  • status One of the tracking event statuses defined on the Tracking Event resource.
  • time An ISO 8601 timestamp for the time the event occured.
  • details Human friendly description of the tracking event.
  • location Description of where the event occured. No specific format is required. Optional.
  • event_id Unique identifier for the tracking event. An event_id should be unique across all tracking numbers, and consistent for each call to this endpoint for each tracking number.

It is not necessary to return all tracking events for each request, as events are saved by Webshipper. Changes to previously sent tracking events are ignored.


Request to the carrier implementation
POST <your tracking endpoint>
      
        {
          "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).


Request to the carrier implementation
POST <your validation endpoint>
       
         {
           "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.


Sample request
POST <your prebooking endpoint>
      
      {
        "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.

Example of WEL expressions

If this expression

(delivery_address.country_code = 'NO' and weight in 1000-2000 and not (sender_address.zip in 1000-5000) and price > 200 ) or (packages.count >= 2)
Is given the following input:
{
  "weight": 1100,
  "delivery_address": {
    "zip": "10200",
    "country_code": "NO"
  },
  "sender_address": {
    "zip": "8000",
    "country_code": "DK"
  },
  "packages": [
    {
      "weight": 500
    },
    {
      "weight": 600
    }
  ]
}
It will evaluate to true.

Webshipper Expression Language Syntax
Expressions have the following syntax, where 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

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

Conditions allow you to render content conditionally, this may be done through if-conditions as follows:

{% if order.order_channel_id == 1 or order.visible_ref contains 'SHOP1' %}
 This is order channel 1
{% else %}
 This is not order channel 1
{% endif %}
The following operators are supported for conditions:
Operator Function
== equals
!= not equals
> greater than
< less than
<= less than or equal
>= greater than or equal
or Condition A or condition B
and Condition A and condition B

Iteration

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

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 }}
 

https://<account name>.api.webshipper.io/v2/brands

Attributes
documents

Read only


Filters

Routes
GET
https://<account name>.api.webshipper.io/v2/brands/{id}
GET
https://<account name>.api.webshipper.io/v2/brands
PATCH
https://<account name>.api.webshipper.io/v2/brands/{id}
POST
https://<account name>.api.webshipper.io/v2/brands
DELETE
https://<account name>.api.webshipper.io/v2/brands/{id}

https://<account name>.api.webshipper.io/v2/return_refund_methods

Attributes
name string


description text


allowed_days integer


payment_required boolean


excluded_skus string


Relationships
portal
has_one

return_portals . return_line
has_one

return_lines .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/return_refund_methods/{id}
GET
https://<account name>.api.webshipper.io/v2/return_refund_methods
PATCH
https://<account name>.api.webshipper.io/v2/return_refund_methods/{id}
POST
https://<account name>.api.webshipper.io/v2/return_refund_methods
DELETE
https://<account name>.api.webshipper.io/v2/return_refund_methods/{id}

Action

https://<account name>.api.webshipper.io/v2/actions

Actions as part of automations

Attributes
job_type string

Name of a supported job:

  • CreateShipmentJob


async boolean

If true, this action runs as a background process, if not it runs immediately


additional_attributes array

Array of objects containing keys attr_values and attr_value


priority integer


Relationships
automation
has_one

automations .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/actions/{id}
GET
https://<account name>.api.webshipper.io/v2/actions
PATCH
https://<account name>.api.webshipper.io/v2/actions/{id}
POST
https://<account name>.api.webshipper.io/v2/actions
DELETE
https://<account name>.api.webshipper.io/v2/actions/{id}

Activity

https://<account name>.api.webshipper.io/v2/activities

Resource for activity.

Attributes
details text

Details of the activity


latitude float

Latitude of the activity


longitude float

Longitude of the activity


signature

Base64 encoded signature of the activity


signature_name string

Name of the signature


photo

Base64 encoded photo of the activity


initiator string

Initiator of the activity


created_at datetime

Read only
The time when the resource was created


Relationships
activity_type
has_one

activity_types . status_event_type
has_one

activity_types . model
has_one

Polymorphic.
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/activities/{id}
GET
https://<account name>.api.webshipper.io/v2/activities
PATCH
https://<account name>.api.webshipper.io/v2/activities/{id}
POST
https://<account name>.api.webshipper.io/v2/activities
DELETE
https://<account name>.api.webshipper.io/v2/activities/{id}

Activity Types

https://<account name>.api.webshipper.io/v2/activity_types

Read only resource for activity types.

Attributes
activity_description string

Description of the activity


activity_key string

Key for the activity


model string

Model for the activity


model_status string

Status of the model


requires_signature boolean

Does the activity require a signature


requires_photo boolean

Does the activity require a photo


active boolean

Is the activity active


priority integer

Priority of the activity


Filters

id, active, model

Routes
GET
https://<account name>.api.webshipper.io/v2/activity_types/{id}
GET
https://<account name>.api.webshipper.io/v2/activity_types
PATCH
https://<account name>.api.webshipper.io/v2/activity_types/{id}
POST
https://<account name>.api.webshipper.io/v2/activity_types
DELETE
https://<account name>.api.webshipper.io/v2/activity_types/{id}

Additional Attribute

https://<account name>.api.webshipper.io/v2/additional_attributes

This resource is used to attach info to orders and order lines

Attributes
name string

Visible name of the attribute


attr_key string

Key for the attribute


attr_value text

Value of the attribute


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


created_at datetime

Read only
The time when the resource was created


Relationships
order
has_one

orders . order_line
has_one

order_lines .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/additional_attributes/{id}
GET
https://<account name>.api.webshipper.io/v2/additional_attributes
PATCH
https://<account name>.api.webshipper.io/v2/additional_attributes/{id}
POST
https://<account name>.api.webshipper.io/v2/additional_attributes
DELETE
https://<account name>.api.webshipper.io/v2/additional_attributes/{id}

Attachment

https://<account name>.api.webshipper.io/v2/attachments

Attachment are used to associate existing Documents with Orders and Shipments.

Attributes
updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


created_at datetime

Read only
The time when the resource was created


Relationships
document
has_one

documents . has_documents
has_one

Polymorphic.
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/attachments/{id}
GET
https://<account name>.api.webshipper.io/v2/attachments
PATCH
https://<account name>.api.webshipper.io/v2/attachments/{id}
POST
https://<account name>.api.webshipper.io/v2/attachments
DELETE
https://<account name>.api.webshipper.io/v2/attachments/{id}
POST https://<account name>.api.webshipper.io/v2/ attachments

Attaching to an Order

{
  "data": {
    "type": "attachments",
    "relationships": {
      "document": {
        "data": {
          "type": "documents",
          "id": 532
        }
      },
      "has_documents": {
        "data": {
          "type": "orders",
          "id": 532
        }
      }
    }
  }
}
POST https://<account name>.api.webshipper.io/v2/ attachments

Attaching to a Shipment

{
  "data": {
    "type": "shipments",
    "attributes": {
      "included_documents": [
        {
          "document_id": 1
        }
      ]
    },
    "relationships": {
      "order": {
        "data": {
          "type": "orders",
          "id": 123
        }
      }
    }
  }
}

Automation

https://<account name>.api.webshipper.io/v2/automations

With Automations you can build custom workflows on the Webshipper platform using highly flexible Triggers and Actions.

Attributes
trigger object

Flattened resource of type Trigger


actions array

Array of flattened resources of type Action


name string


enabled boolean


priority integer


automation_type integer


Relationships
activity_type
has_one

activity_types .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/automations/{id}
GET
https://<account name>.api.webshipper.io/v2/automations
PATCH
https://<account name>.api.webshipper.io/v2/automations/{id}
POST
https://<account name>.api.webshipper.io/v2/automations
DELETE
https://<account name>.api.webshipper.io/v2/automations/{id}

Automations Dry Run

https://<account name>.api.webshipper.io/v2/automations_dry_runs

Attributes
dry_run


automation


shipment_id


order_id


report_id


model_type


element_name


Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/automations_dry_runs/{id}
GET
https://<account name>.api.webshipper.io/v2/automations_dry_runs
PATCH
https://<account name>.api.webshipper.io/v2/automations_dry_runs/{id}
POST
https://<account name>.api.webshipper.io/v2/automations_dry_runs
DELETE
https://<account name>.api.webshipper.io/v2/automations_dry_runs/{id}

Barcode Range

https://<account name>.api.webshipper.io/v2/barcode_ranges

This resource is used to describe the barcode ranges provided to you by a carrier.

Attributes
barcode_type string

String like DPD or SSCC


serial_from integer

The first barcode in the range


serial_to integer

The last barcode in the range


current_serial integer

Read only
The last used (highest) barcode serial


usage_status integer


replaces_id


Relationships
carrier
has_one

carriers .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/barcode_ranges/{id}
GET
https://<account name>.api.webshipper.io/v2/barcode_ranges
PATCH
https://<account name>.api.webshipper.io/v2/barcode_ranges/{id}
POST
https://<account name>.api.webshipper.io/v2/barcode_ranges
DELETE
https://<account name>.api.webshipper.io/v2/barcode_ranges/{id}

Bulk import orders

https://<account name>.api.webshipper.io/v2/bulk_import_orders

Bulk import orders based on an array of ids

Attributes
ids

Order ids to import from the order channel


order_channel_id

Id of the order channel to import orders from


async

Run the import asyncronously, default is false unless importing more than one order or from more than one order channel


reimport

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_start

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_end

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

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


bulk_imports

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

Source of the orders to import. This will default to API


Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/bulk_import_orders/{id}
GET
https://<account name>.api.webshipper.io/v2/bulk_import_orders
PATCH
https://<account name>.api.webshipper.io/v2/bulk_import_orders/{id}
POST
https://<account name>.api.webshipper.io/v2/bulk_import_orders
DELETE
https://<account name>.api.webshipper.io/v2/bulk_import_orders/{id}

CSV Mapping

https://<account name>.api.webshipper.io/v2/csv_mappings

Describes how to parse an uploaded CSV file

Attributes
separator required string

The seperator in the file. Normally ';' or ','


target_class required string

Must be one of the models Order or Shipment


grouped_by required integer

Must be the index of the Order ID


grouped_path required string

The sub-model which you are grouping. For order: order_lines_attributes


includes_header boolean

Determines if there is an ignorable header line in the file


lines_as_package boolean


recreate_order_lines boolean


separate_order_line_mapping boolean


name required string

Name of the configuration


example_input text

Example input to make it easier to create the mapping in the UI.


line_example_input text


rules array

Array of flattened resources of the type CSV Rule


shipment_export_format text


order_export_format text


create_shipment_automatically boolean


force_async boolean


concat_paths boolean


split_large_records boolean


export_file_extension string


Relationships
carrier
has_one

carriers . order_channel
has_one

order_channels .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/csv_mappings/{id}
GET
https://<account name>.api.webshipper.io/v2/csv_mappings
PATCH
https://<account name>.api.webshipper.io/v2/csv_mappings/{id}
POST
https://<account name>.api.webshipper.io/v2/csv_mappings
DELETE
https://<account name>.api.webshipper.io/v2/csv_mappings/{id}

CSV Mapping Rule

https://<account name>.api.webshipper.io/v2/csv_rules

Describes how an entry in a CSV file should map to an attribute in a resource.

Attributes
target_path required string

Path of the attribute to update


source_index required integer

The index of the field in the CSV file to be mapped


default_value string

Value to use if the value in the CSV file is empty or missing


input_conversions object

A key/value mapping for converting values before creating the object


Relationships
mapping
has_one

csv_mappings .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/csv_rules/{id}
GET
https://<account name>.api.webshipper.io/v2/csv_rules
PATCH
https://<account name>.api.webshipper.io/v2/csv_rules/{id}
POST
https://<account name>.api.webshipper.io/v2/csv_rules
DELETE
https://<account name>.api.webshipper.io/v2/csv_rules/{id}

CSV Upload

https://<account name>.api.webshipper.io/v2/csv_uploads

Used to import records from CSV files (or similar formats). CSV Mapping Rules provides the details for how to import the records.

Attributes
imported array

Read only
A list of ids of the imported records


input required string

The raw CSV data


input_url


import_errors array

Read only
A list of error messages for items that could not be imported


async boolean

If set to true, the import will be performed in background. Highly recommended for imports larger than 100 rows.


make_exportable boolean


created_at datetime

Read only
The time when the resource was created


Relationships
mapping
has_one

csv_mappings .
Filters

id

Routes
POST
https://<account name>.api.webshipper.io/v2/csv_uploads

Carrier

https://<account name>.api.webshipper.io/v2/carriers

Attributes
alias required string

Your name for the carrier


services

Array of services provided by this Carrier


attrs

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


prefer_zpl boolean


created_at datetime

Read only
The time when the resource was created


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


is_approved boolean


approved_service_codes text


service_parameter_enums


barcode_notification_behavior integer


barcode_notification_mail string


has_active_cost_sheet


delete_at_carrier boolean


test_mode boolean


logo


logo_url


print_error_label boolean


ftp_configuration_id integer


Relationships
carrier_type
has_one

carrier_types . sender_address
has_one

shipping_addresses . return_address
has_one

shipping_addresses . shipping_rates
has_many

shipping_rates . cost_sheets
has_many

cost_sheets .
Filters

id, billable, carrier_type_codes, carrier_group_id

Routes
GET
https://<account name>.api.webshipper.io/v2/carriers/{id}
GET
https://<account name>.api.webshipper.io/v2/carriers
PATCH
https://<account name>.api.webshipper.io/v2/carriers/{id}
POST
https://<account name>.api.webshipper.io/v2/carriers
DELETE
https://<account name>.api.webshipper.io/v2/carriers/{id}

Carrier Access

https://<account name>.api.webshipper.io/v2/carrier_accesses

Grants access to the carrier's shipments for a single user. This has no effect if the user has access to all carriers.

Attributes
created_at datetime

Read only
The time when the resource was created


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


Relationships
carrier
has_one

carriers . user
has_one

users .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/carrier_accesses/{id}
GET
https://<account name>.api.webshipper.io/v2/carrier_accesses
POST
https://<account name>.api.webshipper.io/v2/carrier_accesses
DELETE
https://<account name>.api.webshipper.io/v2/carrier_accesses/{id}

Carrier Type

https://<account name>.api.webshipper.io/v2/carrier_types

Read-only endpoint to fetch information of the available carrier types.

Attributes
fulfillment_logo

Logo for the carrier


list_logo

Logo for the carrier


name string

Name of the carrier


carrier_code string

Code identifying the carrier


description text

Description of the carrier


required_details text

Details required to use the carrier


requires_dutiable boolean


supports_zpl boolean


supports_pickup


supports_tracking


supports_price_quoting boolean


requires_approval boolean


supports_documents boolean


supports_shipment_updates boolean

Boolean indicating wether the carrier supports shipment updates


shipment_updates_limit_minutes integer

Number of minutes before shipment time a shipment can be updated


barcode_mail string


supports_price_pdf_upload


supports_deletion


barcode_customer_notification_mail_template_id integer


colli_type_support integer

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.


beta boolean


supports_test_mode boolean


show_send_time boolean


supports_shadow_bookings boolean


rate_quote_validation boolean


carrier_group_id string


require_ftp_configuration_id boolean


hide boolean


Relationships
local_attrs
has_many

local_attrs . carriers
has_many

carriers .
Filters

id, carrier_code, carrier_group_id

Routes
GET
https://<account name>.api.webshipper.io/v2/carrier_types/{id}
GET
https://<account name>.api.webshipper.io/v2/carrier_types

Customs Line

https://<account name>.api.webshipper.io/v2/customs_lines

Customs Lines is generally created as part of a shipment creation and should it should never be necessary to call this resource directly.

Attributes
sku string

Stock Keeping Unit


description text

Goods description


quantity required integer

Quantity of the customs line


tarif_number string

Tariff number / HS code


country_of_origin string

Country of origin of the customs line - ISO 3166-1 alpha-2


unit_price float

Unit price of a single quantity customs line


vat_percent float

Vat percent of the customs line


currency string

Currency ISO-4217


weight float

Weight of a single quantity customs line


weight_unit integer

Weight unit of the customs line - One of 'g', 'oz', 'lbs' or 'kg'


discount float

Discount of a single quantity customs line


dangerous_goods_details object

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
GET
https://<account name>.api.webshipper.io/v2/customs_lines/{id}
GET
https://<account name>.api.webshipper.io/v2/customs_lines
PATCH
https://<account name>.api.webshipper.io/v2/customs_lines/{id}
POST
https://<account name>.api.webshipper.io/v2/customs_lines
DELETE
https://<account name>.api.webshipper.io/v2/customs_lines/{id}

Document

https://<account name>.api.webshipper.io/v2/documents

Additional shipment documents. This is used for customs declarations etc. Documents are limited to 5mb.

Attributes
shipment_id integer

Id of the shipment it belongs to


document_size required string

Enum for the paper size. valid values: A4


document_format required string

Enum for the document format. Valid values: PDF


base64 required

Base64 representation of the document. Only required when creating.


is_special boolean

Used to indicate if this document is a special document, like static customs documents. Special documents will be displayed in Webshipper under Settings > Documents.


name string

Used for special documents


description text

Used for special documents


document_type integer

One of: 'shipping_document', 'other', 'customs_document', 'invoice', 'certificate', 'proforma', 'nafta_certificate', 'commercial', 'awb'. Documents returned from the carrier are always shipping_document.


is_paperless boolean

Used to indicate if a shipment is paperless


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


created_at datetime

Read only
The time when the resource was created


Relationships
has_documents
has_one

Polymorphic. print_jobs
has_many

printer_jobs .
Filters

id, is_special

Routes
GET
https://<account name>.api.webshipper.io/v2/documents/{id}
GET
https://<account name>.api.webshipper.io/v2/documents
PATCH
https://<account name>.api.webshipper.io/v2/documents/{id}
POST
https://<account name>.api.webshipper.io/v2/documents
DELETE
https://<account name>.api.webshipper.io/v2/documents/{id}

Document Templates

https://<account name>.api.webshipper.io/v2/document_templates

Read only resource for document templates.

Attributes
name string


copies integer

Number of copies


document_type integer

Type of document


overrides text

Overrides for the document


defaults

Defaults for the document


notify boolean

Notify


email_address string

Email address


email_body text

Email body


email_filename string

Email filename


Filters

id, document_type

Routes
GET
https://<account name>.api.webshipper.io/v2/document_templates/{id}
GET
https://<account name>.api.webshipper.io/v2/document_templates
PATCH
https://<account name>.api.webshipper.io/v2/document_templates/{id}
POST
https://<account name>.api.webshipper.io/v2/document_templates
DELETE
https://<account name>.api.webshipper.io/v2/document_templates/{id}

Drop Point

Drop point for orders. To locate drop points, please refer to 'Drop Point Locator'

Attributes
drop_point_id required string

The carriers ID of the drop point.


name required string

Name of the drop point


address_1 required string

Address line 1 of the drop point


address_2 string

Address line 2 of the drop point


zip required string

Zip code for the drop point


city required string

City for the drop point


country_code required string

Country Code for the drop point. ISO 3166-1 Alfa 2


state string

State code. ISO 3166-2 Alfa 2


phone string

Phone of the drop point


carrier_code string

Text base code to identify the carrier of the drop point ( not mandatory )


routing_code string

Routing code for the drop point.


longitude string

Longitude


latitude string

Latitude


created_at datetime

Read only
The time when the resource was created


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


opening_hours

Read only
Opening hours for the drop point. Days are 0-indexed, starting with Monday as 0


Filters

id

Routes
No routes available for this resource. It can only be accesses as a flattened resource in other resources

Drop Point Locator

https://<account name>.api.webshipper.io/v2/drop_point_locators

Used to find the geographically closest drop points.

Attributes
carrier_id required integer

ID of the carrier that you want to quote. This is only mandatory if no shipping_rate_id is given.


service_code required string

Service code for the service that you want to quote. This is only mandatory if no shipping_rate_id is given.


shipping_rate_id required

ID of the shipping rate that you want to quote. This is only mandatory if no carrier_id is given..


drop_point_id


delivery_address required

Flattened shipping address object. zip and country_code are required and address_1 is optional.


drop_points array

Array of drop points near delivery_address. This will be populated in the response.


drop_point_service_code


Filters

id

Routes
POST
https://<account name>.api.webshipper.io/v2/drop_point_locators
POST https://<account name>.api.webshipper.io/v2/ drop_point_locators

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"
      }
    }
  }
}
POST https://<account name>.api.webshipper.io/v2/ drop_point_locators

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

https://<account name>.api.webshipper.io/v2/edis

This resource describes an EDI file. This file will be uploaded to an FTP server configured by the carrier.

Attributes
status integer

Must be one of 'pending', 'on_hold' or 'sent'


data text

The file contents (as text)


encoding integer

Must be either 'utf8' or 'ascii'


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


created_at datetime

Read only
The time when the resource was created


carrier_code

Read only
Text-based code representing the carrier type.


Relationships
shipment
has_one

shipments .
Filters

id, shipment_id, waybill_id

Routes
GET
https://<account name>.api.webshipper.io/v2/edis
GET
https://<account name>.api.webshipper.io/v2/edis/{id}

End-of-day report

https://<account name>.api.webshipper.io/v2/end_of_day_reports

A report of all shipment for the day of start_time.

Attributes
base64

Base64 encoding of the PDF document. This must explicitly be included with fields[end_of_day_reports]='base64'


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


created_at datetime

Read only
The time when the resource was created


start_time datetime

Datetime representing the start time for the report


end_time datetime

Datetime representing the end time for the report


Relationships
carrier
has_one

carriers . print_jobs
has_many

printer_jobs .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/end_of_day_reports/{id}
GET
https://<account name>.api.webshipper.io/v2/end_of_day_reports
PATCH
https://<account name>.api.webshipper.io/v2/end_of_day_reports/{id}
POST
https://<account name>.api.webshipper.io/v2/end_of_day_reports
DELETE
https://<account name>.api.webshipper.io/v2/end_of_day_reports/{id}

Error Type

https://<account name>.api.webshipper.io/v2/error_types

Attributes
translations


matcher string


error_class string


support_url string


created_at datetime

Read only
The time when the resource was created


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/error_types/{id}
GET
https://<account name>.api.webshipper.io/v2/error_types
PATCH
https://<account name>.api.webshipper.io/v2/error_types/{id}
POST
https://<account name>.api.webshipper.io/v2/error_types
DELETE
https://<account name>.api.webshipper.io/v2/error_types/{id}

Event

https://<account name>.api.webshipper.io/v2/events

Timeline event for orders or shipments

Attributes
title string


details text


icon string

FontAwesome 4 compatible icon like: exclamation, trash, truck, envelope, cog, anchor, map-marker, certificate


initiator string

Will be set by the Webshipper API


source string


created_at datetime

Read only
The time when the resource was created


Relationships
model
has_one

Polymorphic.
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/events/{id}
GET
https://<account name>.api.webshipper.io/v2/events
PATCH
https://<account name>.api.webshipper.io/v2/events/{id}
POST
https://<account name>.api.webshipper.io/v2/events
DELETE
https://<account name>.api.webshipper.io/v2/events/{id}
POST https://<account name>.api.webshipper.io/v2/ events

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

https://<account name>.api.webshipper.io/v2/event_models

Attributes
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/event_models/{id}
GET
https://<account name>.api.webshipper.io/v2/event_models
PATCH
https://<account name>.api.webshipper.io/v2/event_models/{id}
POST
https://<account name>.api.webshipper.io/v2/event_models
DELETE
https://<account name>.api.webshipper.io/v2/event_models/{id}

Favourite Page

https://<account name>.api.webshipper.io/v2/favourite_pages

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 required string

Path of the favourite page


name text

Name of the favourite page


user_id integer


Relationships
user
has_one

users . hot_key
has_one

hot_keys .
Filters

id, user_id

Routes
GET
https://<account name>.api.webshipper.io/v2/favourite_pages/{id}
GET
https://<account name>.api.webshipper.io/v2/favourite_pages
PATCH
https://<account name>.api.webshipper.io/v2/favourite_pages/{id}
POST
https://<account name>.api.webshipper.io/v2/favourite_pages
DELETE
https://<account name>.api.webshipper.io/v2/favourite_pages/{id}

Has Documents

https://<account name>.api.webshipper.io/v2/has_documents

Attributes
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/has_documents/{id}
GET
https://<account name>.api.webshipper.io/v2/has_documents
PATCH
https://<account name>.api.webshipper.io/v2/has_documents/{id}
POST
https://<account name>.api.webshipper.io/v2/has_documents
DELETE
https://<account name>.api.webshipper.io/v2/has_documents/{id}

HotKey

https://<account name>.api.webshipper.io/v2/hot_keys

Hot key lets you define a key combination for quickly accessing your favourite pages

Attributes
hot_key string

Key combination of the hotkey


path required string

Path the hotkey is assigned to


favourite_page_id integer


user_id integer


Relationships
favourite_page
has_one

favourite_pages . user
has_one

users .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/hot_keys/{id}
GET
https://<account name>.api.webshipper.io/v2/hot_keys
PATCH
https://<account name>.api.webshipper.io/v2/hot_keys/{id}
POST
https://<account name>.api.webshipper.io/v2/hot_keys
DELETE
https://<account name>.api.webshipper.io/v2/hot_keys/{id}

Label

https://<account name>.api.webshipper.io/v2/labels

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
shipment_id integer


label_size integer

Size of the label. Enum with possible values: '100X100', '100X150', '100X192', 'A4'.


label_format integer

Label format. Enum with possible values: 'PDF', 'ZPL'.


base64

Base64 encoding of the pdf document. (Can be an array, see the description above)


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


created_at datetime

Read only
The time when the resource was created


Relationships
print_jobs
has_many

printer_jobs .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/labels
GET
https://<account name>.api.webshipper.io/v2/labels/{id}
GET https://<account name>.api.webshipper.io/v2/ labels/1

{
  "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

https://<account name>.api.webshipper.io/v2/local_attrs

As opposed to Global Attributes, Local Attributes are used for creating Attributes for Order Channels and Carriers.

Attributes
attr_name required string

Visible name of the attribute


attr_key required string

Key for the attribute. Used by the system to read the correct information


attr_type required string

Data type. Must be either of the following: string, integer or password


is_required boolean

Determines if the form should require the attr to be filled


description string

Help text to describe the attribute


requirement_type integer


category string


priority integer


only_visible_on_creation boolean

Determines if the form should only be visible when connecting


Relationships
order_channel_type
has_one

order_channel_types . local_attr_enums
has_many

local_attr_enums . local_attr_translations
has_many

local_attr_translations .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/local_attrs/{id}
GET
https://<account name>.api.webshipper.io/v2/local_attrs
GET https://<account name>.api.webshipper.io/v2/ local_attrs/9

{
  "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

https://<account name>.api.webshipper.io/v2/local_attr_enums

A set of predefined values allowed for a Local Attribute.

Attributes
enum_name string

Visible name for the enum


enum_value string

Value for the enum


Relationships
local_attr
has_one

local_attrs .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/local_attr_enums/{id}
GET
https://<account name>.api.webshipper.io/v2/local_attr_enums
GET https://<account name>.api.webshipper.io/v2/ local_attr_enums/9

{
  "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

https://<account name>.api.webshipper.io/v2/mail_template_previews

Attributes
mail


mail_template


mail_locale


locale


shipment_id


return_id


order_id


brand_id


hook


overrides


lang


defaults


to


whitelisted_languages


Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/mail_template_previews/{id}
GET
https://<account name>.api.webshipper.io/v2/mail_template_previews
PATCH
https://<account name>.api.webshipper.io/v2/mail_template_previews/{id}
POST
https://<account name>.api.webshipper.io/v2/mail_template_previews
DELETE
https://<account name>.api.webshipper.io/v2/mail_template_previews/{id}

Mail Templates

https://<account name>.api.webshipper.io/v2/mail_templates

Attributes
name string


default_locale string


mail_locales


images


purpose integer


bcc_mail string


is_prebuilt boolean


overrides text


defaults


hook string


whitelisted_languages text


used_by_shipping_rates


described

Read only
Encapsulated with new WYSIWYG editor and legacy HTML based templates


used_by_order_channels

Read only
which order_channels use mail_template. If not used by any, it will return empty list


Relationships
brand
has_one

brands .
Filters

id, purpose

Routes
GET
https://<account name>.api.webshipper.io/v2/mail_templates/{id}
GET
https://<account name>.api.webshipper.io/v2/mail_templates
PATCH
https://<account name>.api.webshipper.io/v2/mail_templates/{id}
POST
https://<account name>.api.webshipper.io/v2/mail_templates
DELETE
https://<account name>.api.webshipper.io/v2/mail_templates/{id}

Merged Order

https://<account name>.api.webshipper.io/v2/order_merges

Attributes
order_id required boolean

ID of order to merge order lines in to


orders required array

Orders from which to merge order lines from. Orders as nested resources


Filters

id

Routes
POST
https://<account name>.api.webshipper.io/v2/order_merges

Merged PDF

https://<account name>.api.webshipper.io/v2/pdf_merges

Attributes
include_labels required boolean

Whether to include labels or not


include_docs required boolean

Whether to include docs or not'


include_slips required boolean

Whether to include slips or not


force_a4 required boolean

Whether to use A4 paper size not


shipment_ids array

A list of shipment ids to include in the merged pdf


order_ids array

A list of order ids to include in the merged pdf


url text


failed boolean


Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/pdf_merges/{id}
POST
https://<account name>.api.webshipper.io/v2/pdf_merges

Model

https://<account name>.api.webshipper.io/v2/models

Attributes
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/models/{id}
GET
https://<account name>.api.webshipper.io/v2/models
PATCH
https://<account name>.api.webshipper.io/v2/models/{id}
POST
https://<account name>.api.webshipper.io/v2/models
DELETE
https://<account name>.api.webshipper.io/v2/models/{id}

OAuth Access Token

https://<account name>.api.webshipper.io/v2/oauth_access_tokens

This resource describes all of the access tokens for the appllication.

Attributes
scopes required string

The scopes to which access is granted by the access token.


created_at datetime

Read only
The time when the resource was created


resource_owner_id required integer

Id of the owner


expires_in required integer

Epoch timestamp of the expiration date for the token


expired


token required string

The access token


revoked_at datetime

Datetime of the time the token was revoked - if revoked


resource_owner


application_id integer


application

The application to which this tokens grants access


Relationships
application
has_one

oauth_applications .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/oauth_access_tokens/{id}
GET
https://<account name>.api.webshipper.io/v2/oauth_access_tokens
GET https://<account name>.api.webshipper.io/v2/ oauth_access_tokens/1

{
  "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

https://<account name>.api.webshipper.io/v2/oauth_applications

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
name required string

Application name


uid required string

Unique id


scopes string

The scopes which the OAuth application will be granted.


redirect_uri text

OAuth redirect URI


created_at datetime

Read only
The time when the resource was created


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


Relationships
access_tokens
has_many

oauth_access_tokens .
Filters

id, uid, active

Routes
GET
https://<account name>.api.webshipper.io/v2/oauth_applications/{id}
GET
https://<account name>.api.webshipper.io/v2/oauth_applications
GET https://<account name>.api.webshipper.io/v2/ oauth_applications/1

{
  "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

https://<account name>.api.webshipper.io/v2/orders

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
order_channel_id integer

DEPRECATED Assign a relation instead


status required string

Enum status of the order. Possible values: pending, dispatched, partly_dispatched, cancelled, error, missing_rate, on_hold


ext_ref string

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_ref string

Visible reference - the friendly/visible external order number


drop_point object

Flattened resource of type DropPoint. Must be assigned when the order must be delivered to a drop point.


original_shipping object

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.


order_lines required array

Flattened resource of type OrderLine


delivery_address required object

Flattened resource of type ShippingAddress


sender_address object

Flattened resource of type ShippingAddress. If the address is not assigned - the sender address of the order channel will be used.


billing_address object

Flattened resource of type ShippingAddress. Will be duplicated from delivery address if not assigned.


sold_from_address object

Flattened resource of type ShippingAddress. Will be duplicated from sender address if not assigned.


currency required string

Currency code of the order


internal_comment string

Latest comment with type 'internal'. Changing this, will create a new comment


external_comment string

External order comment. Will typically be the order comment from e-commerce checkout.


error_message object

Any error message that resulted from the latest attempt at making a shipment from the order.


slip string

Read only
The order slip in PDF format using base64 encoding. This will only be included if the parameter fields[orders] includes slip.


base64

Read only


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


created_at datetime

Read only
The time when the resource was created


lock_state string

When an order is locked, it cannot be modified or sent until it is unlocked. Possible values: locked or unlocked.


source string

A description of how the order was created in Webshipper. Possible values: 'api', 'manual' or 'csv'


tags array

Array of strings used to tag an order


error_class string

A string like 'address' or 'carrier_downtime' describe which type of error caused the order to fail


slip_printed boolean


label_printed boolean


create_shipment_automatically


latest_activity


latest_status_event


shipping_rate_id integer


csv_upload_id integer


Relationships
* order_channel
has_one

order_channels . shipping_rate
has_one

shipping_rates . error_type
has_one

error_types . printer_client
has_one

printer_clients . shipments
has_many

shipments . additional_attributes
has_many

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
has_many

printer_jobs . packages
has_many

packages . events
has_many

events . attachments
has_many

attachments . documents
has_many

documents . activities
has_many

activities . status_events
has_many

activities . returns
has_many

returns . comments
has_many

comments . stores
has_many

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
GET
https://<account name>.api.webshipper.io/v2/orders/{id}
GET
https://<account name>.api.webshipper.io/v2/orders
PATCH
https://<account name>.api.webshipper.io/v2/orders/{id}
POST
https://<account name>.api.webshipper.io/v2/orders
DELETE
https://<account name>.api.webshipper.io/v2/orders/{id}
GET https://<account name>.api.webshipper.io/v2/ orders/12

{
  "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"
    }
  }
}
POST https://<account name>.api.webshipper.io/v2/ orders

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

https://<account name>.api.webshipper.io/v2/order_channels

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
channel_label string

Label to identify the order channel.


attrs array

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


additional_parameters object

Optional hash, this is used when creating new order channels.


slip_print_mode string

Possible values: 'dont_print', 'print_immediately' or 'print_with_shipment'.


return_label_print_mode string

Possible values: 'dont_print', 'print_immediately'.


shipping_label_print_mode string

Possible values: 'dont_print', 'print_immediately'.


document_print_mode string

Possible values: 'dont_print', 'print_immediately'.


logo

Base64 representation of the logo of the order channel.


configuration_token

Token to use for Webshipper modules. Tokens will only be generated for modules that require a configuration token.


sync_status integer

Determines if the order channel is currently synchronising. Possible values are: synchronize, suspended, paused.


failed_sync_count integer

Shows if recent synchronisation events have failed.


fulfill_automatically boolean

Whether or not to fulfill the order in the original order channel when a shipment is created. Default: true


drop_point_limit integer


create_shipment_automatically boolean


health


convert_currency_on_rate_quotes boolean


sync_additional_attributes_to_shipments boolean


auto_order_import boolean


has_configuration_token


Relationships
order_channel_type
has_one

order_channel_types . slip_template
has_one

slip_templates . sender_address
has_one

shipping_addresses . return_address
has_one

shipping_addresses . pickup_address
has_one

shipping_addresses . sold_from_address
has_one

shipping_addresses . default_printer_client
has_one

printer_clients . orders
has_many

orders . shipping_rates
has_many

shipping_rates . shipping_mappings
has_many

shipping_mappings . order_channel_sync_entries
has_many

order_channel_sync_entries . additional_attributes
has_many

additional_attributes .
Filters

id, attr

Routes
GET
https://<account name>.api.webshipper.io/v2/order_channels/{id}
GET
https://<account name>.api.webshipper.io/v2/order_channels
PATCH
https://<account name>.api.webshipper.io/v2/order_channels/{id}
POST
https://<account name>.api.webshipper.io/v2/order_channels
DELETE
https://<account name>.api.webshipper.io/v2/order_channels/{id}
GET https://<account name>.api.webshipper.io/v2/ order_channels/2

{
  "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

https://<account name>.api.webshipper.io/v2/order_channel_accesses

Grants a user access to an order channel. This has no effect if the user has been granted access to all order channels.

Attributes
created_at datetime

Read only
The time when the resource was created


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


Relationships
order_channel
has_one

order_channels . user
has_one

users .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/order_channel_accesses/{id}
GET
https://<account name>.api.webshipper.io/v2/order_channel_accesses
PATCH
https://<account name>.api.webshipper.io/v2/order_channel_accesses/{id}
POST
https://<account name>.api.webshipper.io/v2/order_channel_accesses
DELETE
https://<account name>.api.webshipper.io/v2/order_channel_accesses/{id}

Order Channel Type

https://<account name>.api.webshipper.io/v2/order_channel_types

Order Channel Types are used to create Order Channels

Attributes
name string


support_url string


public_global_attrs


list_logo


description text


module_link string


can_autofulfill boolean


can_limit_drop_points boolean


supports_rate_quoting boolean


uses_scheduled_import boolean


supports_time_interval_import boolean


supports_statuses_import boolean


supports_id_import boolean


supports_vat_in_checkout boolean


hide boolean


Relationships
local_attrs
has_many

local_attrs .
Filters

id, by_name

Routes
GET
https://<account name>.api.webshipper.io/v2/order_channel_types/{id}
GET
https://<account name>.api.webshipper.io/v2/order_channel_types

Order Line

https://<account name>.api.webshipper.io/v2/order_lines

Attributes
sku string

Stock Keeping Unit of the order line


description text

Description of the goods


quantity required integer

Quantity of goods


location string

The warehouse location of the items.


tarif_number string

HS Tarif code for paperless customs


country_of_origin string

The country of origin of the goods.


unit_price float

The unit price of goods in the currency of the order


package_id integer

Whether the items are associated with a parcel of a shipment.


discounted_unit_price

The unit price after discounts has been applied in the currency of the order


discount_value float

The discount for the order line, in the type given by discount_type


discount_type integer

The type of discount, eg. percent or fixed


vat_percent float

The VAT rate in percentage.


order_id integer


status integer

Possible enum values: pending, dispatched or returned


ext_ref string

External reference of the order line.


weight float

Weight per unit.


weight_unit string

Weight unit. Possible values: oz, g, lbs, kg. Defaults to g


created_at datetime

Read only
The time when the resource was created


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


is_virtual boolean


dangerous_goods_details object

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
package
has_one

packages . * order
has_one

orders . additional_attributes
has_many

additional_attributes .
Filters

id

Routes

Package

https://<account name>.api.webshipper.io/v2/packages

Attributes
weight required number

Weight of the package


weight_unit required enum

One of 'g', 'oz', 'lbs' and 'kg'


dimensions


service_attributes


add_ons


colli_type string

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.


predefined_barcode

A predefined SSCC barcode. Can be used if the barcode already has been created outside of Webshipper.


Relationships
shipment
has_one

shipments . order_lines
has_many

order_lines .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/packages/{id}
GET
https://<account name>.api.webshipper.io/v2/packages
POST
https://<account name>.api.webshipper.io/v2/packages

Pickup

https://<account name>.api.webshipper.io/v2/pickups

Pickups facilitates the booking of a pickup from a given carrier. Not all carriers supports pickup.

Attributes
pickup_instruction text

Instruction to the carrier.


pickup_location_close_time datetime

When the pickup location is closing.


pickup_time datetime

The time you want the carrier to arrive at the pickup address.


reference string

The reference returned by the carrier.


status integer

Decides if the pickup is requested or cancelled. To cancel a pickup you must update the status to cancelled.


created_at datetime

Read only
The time when the resource was created


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


shipping_address

The address where the shipments must be picked up.


carrier

The carrier that should pickup the shipments.


Relationships
carrier
has_one

carriers . shipping_address
has_one

shipping_addresses . shipments
has_many

shipments .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/pickups/{id}
GET
https://<account name>.api.webshipper.io/v2/pickups
PATCH
https://<account name>.api.webshipper.io/v2/pickups/{id}
POST
https://<account name>.api.webshipper.io/v2/pickups
DELETE
https://<account name>.api.webshipper.io/v2/pickups/{id}

Print Bulk Slips

https://<account name>.api.webshipper.io/v2/bulk_printer_jobs

Bulk add slips to the printer queue

Attributes
ids


model_type


printer_client_id


Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/bulk_printer_jobs/{id}
GET
https://<account name>.api.webshipper.io/v2/bulk_printer_jobs
PATCH
https://<account name>.api.webshipper.io/v2/bulk_printer_jobs/{id}
POST
https://<account name>.api.webshipper.io/v2/bulk_printer_jobs
DELETE
https://<account name>.api.webshipper.io/v2/bulk_printer_jobs/{id}

Printable

https://<account name>.api.webshipper.io/v2/printables

Attributes
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/printables/{id}
GET
https://<account name>.api.webshipper.io/v2/printables
PATCH
https://<account name>.api.webshipper.io/v2/printables/{id}
POST
https://<account name>.api.webshipper.io/v2/printables
DELETE
https://<account name>.api.webshipper.io/v2/printables/{id}

Printer

https://<account name>.api.webshipper.io/v2/printers

Printers are loaded automatically when connecting to your account from the Webshipper Silent Printer application.

Attributes
name string

Name of the printer.


active boolean

Determines if the printer is configured on the printer station


last_connected datetime

Last connection time


paper_width float

Paper width


paper_height float

Paper height


rotate_print_180 boolean


Relationships
client
has_one

printer_clients .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/printers/{id}
GET
https://<account name>.api.webshipper.io/v2/printers

Printer Client

https://<account name>.api.webshipper.io/v2/printer_clients

Printer clients are created automatically when connecting Webshipper Silent Printer and should not be created manually.

Attributes
uuid required string

Unique ID of the printer client


approved boolean

DEPRECATED


alias required string

Defaults to the host name of the machine running the client


is_online boolean

Shows if the printer client is online


last_connected datetime

Shows when the printer client was last connected


prevent_multiple_shipments boolean


Relationships
label_printer
has_one

printers . zpl_printer
has_one

printers . document_printer
has_one

printers . location
has_one

shipping_addresses . printers
has_many

printers . order_channels
has_many

order_channels .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/printer_clients/{id}
GET
https://<account name>.api.webshipper.io/v2/printer_clients
PATCH
https://<account name>.api.webshipper.io/v2/printer_clients/{id}

Printer Job

https://<account name>.api.webshipper.io/v2/printer_jobs

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
created_at datetime

Read only
The time when the resource was created


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


completed boolean

This will return as true when the printer client has accepted the job.


error string

Any error message that resulted.


base64

Read only
Base64 encoding if the associated printable, must the explicitly included in fields query parameter to be included


try_count integer


initiator string


options


Relationships
printer_client
has_one

printer_clients . printer
has_one

printers . printable
has_one

Polymorphic.
Filters

id, printer_client_id, created_at, completed, error, try_count, printer_id

Routes
GET
https://<account name>.api.webshipper.io/v2/printer_jobs/{id}
GET
https://<account name>.api.webshipper.io/v2/printer_jobs
PATCH
https://<account name>.api.webshipper.io/v2/printer_jobs/{id}
POST
https://<account name>.api.webshipper.io/v2/printer_jobs
DELETE
https://<account name>.api.webshipper.io/v2/printer_jobs/{id}

Quote Object

https://<account name>.api.webshipper.io/v2/rate_quotes_items

Attributes
price

Read only
Price in some currency


Filters

id

Routes

Rate Quote

https://<account name>.api.webshipper.io/v2/rate_quotes

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
quotes array

Read only
Array of quotes


success

Read only
DEPRECATED. The request will return an error response if the quote failed.


delivery_address required object

Delivery address for the quote. Flattened resource of 'Shipping Address'


price integer

The total price of the items


weight required float

Weight for the quote.


weight_unit required enum

The weight unit. Possible values: g, kg, lbs, oz.


height float

Height for the quote. The unit must match the unit you are using for shipping rate configurations.


length float

Length for the quote. The unit must match the unit you are using for shipping rate configurations.


width float

Width for the quote. The unit must match the unit you are using for shipping rate configurations.


dimensions_unit

Dimensions unit. Possible values: cm, m, in, ft


sender_address object

Delivery address for the quote. Flattened resource of 'Shipping Address'


items array

Array of items, each item should have fields quantity, sku, description


order_channel_id required integer

The id of the order channel for which to get shipping rates.


currency


include_hidden boolean

Also include shipping rates which are normally hidden during checkout.


is_return boolean

Set to true to quote for return rates. If false standard rates are quoted. Default: false.


additional_attributes

Possibility to add hash of additional attributes for filtering.


filter_by_currency


Filters

id

Routes
POST
https://<account name>.api.webshipper.io/v2/rate_quotes
POST https://<account name>.api.webshipper.io/v2/ rate_quotes

{
  "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"
    }
  }
}
POST https://<account name>.api.webshipper.io/v2/ rate_quotes

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

https://<account name>.api.webshipper.io/v2/reports

Reports are generated by using Report Types which specify how a report should look and which records to include in the report.

Attributes
updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


created_at datetime

Read only
The time when the resource was created


start_time datetime


end_time datetime


output_formats array


parameters object


base64 string

Read only


pdf_download_url


xml_download_url


csv_download_url


json_download_url


xlsx_download_url


failed boolean


order_ids


error_message text


Relationships
report_type
has_one

report_types . carrier
has_one

carriers . print_jobs
has_many

printer_jobs .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/reports/{id}
GET
https://<account name>.api.webshipper.io/v2/reports
PATCH
https://<account name>.api.webshipper.io/v2/reports/{id}
POST
https://<account name>.api.webshipper.io/v2/reports
DELETE
https://<account name>.api.webshipper.io/v2/reports/{id}

Report Type

https://<account name>.api.webshipper.io/v2/report_types

This resource acts a template for creating resource.

Attributes
name string


columns array

Array of objects with keys header and content


parameters array

Array of objects with keys parameter_key and parameter_value


resource string


header_columns array

Array of objects with keys header and content that will be used to display the header content of the report


footer_content text


conditions array

Array of objects describing how to load the resources. Contains keys condition_key, condition_operator, condition_value.


include_deleted boolean

If true the report will included deleted records. Default: false


use_carrier_eod boolean

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.


created_at datetime

Read only
The time when the resource was created


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


schedule string


default_format string


mail_on_run boolean


mail string


Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/report_types/{id}
GET
https://<account name>.api.webshipper.io/v2/report_types
PATCH
https://<account name>.api.webshipper.io/v2/report_types/{id}
POST
https://<account name>.api.webshipper.io/v2/report_types
DELETE
https://<account name>.api.webshipper.io/v2/report_types/{id}

Requeueable Printer Jobs

https://<account name>.api.webshipper.io/v2/printer_requeue_jobs

Find and requeue failed printer jobs within the given timeframe

Attributes
start_time


end_time


job_id


mark_as_complete


Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/printer_requeue_jobs/{id}
GET
https://<account name>.api.webshipper.io/v2/printer_requeue_jobs
PATCH
https://<account name>.api.webshipper.io/v2/printer_requeue_jobs/{id}
POST
https://<account name>.api.webshipper.io/v2/printer_requeue_jobs
DELETE
https://<account name>.api.webshipper.io/v2/printer_requeue_jobs/{id}

Return Causes

https://<account name>.api.webshipper.io/v2/return_causes

Description of the cause

Attributes
name string


description text


require_comment boolean

Does the cause require a comment


limit_refund_methods boolean

Does the cause limit refund methods


support_image_required boolean

Does the cause support image required


Relationships
portal
has_one

return_portals . refund_methods
has_many

return_refund_methods .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/return_causes/{id}
GET
https://<account name>.api.webshipper.io/v2/return_causes
PATCH
https://<account name>.api.webshipper.io/v2/return_causes/{id}
POST
https://<account name>.api.webshipper.io/v2/return_causes
DELETE
https://<account name>.api.webshipper.io/v2/return_causes/{id}

Return Lines

https://<account name>.api.webshipper.io/v2/return_lines

Read only resource for return lines.

Attributes
cause_description text

Description of the cause


quantity integer

Quantity of the return line


refund_method

Refund method for the return line


Relationships
return
has_one

returns . cause
has_one

return_causes . order_line
has_one

order_lines . refund_method
has_one

return_refund_methods .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/return_lines/{id}
GET
https://<account name>.api.webshipper.io/v2/return_lines
PATCH
https://<account name>.api.webshipper.io/v2/return_lines/{id}
POST
https://<account name>.api.webshipper.io/v2/return_lines
DELETE
https://<account name>.api.webshipper.io/v2/return_lines/{id}

Return Order

https://<account name>.api.webshipper.io/v2/returns

Attributes
status string

One of pending, sent, arrived, processed, error or approved


error_message text


return_lines required array

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


base64

Base 64 encoding of return slip


secret string

Read only
Read only token for publicly accessing status of the return order


internal_comment text


latest_activity


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


created_at datetime

Read only
The time when the resource was created


order_channel_id integer


internal_session_id string


Relationships
order
has_one

orders . portal
has_one

return_portals . shipping_method
has_one

return_shipping_methods . shipment
has_one

shipments . activities
has_many

activities . events
has_many

events . comments
has_many

comments .
Filters

id, secret, activity_type, status, portal_id, free_text, return_causes

Routes
GET
https://<account name>.api.webshipper.io/v2/returns/{id}
GET
https://<account name>.api.webshipper.io/v2/returns
PATCH
https://<account name>.api.webshipper.io/v2/returns/{id}
POST
https://<account name>.api.webshipper.io/v2/returns
DELETE
https://<account name>.api.webshipper.io/v2/returns/{id}
https://<account name>.api.webshipper.io/v2/ returns/1

{
  "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

https://<account name>.api.webshipper.io/v2/return_portals

Attributes
name string


custom_style text


shipping_methods


translations


locale string


allowed_days_since_dispatch integer


send_immediately boolean


static_notice_email string


order_channel_logo


logo


force_single_page boolean


order_channel_id integer


optional_return_cause boolean


new_mail_template


new_confirmation_mail_template


email_address_source integer


email_address_resource_options


finished_stripe_setup


Relationships
order_channel
has_one

order_channels . slip_template
has_one

slip_templates . mail_template
has_one

mail_templates . confirmation_mail_template
has_one

mail_templates . return_address
has_one

shipping_addresses . returns
has_many

returns . causes
has_many

return_causes . refund_methods
has_many

return_refund_methods .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/return_portals/{id}
GET
https://<account name>.api.webshipper.io/v2/return_portals
PATCH
https://<account name>.api.webshipper.io/v2/return_portals/{id}
POST
https://<account name>.api.webshipper.io/v2/return_portals
DELETE
https://<account name>.api.webshipper.io/v2/return_portals/{id}

Return Shipping Method

https://<account name>.api.webshipper.io/v2/return_shipping_methods

Attributes
name string


excluded_skus string


excluded_zip_codes string


excluded_countries string


Relationships
portal
has_one

return_portals . shipping_rate
has_one

shipping_rates .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/return_shipping_methods/{id}
GET
https://<account name>.api.webshipper.io/v2/return_shipping_methods
PATCH
https://<account name>.api.webshipper.io/v2/return_shipping_methods/{id}
POST
https://<account name>.api.webshipper.io/v2/return_shipping_methods
DELETE
https://<account name>.api.webshipper.io/v2/return_shipping_methods/{id}

Service Quote

https://<account name>.api.webshipper.io/v2/service_quotes

Service Quotes are used to find suitable services by quoting the carriers directly.

Attributes
success boolean

Read only
True if quote was successful


carrier_id required integer

The id of the carrier to quote


service_code

Service code of the carrier. This is optional. When omitted, all supported services will be returned.


send_time required datetime

ISO 8601 formatted


send_date


packages required array

Array of objects, each containing key weight. At least one package is required.


delivery_address required object

Delivery address for the quote


sender_address required object

Sender address for the quote


services array

Read only
Read only. Populated in response with an array of objects containing the following keys:
  • service_name
  • service_code
  • is_return
  • supports_paperless
  • requires_drop_point
  • cost_price
  • currency
  • vat_percent
  • estimated_delivery_date_from
  • estimated_delivery_date_to
  • add_ons
    Array containing objects
    • add_on_name
    • add_on_code
  • parameters
  • Array containing objects
    • attr_name
    • attr_key
    • attr_type
  • country_combinations
  • barcode_requirement
  • waybill_requirement
  • booking_quote_info
  • supported_colli_types


add_ons

Carrier add-ons for the quote


service_attributes

Service attributes for the carrier


is_return

Determines if you are quoting for return (inbound) services or standard (outbound) services.


dutiable

Determines if the goods for the quote are dutiable


cost_sheet_id

Used if you want only a price from a specific cost sheet


timeout

Timeout for request in seconds. Will default to 15 seconds


Filters

id

Routes
POST
https://<account name>.api.webshipper.io/v2/service_quotes
POST https://<account name>.api.webshipper.io/v2/ service_quotes

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

https://<account name>.api.webshipper.io/v2/shipments

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
Please note that when updating shipments you should only include fields that you wish to change, and if you only wish to change part of a field, i.e. add a package to an existing set of packages, you should include all current data. For adding a package that means you should include the array of packages as it is before the change, remember to include ids for each existing package. New packages should not have an id. If you leave out ids for an existing object it will be deleted and recreated, this might result in new barcodes and other changes. You can see an example of updating package data in the "use cases" tab to the right.

Attributes
reference required string

The reference you want to identify the shipment form. For example order number.


comment text

An optional comment for the carrier


service_code string

The carrier's service code. This should only be assigned if you are not using a shipping rate.


is_return boolean

Determines whether the shipment is a return shipment.


packages required array

Flattened array of packages to be sent. At least one package is mandatory. For structure refer to 'Package' entity


delivery_address required object

Flattened Shipping Address representing the delivery address for the shipment.
Duplicated from order if order relation given..


sender_address required object

Flattened Shipping Address representing the sender address of shipment.
Duplicated from order if order relation given..


billing_address object

Flattened Shipping Address representing the billing address of shipment. Duplicated from delivery address if empty.
Duplicated from order if order relation given..


pickup_address object

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..


return_address object

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..


service_attributes array

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. .


add_ons array

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.


sms_notification

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.


email_notification

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.


included_documents

Flattened array of Document - can be used to upload documents to the shipment which will be sent to the carrier.


drop_point

Flattened Drop Point - should only be assigned if you are sending to a drop point.


tracking_links array

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


fulfill_immediately

Deprecated


test_mode boolean


dutiable boolean


created_at datetime

Read only
The time when the resource was created


ext_ref string

The external (carrier) reference


original_shipment_id integer


send_time datetime


status integer


latest_update_time


supports_updates


additional_attributes

Flattened hash with optional key/value pairs.


cost_price float

The cost price of the shipment, either directly from the carrier or from a cost sheet


sales_price float

The price presented to the customer in checkout


currency string


manual_order_shipment_creation


carrier_type_name string

Read only
Webshipper defined name of the carrier type


carrier_alias string

Read only
Carrier alias set by the user in Webshipper


carrier_id integer

Read only
ID of the carrier


invoice_settings


latest_activity


latest_status_event


shadow_booking_as_parent


source integer


document_template


csv_upload_id integer


omit_print boolean


original_shipment

An optional link to the original shipment, when creating a return-shipment


Relationships
carrier
has_one

carriers . order
has_one

orders . shipping_rate
has_one

shipping_rates . printer_client
has_one

printer_clients . original_shipment
has_one

shipments . pickup
has_one

pickups . shadow_shipment
has_one

shipments . return
has_one

returns . document_template
has_one

document_templates . mail_template
has_one

mail_templates . return_label_mail_template
has_one

mail_templates . labels
has_many

labels . documents
has_many

documents . attachments
has_many

attachments . edis
has_many

edis . additional_attributes
has_many

additional_attributes . events
has_many

events . return_shipments
has_many

shipments . activities
has_many

activities . status_events
has_many

activities . stores
has_many

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
https://<account name>.api.webshipper.io/v2/shipments/{id}
POST
https://<account name>.api.webshipper.io/v2/shipments
GET
https://<account name>.api.webshipper.io/v2/shipments
GET https://<account name>.api.webshipper.io/v2/ shipments/432

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"
    }
  }
}
POST https://<account name>.api.webshipper.io/v2/ shipments

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
        }
      }
    }
  }
}
POST https://<account name>.api.webshipper.io/v2/ shipments

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
        }
      }
    }
  }
}
POST https://<account name>.api.webshipper.io/v2/ shipments

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
        }
      }
    }
  }
}
POST https://<account name>.api.webshipper.io/v2/ shipments

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
        }
      }
    }
  }
}
POST https://<account name>.api.webshipper.io/v2/ shipments

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
        }
      }
    }
  }
}
PUT https://<account name>.api.webshipper.io/v2/ shipments

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

https://<account name>.api.webshipper.io/v2/shipping_addresses

Attributes
att_contact required string

Att person. To generate parcels either att_contact or company_name is required


company_name required string

Company name. To generate parcels either att_contact or company_name is required


address_1 required string

Address line 1


address_2 string

Address line 2


country_code required string

ISO 3166-1 alpha-2 code


state string

Sub-division of country, if applicable. State code. ISO 3166-2 alpha-2


phone string

Phone number of the entity. This can be used for SMS notifications.


email string

E-mail address of the entity. This can be used for e-mail notifications.


zip string

Postal code of the entity. This is required for most destination countries.


city string

City of the entity. This is required for most destination countries.


vat_no string

The VAT number of the entity. This is only required for address_type sold_from


address_type string

Used for special addresses for order channels. This will be one of the following: recipient, sender, sold_from, pickup, return, order_address


ext_location string


voec


eori


sprn


ioss


fda


duns


personal_customs_no


company_customs_numbers


Filters

id, att_contact, company_name, address_1, address_2, country_code, state, zip, address_type, search

Routes
GET
https://<account name>.api.webshipper.io/v2/shipping_addresses/{id}
GET
https://<account name>.api.webshipper.io/v2/shipping_addresses
PATCH
https://<account name>.api.webshipper.io/v2/shipping_addresses/{id}
POST
https://<account name>.api.webshipper.io/v2/shipping_addresses
DELETE
https://<account name>.api.webshipper.io/v2/shipping_addresses/{id}

Shipping Mapping

https://<account name>.api.webshipper.io/v2/shipping_mappings

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 string

Shipping code is a unique identifier from the order channel that will be mapped to a shipping rate


shipping_name string

Shipping name is a human readable identifier of the shipping method


shipping_rate_id integer

Shipping rate id is the id of the shipping rate which you want to map to.


order_channel_id integer

Order channel id of the order channel


created_at datetime

Read only
The time when the resource was created


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


Relationships
shipping_rate
has_one

shipping_rates . order_channel
has_one

order_channels .
Filters

id, order_channel_id, order_channel, shipping_code

Routes
GET
https://<account name>.api.webshipper.io/v2/shipping_mappings/{id}
GET
https://<account name>.api.webshipper.io/v2/shipping_mappings
PATCH
https://<account name>.api.webshipper.io/v2/shipping_mappings/{id}
POST
https://<account name>.api.webshipper.io/v2/shipping_mappings
DELETE
https://<account name>.api.webshipper.io/v2/shipping_mappings/{id}

Shipping Rate

https://<account name>.api.webshipper.io/v2/shipping_rates

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
carrier_id integer

Read only
Id of the carrier which the shipping rate belongs to


order_channel_id integer

Read only
Id of the order channel which the shipping rate belongs to


name required string

Name to be displayed in the e-commerce system.


carrier_service_code required string

The carrier's service code which must be used when generating parcels with this shipping rate.


require_drop_point boolean

Determines if the shipping rate requires a drop point to be assigned.


visible_for integer

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


service_attributes

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.


dimensions

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.


add_ons

Array of add_ons supported by the carrier service.


is_return boolean

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.


carriers_email boolean

When this is set to true, the shipping rate will enable e-mail notifications from the carrier.


comment_map string

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}}


reference_map string

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}}


carriers_sms boolean

When this is set to true, the shipping rate will enable SMS notifications from the carrier.


dutiable boolean

Defines whether the goods sent using this shipping rate are dutiable.


is_hidden boolean

Attribute to indicate if the shipping rate is visible to order channels


click_collect boolean


reference text


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


created_at datetime

Read only
The time when the resource was created


default_colli_type string

Predefined colli type to be used when using the shipping rate. Must be supported by the carrier.


sender_address_id integer


return_address_id integer


invoice_settings


shadow_booking_keep_labels boolean


shadow_booking_keep_documents boolean


ignore_rate_quote_validation boolean


custom_message string

Custom message to be displayed for the shipping rate


regions

Flattended array of Regions. See section on Shipping Regions and Expressions for more details


Relationships
* carrier
has_one

carriers . The carrier which must be used * order_channel
has_one

order_channels . The order channel which the shipping rate belongs to. return_shipping_rate
has_one

shipping_rates . sender_address
has_one

shipping_addresses . return_address
has_one

shipping_addresses . mail_template
has_one

mail_templates . return_mail_template
has_one

mail_templates . document_template
has_one

document_templates . shadow_booking_shipping_rate
has_one

shipping_rates . regions
has_many

regions . stores
has_many

stores .
Filters

id, order_channel_id, is_return, is_hidden, service_code, shadow_bookings

Routes
GET
https://<account name>.api.webshipper.io/v2/shipping_rates/{id}
GET
https://<account name>.api.webshipper.io/v2/shipping_rates
PATCH
https://<account name>.api.webshipper.io/v2/shipping_rates/{id}
POST
https://<account name>.api.webshipper.io/v2/shipping_rates
DELETE
https://<account name>.api.webshipper.io/v2/shipping_rates/{id}

Shipping Rate Expression

https://<account name>.api.webshipper.io/v2/expressions

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
expression text

Is the actual WEL expression to be evaluated


vat_percent required float

VAT rate in percentage which must be added to the price.


currency required string

Currency of the price


price required float

The cost price displayed to the end user


Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/expressions/{id}
GET
https://<account name>.api.webshipper.io/v2/expressions
PATCH
https://<account name>.api.webshipper.io/v2/expressions/{id}
POST
https://<account name>.api.webshipper.io/v2/expressions
DELETE
https://<account name>.api.webshipper.io/v2/expressions/{id}

Shipping Region

https://<account name>.api.webshipper.io/v2/regions

Shipping regions handle multiple countries as a group, e.g. the European Union.

Attributes
name string

Name


expressions

Flattened array of expressions. Please see section 8 for more details regarding expressions.


created_at datetime

Read only
The time when the resource was created


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


countries text


Relationships
shipping_rate
has_one

shipping_rates .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/regions/{id}
GET
https://<account name>.api.webshipper.io/v2/regions
PATCH
https://<account name>.api.webshipper.io/v2/regions/{id}
POST
https://<account name>.api.webshipper.io/v2/regions
DELETE
https://<account name>.api.webshipper.io/v2/regions/{id}

Slip Template

https://<account name>.api.webshipper.io/v2/slip_templates

Templates for generating parcel slips. The Webshipper Template Language (WTL) may be used when creating templates.

Attributes
name required string

Name to identify the template.


slip_size integer

Size of the parcel slip. Possible values: A4 and 4X6


additional_content text

Content after the table of order lines for A4-based parcel slips.


additional_content_align integer

Alignment of additional_content. Possible values: center, right, left


barcode_content string

Content of the barcode


header_content text

Content of the slip header


top_left_content_header string

Header of the top left corner


top_right_content_header string

Header of the top right corner


top_left_content text

Content of the top left corner


top_right_content text

Content of the top right corner


footer_content text

Content of the footer


slip_template_columns

Array of columns. Column objects contains: namecontent, text_alignment(right, left, center), width (in percentage)


table_color string

HEX color including #


table_text_color string

HEX color including #


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


created_at datetime

Read only
The time when the resource was created


sort_key string

The key to sort the order-lines by


returns_only boolean


disable_inline_formatting boolean


used_by_order_channels

which order_channels use slip_template. If not used by any, it will return empty list


Relationships
order_channels
has_many

order_channels .
Filters

id, returns_only

Routes
GET
https://<account name>.api.webshipper.io/v2/slip_templates/{id}
GET
https://<account name>.api.webshipper.io/v2/slip_templates
PATCH
https://<account name>.api.webshipper.io/v2/slip_templates/{id}
POST
https://<account name>.api.webshipper.io/v2/slip_templates
DELETE
https://<account name>.api.webshipper.io/v2/slip_templates/{id}

Slip Template Preview

https://<account name>.api.webshipper.io/v2/slip_template_previews

Attributes
slip_template


order_visible_ref


base64


example_id


Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/slip_template_previews/{id}
GET
https://<account name>.api.webshipper.io/v2/slip_template_previews
PATCH
https://<account name>.api.webshipper.io/v2/slip_template_previews/{id}
POST
https://<account name>.api.webshipper.io/v2/slip_template_previews
DELETE
https://<account name>.api.webshipper.io/v2/slip_template_previews/{id}

Store

https://<account name>.api.webshipper.io/v2/stores

Used for click n collect if activated on the shipping rate.

Attributes
name string


address_1 string


address_2 string


zip string


city string


country_code string


longitude string


latitude string


Relationships
sender_address
has_one

shipping_addresses . return_address
has_one

shipping_addresses . pickup_address
has_one

shipping_addresses . sold_from_address
has_one

shipping_addresses . shipping_rates
has_many

shipping_rates .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/stores/{id}
GET
https://<account name>.api.webshipper.io/v2/stores
PATCH
https://<account name>.api.webshipper.io/v2/stores/{id}
POST
https://<account name>.api.webshipper.io/v2/stores
DELETE
https://<account name>.api.webshipper.io/v2/stores/{id}

Tag

https://<account name>.api.webshipper.io/v2/tags

Read only resources describing all tags used. The index action returns a unique list of all tags currently

Attributes
tag string

Read only


Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/tags

Tracking Event

https://<account name>.api.webshipper.io/v2/tracking_events

Attributes
status string

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 datetime

Time the event occured at the carrier


description text

Readable description of the event


location string


latitude float


longitude float


tracking_number

The tracking number for this event, if availiable


event_id string

Unique event of the id


shipment_id integer

ID of shipment


tracking_link_id integer


tracking_link_url

The tracking link for this event, if availiable


created_at datetime

Read only
The time when the resource was created


Relationships
package
has_one

packages . The package for this event, if availiable shipment
has_one

shipments . The shipment for this event.
Filters

id, created_at, shipment_id

Routes
GET
https://<account name>.api.webshipper.io/v2/tracking_events
GET
https://<account name>.api.webshipper.io/v2/tracking_events/{id}

Trigger

https://<account name>.api.webshipper.io/v2/triggers

Trigger for automations. When evaluated to true, the automation will start.

Attributes
expression text

WEL expression for the trigger


expression_ast


model_type string

Model for the trigger. E.g. Order


event string

created or updated


timing integer


Relationships
automation
has_one

automations .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/triggers/{id}
GET
https://<account name>.api.webshipper.io/v2/triggers
PATCH
https://<account name>.api.webshipper.io/v2/triggers/{id}
POST
https://<account name>.api.webshipper.io/v2/triggers
DELETE
https://<account name>.api.webshipper.io/v2/triggers/{id}

User

https://<account name>.api.webshipper.io/v2/users

Attributes
first_name string

The user's first name.


last_name string

The user's last name.


email string

The user's e-mail address.


password integer

The user's password. This can only be used for changing the password.


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


created_at datetime

Read only
The time when the resource was created


last_sign_in_at datetime

The time of the most recent sign-in by the user.


all_order_channels boolean

Specifies whether the user has access to all order channels on the tenant.


all_carriers boolean

Specifies whether the user has access to all of the carriers for tenant.


hidden boolean

Specifies whether the user should be hidden in the user interface.


current_password

This must be set when changing the password of the user.


locale integer

Locale enum. da or en


locked_until datetime

Locked until specified datetime


failed_count integer

Amount of failed login attempts since last login


is_locked

Read only. Will be true when the user is temporarily locked due to too many login attempts


user_status integer


home_page text

The home page set by the user


limit_order_search text


view_ids boolean


Relationships
user_group
has_one

user_groups . printer_client
has_one

printer_clients . The printer client (workstation) which the user is currently assigned to. order_channel_accesses
has_many

order_channel_accesses . carrier_accesses
has_many

carrier_accesses . store_assignments
has_many

store_assignments . stores
has_many

stores . favourite_pages
has_many

favourite_pages . consents
has_many

user_consents .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/users/{id}
GET
https://<account name>.api.webshipper.io/v2/users
PATCH
https://<account name>.api.webshipper.io/v2/users/{id}
POST
https://<account name>.api.webshipper.io/v2/users
DELETE
https://<account name>.api.webshipper.io/v2/users/{id}

User Group

https://<account name>.api.webshipper.io/v2/user_groups

Attributes
name string

Name of the user group


scopes array

Array of scopes. Please see section 6 for more details regarding scopes.


locked boolean


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


created_at datetime

Read only
The time when the resource was created


Relationships
users
has_many

users .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/user_groups/{id}
GET
https://<account name>.api.webshipper.io/v2/user_groups
PATCH
https://<account name>.api.webshipper.io/v2/user_groups/{id}
POST
https://<account name>.api.webshipper.io/v2/user_groups
DELETE
https://<account name>.api.webshipper.io/v2/user_groups/{id}

Waybill

https://<account name>.api.webshipper.io/v2/waybills

Attributes
waybill_name string

Name of the waybill type


waybill_code string

Code identifying the type of waybill


reference string

Unique reference returned from the carrier implementation when a waybill is opened.


consolidation_key string


barcode_serial integer

This will be assigned by the API if the waybill type has a barcode requirement.


status integer

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.


shipment_count

This is a read-only attribute which returns the total number of shipments.


currency string


copies integer


created_at datetime

Read only
The time when the resource was created


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


documents

Array of documents. This is available when the waybill is closed.


Relationships
carrier
has_one

carriers . sold_to_address
has_one

shipping_addresses . sender_address
has_one

shipping_addresses . document_template
has_one

document_templates . printer_client
has_one

printer_clients . shipments
has_many

shipments . documents
has_many

documents .
Filters

id, status, carrier

Routes
GET
https://<account name>.api.webshipper.io/v2/waybills/{id}
GET
https://<account name>.api.webshipper.io/v2/waybills
PATCH
https://<account name>.api.webshipper.io/v2/waybills/{id}
POST
https://<account name>.api.webshipper.io/v2/waybills
DELETE
https://<account name>.api.webshipper.io/v2/waybills/{id}

Webhook

https://<account name>.api.webshipper.io/v2/webhooks

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'.

Webshipper highly recommends not processing webhooks immediately but instead putting the webhooks in a queue and then process the webhooks asynchronously.

Webhooks are retried 21 times over a period of 8 days. An e-mail message will be sent to your account's technical contact if a webhook has been failing for 4 hours. After all retries have been exhaused, the webhook is disabled entirely and a new one must be created. The account's technical contact will also be notified by e-mail when a webhook is disabled in this scenario.

All webhooks are sent using the X-Webshipper-Hmac-SHA256 header, which contains the Base64 encoding of the HMAC of the JSON request body signed with your customer secret using SHA256. Webhooks also include the X-Webshipper-Topic header used to indicate the webhook topic.

Example in Ruby:

  Base64.strict_encode64(OpenSSL::HMAC.digest('sha256', secret, data))  
Example in .NET

  var request_body = "RAW REQUEST BODY GOES HERE: IT IS UTF8 ENCODED ✅";

  var hmac = new HMACSHA256( Encoding.UTF8.GetBytes("secret123"));
  var digest = System.Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(request_body)));
  Console.WriteLine(digest);
          
        

Note that for 'deleted' webhooks, not all attributes can be expected to be present

Attributes
url string

The HTTP endpoint to be called. Webhooks always use POST as the request method.


topic string

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.


enabled boolean

This is a boolean attribute that specifies whether the webhook is active.


secret string

The secret used to sign the HMAC.


health


latest_error text

The most recent error message.


condition text


created_at datetime

Read only
The time when the resource was created


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


carriers


order_channels array

Read only
Array of objects containing keys id and channel_label if condition describes a list of allowed order channels, null otherwise.


Relationships
owner
has_one

Polymorphic. The User or the Application that created the webhook failures
has_many

webhook_failures . jobs
has_many

webhook_jobs .
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/webhooks/{id}
GET
https://<account name>.api.webshipper.io/v2/webhooks
PATCH
https://<account name>.api.webshipper.io/v2/webhooks/{id}
POST
https://<account name>.api.webshipper.io/v2/webhooks
DELETE
https://<account name>.api.webshipper.io/v2/webhooks/{id}

Webhook Failure

https://<account name>.api.webshipper.io/v2/webhook_failures

A log entry with details of a failed webhook request the last 7 days.

Attributes
record_id integer

Read only
The id of the record the webhook failed to send


message text

Read only
Title of the failure


created_at datetime

Read only
The time when the resource was created


updated_at datetime

Read only
The time when resource was last updated or when it was created if it was never updated


Relationships
webhook
has_one

webhooks . The Webhook this failures belongs to.
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/webhook_failures/{id}
GET
https://<account name>.api.webshipper.io/v2/webhook_failures
PATCH
https://<account name>.api.webshipper.io/v2/webhook_failures/{id}
POST
https://<account name>.api.webshipper.io/v2/webhook_failures
DELETE
https://<account name>.api.webshipper.io/v2/webhook_failures/{id}