1 Introduction

1.1 Convensions

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 convensions:

  • 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

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_date": "03-04-2018",
      "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_date": "03-04-2018",
            "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 convensions 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.

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 = 'SAHRED 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, 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"],
    ]
  }

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"
        }
      ],
      "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",
          "enum": [
            [
              "Halv palle",
              "half_pallet"
            ],
            [
              "Hel palle",
              "pallet"
            ]
          ]
        }
      ],
      "country_combinations": [
        {
          "sender_country": "DK",
          "recipient_countries": [
            "DK",
            "SE",
            "NO"
          ]
        },
        {
          "sender_country": "SE",
          "recipient_countries": [
            "DK"
          ]
        }
      ]
    }
  ]
}

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

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": [
      {
        "weight": 1000,
        "weight_unit": "g",
        "dimensions": {
          "height": 15,
          "length": 15,
          "width": 15,
          "unit": "cm"
        }
      }
    ],
    "send_date": "2017-10-04 11:43:18 +0200",
    "service_code": "EE",
    "add_ons": ["COD"],
    "service_attributes": {
      "transport_type": "pallet"
    },
    "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"
          }
        ],
        "parameters": [
          {
            "attr_name": "Ladmeter",
            "attr_key": "ladmeter",
            "attr_type": "integer",
            "required": true
          },
          {
            "attr_name": "Gods type",
            "attr_key": "transport_type",
            "attr_type": "enum",
            "enum": [
              [
                "Halv palle",
                "half_pallet"
              ],
              [
                "Hel palle",
                "pallet"
              ]
            ]
          }
        ],
        "country_combinations": [
          {
            "sender_country": "DK",
            "recipient_countries": [
              "DK",
              "SE",
              "NO"
            ]
          },
          {
            "sender_country": "SE",
            "recipient_countries": [
              "DK"
            ]
          }
        ]
      }
    ]
  }


7.4 Booking endpoint

The booking endpoint is mandatory. This is the endpoint that Webshipper will call every time a shipment is generated. Documents are not mandatory, but can be used in case you want to return, for example, customs documents.

Valid document sizes are:

  • 100X150
  • 100X192
  • A4

Valid label sizes are:

  • 100X150
  • 100X192

The carrier code returned must correspond to any currently registered carrier in Webshipper.

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>

{
  "test_mode": true,
  "shipment_id": 12,
  "carrier_code": "MYCARRIER",
  "service_code": "MYSERVICECODE",
  "label_format": "ZPL",
  "carrier_attributes": {
    "barcode_prefix": "57125",
    "customer_id": "12345"
  },
  "service_attributes": {
    "transport_type": "pallet",
    "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",
        }
      ],
      "dimensions": {
        "height": 10,
        "width": 20,
        "length": 30,
        "unit": "cm"
      }
    }
  ]
}


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.


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

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 Included a label or document as a downloadable link. Example {{ label | pdf_attachment('Download Label', 'return-label.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
 

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

Relationships
automation
has_one
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}

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

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

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}

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

Relationships
carrier
has_one
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_channel_id

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
string

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

* target_class
string

Must be one of the models Order or Shipment

* grouped_by
integer

Must be the index of the Order ID

* grouped_path
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

* name
string

Name of the configuration

example_input
text

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

rules
array

Array of flattened resources of the type CSV Rule

Relationships
carrier
has_one
order_channel
has_one
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
string

Path of the attribute to update

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

created_at
datetime

Read only
The time when the resource was created

Relationships
mapping
has_one
Filters

id

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

Carrier

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

Attributes
* alias
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, 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

Relationships
carrier_type
has_one
shipping_rates
has_many
Filters

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

Relationships
local_attrs
has_many
carriers
has_many
Filters

id

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

Document

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

Additional shipment documents. This is used for customs declarations etc.

Attributes
shipment_id
integer

Id of the shipment it belongs to

* document_size
integer

Enum for the paper size. valid values: A4

* document_format
integer

Enum for the document format. Valid values: PDF

* base64

Base64 representation of the document

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
Filters

id

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}

Drop Point

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

Attributes
* drop_point_id
string

The carriers ID of the drop point.

* name
string

Name of the drop point

* address_1
string

Address line 1 of the drop point

address_2
string

Address line 2 of the drop point

* zip
string

Zip code for the drop point

* city
string

City for the drop point

* country_code
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
integer

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

* service_code
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

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

* delivery_address

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.

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

{
  "data": {
    "id": "1",
    "type": "drop_point_locators",
    "links": {
      "self": "/v2/drop_point_locators/1"
    },
    "attributes": {
      "carrier_id": null,
      "service_code": null,
      "shipping_rate_id": 1,
      "delivery_address": {
        "address_1": "Lyngbygade 8",
        "zip": "8600",
        "city": "Silkeborg",
        "country_code": "DK"
      },
      "drop_points": [

      ]
    },
    "meta": {
      "copyright": "© 2019 Webshipper ApS"
    }
  }
}

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

Label

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

A shipping label. Shipping labels wrap PDF documents.

Attributes
shipment_id
integer

label_size
integer

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

label_format
integer

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

base64

Base64 encoding of the pdf document

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
Filters

id

Routes
GET
https://<account name>.api.webshipper.io/v2/labels/{id}
GET
https://<account name>.api.webshipper.io/v2/labels
PATCH
https://<account name>.api.webshipper.io/v2/labels/{id}
POST
https://<account name>.api.webshipper.io/v2/labels
DELETE
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": "2019-05-02T08:21:36.0Z",
      "created_at": "2019-05-02T08:21:36.0Z"
    },
    "relationships": {
      "print_jobs": {
        "links": {
          "self": "/v2/labels/1/relationships/print_jobs",
          "related": "/v2/labels/1/print_jobs"
        }
      }
    },
    "meta": {
      "copyright": "© 2019 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
string

Visible name of the attribute

* attr_key
string

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

* attr_type
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

Relationships
order_channel_type
has_one
local_attr_enums
has_many
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
    },
    "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"
        }
      }
    },
    "meta": {
      "copyright": "© 2019 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
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": "© 2019 Webshipper ApS"
    }
  }
}

Merged PDF

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

Attributes
* include_labels
boolean

Whether to include labels or not

* include_docs
boolean

Whether to include docs or not'

* include_slips
boolean

Whether to include slips or not

* force_a4
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

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

Id of the owner

* expires_in
integer

Epoch timestamp of the expiration date for the token

expired

* token
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
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,
      "token": 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": "© 2019 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
string

Application name

* uid
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
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": "© 2019 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
string

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

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
array

Flattened resource of type OrderLine

* delivery_address
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

* currency
string

Currency code of the order

internal_comment
object

Internal order comment.

external_comment
object

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

Relationships
* order_channel
has_one
shipping_rate
has_one
error_type
has_one
shipments
has_many
additional_attributes
has_many
print_jobs
has_many
packages
has_many
Filters

id, order_channel_id, ext_ref, sorting_id, created_at, updated_at, status, visible_ref, order_channel, shipping_rate, carrier, sku, delivery_address, free_text, tag

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,
          "discounted_unit_price": 24.0,
          "additional_attributes": {
          }
        }
      ],
      "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
      },
      "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
      },
      "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
      },
      "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
    },
    "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"
        }
      },
      "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"
        }
      }
    },
    "meta": {
      "copyright": "© 2019 Webshipper ApS"
    }
  }
}

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

Relationships
order_channel_type
has_one
slip_template
has_one
sender_address
has_one
return_address
has_one
pickup_address
has_one
sold_from_address
has_one
default_printer_client
has_one
orders
has_many
shipping_rates
has_many
shipping_mappings
has_many
order_channel_sync_entries
has_many
additional_attributes
has_many
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,
          "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": null
    },
    "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": "© 2019 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
user
has_one
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

Relationships
local_attrs
has_many
Filters

id

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

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

Relationships
package
has_one
* order
has_one
additional_attributes
has_many
Filters

id

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

Package

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

Attributes
* weight
float

Weight of the package

* weight_unit
string

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

dimensions

Relationships
shipment
has_one
order_lines
has_many
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
shipping_address
has_one
shipments
has_many
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}

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

Relationships
client
has_one
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
string

Unique ID of the printer client

approved
boolean

DEPRECATED

* alias
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

Relationships
label_printer
has_one
zpl_printer
has_one
document_printer
has_one
location
has_one
printers
has_many
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

Relationships
printer_client
has_one
printer
has_one
printable
has_one
Polymorphic.
Filters

id, printer_client_id, created_at

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}

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

Read only
Array of quotes

success

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

* delivery_address
object

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

price
integer

The total price of the items

* weight
integer

Weight for the quote.

* weight_unit
enum

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

height
integer

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

length
integer

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

width
integer

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
integer

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

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,
      "include_hidden": null,
      "is_return": null,
      "additional_attributes": null,
      "filter_by_currency": null
    },
    "meta": {
      "copyright": "© 2019 Webshipper ApS"
    }
  }
}

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

pdf_download_url

xml_download_url

csv_download_url

json_download_url

xlsx_download_url

failed
boolean

order_ids

Relationships
report_type
has_one
carrier
has_one
print_jobs
has_many
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

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

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}

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

True if quote was successful

* carrier_id
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_date
datetime

ISO 8601 formatted

* packages
array

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

* delivery_address
object

Delivery address for the quote

* sender_address
object

Sender address for the quote

services
array

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
  • country_combinations
  • barcode_requirement
  • waybill_requirement
  • booking_quote_info

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

Filters

id

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

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 they cannot be modified. 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.

Attributes
* reference
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
array

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

* delivery_address
object

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

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

drop_point

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

tracking_links

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

Setting this attribute to false when creating a shipment will delay creating the booking with the carrier. This is the only field that can be updated and can only be changed from false to true. Defaults to: true

test_mode
boolean

dutiable
boolean

created_at
datetime

Read only
The time when the resource was created

Relationships
carrier
has_one
order
has_one
shipping_rate
has_one
printer_client
has_one
mail_template
has_one
pickup
has_one
labels
has_many
documents
has_many
edis
has_many
Filters

id, reference, sorting_id, created_at, updated_at, delivery_address, carrier, free_text, has_pickup

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
PATCH
https://<account name>.api.webshipper.io/v2/shipments/{id}
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",
          "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"
            }
          ],
          "dimensions": {
            "id": null,
            "package_id": 5634,
            "height": 15,
            "width": 15,
            "length": 15,
            "created_at": null,
            "updated_at": null,
            "unit": "cm"
          },
          "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,
              "discounted_unit_price": 15.0,
              "additional_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
      },
      "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
      },
      "billing_address": null,
      "pickup_address": null,
      "return_address": null,
      "service_attributes": [

      ],
      "add_ons": [

      ],
      "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
    },
    "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"
        }
      },
      "mail_template": {
        "links": {
          "self": "/v2/shipments/432/relationships/mail_template",
          "related": "/v2/shipments/432/mail_template"
        }
      },
      "pickup": {
        "links": {
          "self": "/v2/shipments/432/relationships/pickup",
          "related": "/v2/shipments/432/pickup"
        }
      },
      "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"
        }
      },
      "edis": {
        "links": {
          "self": "/v2/shipments/432/relationships/edis",
          "related": "/v2/shipments/432/edis"
        }
      }
    },
    "meta": {
      "copyright": "© 2019 Webshipper ApS"
    }
  }
}
POST https://<account name>.api.webshipper.io/v2/ shipments

Create shipment for an order - shipping rate fetched from the order

{
  "data": {
    "type": "shipments",
    "relationships": {
      "order": {
        "data": {
          "type": "orders",
          "id": 2341
        }
      }
    }
  }
}
POST https://<account name>.api.webshipper.io/v2/ shipments

Partially send an order

{
  "data": {
    "type": "shipments",
    "attributes": {
      "packages": [
        {
          "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 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": [
        {
          "weight": 100,
          "weight_unit": "g",
          "dimensions": {
            "unit": "cm",
            "height": 15,
            "width": 15,
            "length": 15
          }
        }
      ]
    },
    "relationships": {
      "shipping_rate": {
        "data": {
          "type": "shipping_rates",
          "id": 234
        }
      }
    }
  }
}

Shipping Address

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

Attributes
* att_contact
string

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

* company_name
string

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

* address_1
string

Address line 1

address_2
string

Address line 2

* country_code
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
enum

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

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
order_channel
has_one
Filters

id, order_channel_id

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

Id of the carrier which the shipping rate belongs to

order_channel_id
integer

Id of the order channel which the shipping rate belongs to

* name
string

Name to be displayed in the e-commerce system.

* carrier_service_code
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

created_at
datetime

Read only
The time when the resource was created

click_collect
boolean

updated_at
datetime

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

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.
mail_template
has_one
regions
has_many
stores
has_many
Filters

id

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
float

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

* currency
string

Currency of the price

* price
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
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
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

Relationships
order_channels
has_many
Filters

id

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}

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.

description
text

Readable description of the event

location
string

latitude
float

longitude
float

tracking_number

The tracking link for this event, if availiable

event_id
string

Unique event of the id

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

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
string

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

Relationships
user_group
has_one
printer_client
has_one
printer_clients . The printer client (workstation) which the user is currently assigned to.
order_channel_accesses
has_many
carrier_accesses
has_many
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
text

Space separated list of scopes. Please see section 6 for more details regarding scopes.

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

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.

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
sold_to_address
has_one
sender_address
has_one
printer_client
has_one
shipments
has_many
documents
has_many
Filters

id

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 2** for successful requests. Other statuses (including redirects) are treated as errors.

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. Webhook payloads are formatted as JSONAPI resources similar to other resources in the API.

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

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.

enabled
boolean

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

secret
string

The secret used to sign the HMAC.

latest_error
text

The most recent error message.

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
owner
has_one
Polymorphic. The User or the Application that created the webhook
failures
has_many
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}