Stidner Shipping API

Last updated: May 24th, 2018

Setup

To start working with Stidner Shipping, you need to get your merchant credentials from your Stidner manager.

Environment

  • Live environment: https://shipping-api.stidner.com

When using "Sandbox" API key, your orders are created in test-mode.

Authentication

To create production labels and make live requests, you need to authenticate your requests using Live credentials. You can use Sandbox credentials to set up the system and try to make sample labels.

Credentials consist of Merchant ID and API Key and can be obtained in Merchant Dashboard. Sandbox API Key starts with prefix stidner_Sandbox_, Live API Key starts with prefix stidner_live_.

The Merchant ID and API Key should be used in request to every endpoint, provided as Basic HTTP-auth login and password.

Example of authenticated request:

curl -X POST \
https://shipping-api.stidner.com/api/v1/order \
-H 'authorization: Basic MTo4YWI4MmM1MC01ZDdiLTExZTctYjJlNS0zNzhhODI1MWUxMzg=' \
-d '{ … }'

Sandbox mode

To make Sandbox mode requests, you need to specify test API Key instead of live one when making requests.

Be sure to use Sandbox mode when developing the communication between your system and Stidner Shipping, because in Sandbox mode carriers are not notified of your shipments and the real financial relations don’t start.

It is important:

  • Sandbox labels cannot be used to ship a package. If you use label created in Sandbox mode to make an actual shipment, carrier will reject your package
  • Shipping rates in Sandbox mode may differ from actual rates in Live mode
  • Shipment numbers, created in Sandbox mode are untrackable

General endpoints

The three main endpoints in shipping cycle allow to create order, create a shipment package for that order and request pickup for shipment package

Create order

POST /api/v1/order

Creates Shipment Order and returns it with the following relations: Items, Addresses, Shipping Options (with Service Points and Products).

Main JSON object

Attribute Type Requirements / description
source string | null O
external_reference string | null O
order_status string R
currency string R
items array R Array of Item JSON objects
addresses array R Array of Address JSON objects
find_products boolean O If needed to import products from carriers after Order creation
find_points boolean O If needed to import service points from carriers after Order creation

Item JSON object

Name Type Requirements
uuid string | null O Here field can be provided: - UUID of item (if it is needed to update item) - Null (if it is needed to create item)
article_number string | null O
name string R
description string O
quantity integer R Integer between 1 and 1000
unit_price integer R Integer greater than 1
weight integer R Integer greater than 1
height integer | null O
length integer | null O
width integer | null O
warehouse_location string | null O
in_stock boolean | null O

Items create/update scheme is the following. If UUID is provided in item object, and it is not null API update sthe item with correspondent UUID. If not provided or it is null – new item iscreated. If UUID is provided but not found among existing order items – error is returned.

Address JSON object

Address fields description

For the detailed description of address fields and their requirements see the Address object section

Name Type Requirements
customer_type string R Pre-defined customer type
type string R Pre-defined address type
name string R From 1 to 255 symbols
country_code string R 2 symbols
postal_code string R From 1 to 20 symbols
city string R From 1 to 255 symbols
region string | null O From 1 to 255 symbols
address_line string R From 1 to 34 symbols
address_line_2 string | null O From 1 to 34 symbols
contact_name string R From 1 to 255 symbols
contact_phone string R From 1 to 34 symbols
contact_email string R Valid email address

Address handling scheme in order create/update request is the following. All addresses provided in request will replace the addresses in order. For example, to provide new sender address to the order, there is no need to somehow delete the address – you just need to specify the new sender address. If there is a need to remove sender address – just provide no address with type ‘sender’ in request.

There may be no more than one address of either type in request. If there is more – error will be returned.

Example request
{
  "source": null,
  "external_reference": null,
  "order_status": "completed",
  "currency": "SEK",
  "items": [
    {
      "article_number": "sku_50",
      "name": "X-box 2009",
      "description": "A gaming pod",
      "quantity": 2,
      "unit_price": 2000,
      "weight": 300
    }
  ],
  "addresses": [
    {
      "type": "sender",
      "customer_type": "person",
      "name": "Max von Sydow",
      "country_code": "SE",
      "postal_code": "62142",
      "city": "Visby",
      "address_line": "Norra Hansegatan 2B",
      "contact_name": "Max von Sydow",
      "contact_phone": "+46851972000",
      "contact_email": "max@vonsydow.com"
    },
    {
      "type": "recipient",
      "customer_type": "person",
      "name": "Liv Ullmann",
      "country_code": "SE",
      "postal_code": "62464",
      "city": "Fårösund",
      "address_line": "Mellersta Batteriet, Bunge Bungenäs",
      "contact_name": "Liv Ullmann",
      "contact_phone": "+46851972000",
      "contact_email": "liv@ullmann.com"
    }
  ]
}
Example response
{
  "data": {
    "uuid": "91dfa550-6564-11e7-a526-c3103a95d016",
    "info_complete": true,
    "external_reference": null,
    "source": "__stidner_widget",
    "order_status": "completed",
    "shipping_status": "not_shipped",
    "currency": "SEK",
    "option_uuid": null,
    "product_handle": null,
    "point_handle": null,
    "option_type_handle": null,
    "items": [
      {
        "uuid": "91e4cbd0-6564-11e7-87c9-15fd4e7fa991",
        "article_number": "sku_50",
        "name": "X-box 2009",
        "description": "A gaming pod",
        "quantity": 2,
        "unit_price": 2000,
        "weight": 300,
        "height": null,
        "length": null,
        "width": null,
        "warehouse_location": null,
        "in_stock": null
      }
    ],
    "addresses": [
      {
        "customer_type": "person",
        "type": "sender",
        "name": "Max von Sydow",
        "country_code": "SE",
        "postal_code": "62142",
        "city": "Visby",
        "region": null,
        "address_line": "Norra Hansegatan 2B",
        "address_line_2": null,
        "contact_name": "Max von Sydow",
        "contact_phone": "+46851972000",
        "contact_email": "max@vonsydow.com"
      },
      {
        "customer_type": "person",
        "type": "recipient",
        "name": "Liv Ullmann",
        "country_code": "SE",
        "postal_code": "62464",
        "city": "Fårösund",
        "region": null,
        "address_line": "Mellersta Batteriet, Bunge Bungenäs",
        "address_line_2": null,
        "contact_name": "Liv Ullmann",
        "contact_phone": "+46851972000",
        "contact_email": "liv@ullmann.com"
      }
    ],
    "options": [
      {
        "uuid": "46e700c0-656e-11e7-a6ca-1fd7215b4b7c",
        "type": "service_point",
        "carrier": "bring",
        "carrier_logo": "http://webui-merchant.loc/build/images/bring.png",
        "trackable": true,
        "products": [
          {
            "name": null,
            "handle": null,
            "price": 8600,
            "delivery_time": "2017-11-01 13:00:00",
            "delivery_time_trust_level": "low"
          }
        ],
        "service_points": [
          {
            "handle": "5349340",
            "name": "Kareby"
          }
        ]
      },
      {
        "uuid": "46e89e90-656e-11e7-a8ac-af7b4fdec8ff",
        "type": "address",
        "carrier": "dhlexpress",
        "carrier_logo": "http://webui-merchant.loc/build/images/dhlexpress-trans.png",
        "trackable": true,
        "products": [
          {
            "name": "EXPRESS WORLDWIDE",
            "handle": "P",
            "price": 14400,
            "delivery_time": "2017-11-01 13:00:00",
            "delivery_time_trust_level": "high"
          },
          {
            "name": "EXPRESS 9:00",
            "handle": "K",
            "price": 22000,
            "delivery_time": "2017-11-01 09:00:00",
            "delivery_time_trust_level": "high"
          }
        ],
        "service_points": null
      },
      {
        "uuid": "46e9ef90-656e-11e7-9dbf-51d53ef62466",
        "type": "mail",
        "carrier": "postnord_varubrev",
        "carrier_logo": "http://webui-merchant.loc/build/images/postnord-trans.png",
        "trackable": false,
        "products": [
          {
            "name": null,
            "handle": null,
            "price": 5500,
            "delivery_time": "2017-11-01 13:00:00",
            "delivery_time_trust_level": "low"
          }
        ],
        "service_points": null
      }
    ],
    "packages": [
      {
        "uuid": "e3kl3fi3f-11dd-fosdm-2bkl-62d53k9r0132",
        "direction": "shipment",
        "shipment_number": "8939492939",
        "waybill_url": "https://shipping.stidner.com/waybill/8939492939",
        "customs_invoice_url": null,
        "autoprint": false,
        "items": [
          "91e4cbd0-6564-11e7-87c9-15fd4e7fa991"
        ],
        "shipped_at": "2017-11-01 14:00:00",
        "autoprinted_at": null
      },
      {
        "uuid": "e07d7250-5bf9-11e7-bef4-dfaad8144783",
        "direction": "return",
        "shipment_number": "8939492950",
        "waybill_url": "https://shipping.stidner.com/waybill/8939492950",
        "customs_invoice_url": null,
        "autoprint": false,
        "items": [
          "91e4cbd0-6564-11e7-87c9-15fd4e7fa991"
        ],
        "shipped_at": "2017-11-01 14:00:00",
        "autoprinted_at": null
      }
    ],
    "test_mode": true,
    "created_at": "2017-07-10 11:40:27",
    "completed_at": "2017-07-10 11:40:27"
  }
}

Create package

POST /api/v1/order/{order_uuid}/package/shipment

POST /api/v1/order/{order_uuid}/package/return

POST /api/v1/order/{order_uuid}/package/shipmentreturn

Creates package bound to specified order. This is the stage in order lifecycle, when shipping labels are created.

Notes about packages:

  • package can only be created for orders with “order_status” = “completed”
  • To create package the shipping option details saved in order are used (option_uuid, product_handle, point_handle). If at the moment of package creation any of these details is not specified – Stidner Shipping API picks them from options automatically
  • there are 2 directions of package – shipment (shipping to recipient) and return (return from customer to sender)
  • if package direction is “return” and order has address of type “return” – it is used as recipient to return package. If no – address of type “sender” is used to return the package. In both cases “recipient” address is used as sender. In other words, when direction is “return”, sender and recipient are switched places.
  • You can “partially ship” order – in other words, create a package for only part of the items, and the other items ship later. The most often business-cases, when this can be necessary are when some of the items are not in stock but customer wants others to be delivered sooner, when customer ordered some of the items by mistake and doesn’t want them shipped.

Order shipping status
Order object has a shipping_status field, that is updated automatically once the package is sent. The possible values of shipping_status:
Not_shipped. When order has no packages
Partially_shipped. When order has some of the items shipped
Shipped. When order has all items shipped
You cannot update shipping status manually, it’s adjusted depending on sent packages.

Main request object

Attribute Type Description
items array O
Example request
{
  "items": [
    "71330640-5e6f-11e7-999f-efa02f974eff"
  ]
}
Example response
{
  "data": {
    "uuid": "ak32cf4-5e6f-11e7-999f-efa02f974edd",
    "package_status": "pending",
    "test_mode": false,
    "direction": "shipment",
    "carrier_handle": "bring",
    "product_handle": "PICKUP_PARCEL",
    "shipment_number": "8903749293",
    "label_url": "https://shipment.stidner.com/waybill/8903749293",
    "tracking_url": "https://tracking.stidner.com/8903749293",
    "customs_declaration_form_url": null,
    "items": [
      "71330640-5e6f-11e7-999f-efa02f974eff"
    ],
    "pickup_status": "pending",
    "pickup_identifier": null,
    "shipped_at": "2017-11-01 15:00:00"
  }
}

Request pickup

POST /api/v1/package/{package_uuid}/pickup

Requests pickup for specified Package. If Carrier, Package shipped with, doesn't support pickup or if pickup was already successfully requested - error will be returned.

Main request object

Attribute Type Description
date date R Date of pickup (in format Y-m-d)
start_time time R Start time of pickup inside specified pickup date (in format H:i)
fin_time time R Fin time of pickup inside specified pickup date (in format H:i)
Example request
{
  "date": "2018-07-12",
  "start_time": "11:00",
  "fin_time": "21:00"
}
Example response
{
  "data": {
    "uuid": "ak32cf4-5e6f-11e7-999f-efa02f974edd",
    "package_status": "pending",
    "test_mode": false,
    "direction": "shipment",
    "carrier_handle": "bring",
    "product_handle": "PICKUP_PARCEL",
    "shipment_number": "8903749293",
    "label_url": "https://shipment.stidner.com/waybill/8903749293",
    "tracking_url": "https://tracking.stidner.com/8903749293",
    "customs_declaration_form_url": null,
    "items": [
      "71330640-5e6f-11e7-999f-efa02f974eff"
    ],
    "pickup_status": "pending",
    "pickup_identifier": null,
    "shipped_at": "2017-11-01 15:00:00"
  }
}

Order endpoints

Order get

GET /api/v1/order/{order_uuid}

Returns Shipment Order and returns it with the following relations: Items, Addresses, Shipping Options (with Service Points and Products), Packages.

Example response
{
  "data": {
    "uuid": "91dfa550-6564-11e7-a526-c3103a95d016",
    "info_complete": true,
    "external_reference": null,
    "source": "__stidner_widget",
    "order_status": "completed",
    "shipping_status": "not_shipped",
    "currency": "SEK",
    "option_uuid": null,
    "product_handle": null,
    "point_handle": null,
    "option_type_handle": null,
    "items": [
      {
        "uuid": "91e4cbd0-6564-11e7-87c9-15fd4e7fa991",
        "article_number": "sku_50",
        "name": "X-box 2009",
        "description": "A gaming pod",
        "quantity": 2,
        "unit_price": 2000,
        "weight": 300,
        "height": null,
        "length": null,
        "width": null,
        "warehouse_location": null,
        "in_stock": null
      }
    ],
    "addresses": [
      {
        "customer_type": "person",
        "type": "sender",
        "name": "Max von Sydow",
        "country_code": "SE",
        "postal_code": "62142",
        "city": "Visby",
        "region": null,
        "address_line": "Norra Hansegatan 2B",
        "address_line_2": null,
        "contact_name": "Max von Sydow",
        "contact_phone": "+46851972000",
        "contact_email": "max@vonsydow.com"
      },
      {
        "customer_type": "person",
        "type": "recipient",
        "name": "Liv Ullmann",
        "country_code": "SE",
        "postal_code": "62464",
        "city": "Fårösund",
        "region": null,
        "address_line": "Mellersta Batteriet, Bunge Bungenäs",
        "address_line_2": null,
        "contact_name": "Liv Ullmann",
        "contact_phone": "+46851972000",
        "contact_email": "liv@ullmann.com"
      }
    ],
    "options": [
      {
        "uuid": "46e700c0-656e-11e7-a6ca-1fd7215b4b7c",
        "type": "service_point",
        "carrier": "bring",
        "carrier_logo": "http://webui-merchant.loc/build/images/bring.png",
        "trackable": true,
        "products": [
          {
            "name": null,
            "handle": null,
            "price": 8600,
            "delivery_time": "2017-11-01 13:00:00",
            "delivery_time_trust_level": "low"
          }
        ],
        "service_points": [
          {
            "handle": "5349340",
            "name": "Kareby"
          }
        ]
      },
      {
        "uuid": "46e89e90-656e-11e7-a8ac-af7b4fdec8ff",
        "type": "address",
        "carrier": "dhlexpress",
        "carrier_logo": "http://webui-merchant.loc/build/images/dhlexpress-trans.png",
        "trackable": true,
        "products": [
          {
            "name": "EXPRESS WORLDWIDE",
            "handle": "P",
            "price": 14400,
            "delivery_time": "2017-11-01 13:00:00",
            "delivery_time_trust_level": "high"
          },
          {
            "name": "EXPRESS 9:00",
            "handle": "K",
            "price": 22000,
            "delivery_time": "2017-11-01 09:00:00",
            "delivery_time_trust_level": "high"
          }
        ],
        "service_points": null
      },
      {
        "uuid": "46e9ef90-656e-11e7-9dbf-51d53ef62466",
        "type": "mail",
        "carrier": "postnord_varubrev",
        "carrier_logo": "http://webui-merchant.loc/build/images/postnord-trans.png",
        "trackable": false,
        "products": [
          {
            "name": null,
            "handle": null,
            "price": 5500,
            "delivery_time": "2017-11-01 13:00:00",
            "delivery_time_trust_level": "low"
          }
        ],
        "service_points": null
      }
    ],
    "packages": [
      {
        "uuid": "e3kl3fi3f-11dd-fosdm-2bkl-62d53k9r0132",
        "direction": "shipment",
        "shipment_number": "8939492939",
        "waybill_url": "https://shipping.stidner.com/waybill/8939492939",
        "customs_invoice_url": null,
        "autoprint": false,
        "items": [
          "91e4cbd0-6564-11e7-87c9-15fd4e7fa991"
        ],
        "shipped_at": "2017-11-01 14:00:00",
        "autoprinted_at": null
      },
      {
        "uuid": "e07d7250-5bf9-11e7-bef4-dfaad8144783",
        "direction": "return",
        "shipment_number": "8939492950",
        "waybill_url": "https://shipping.stidner.com/waybill/8939492950",
        "customs_invoice_url": null,
        "autoprint": false,
        "items": [
          "91e4cbd0-6564-11e7-87c9-15fd4e7fa991"
        ],
        "shipped_at": "2017-11-01 14:00:00",
        "autoprinted_at": null
      }
    ],
    "test_mode": true,
    "created_at": "2017-07-10 11:40:27",
    "completed_at": "2017-07-10 11:40:27"
  }
}

Order update

PUT /api/v1/order/{order_uuid}

Updates order object with the provided data.

Main request object

Attribute Type Description
source string | null O
external_reference string | null O
order_status string R
currency string R
option_uuid string | null R UUID of shipping option, selected to ship with. Should match UUID of one of the options in current order
product_handle string | null R Handle of product to ship with, if there are multiple products in shipping option
point_handle string | null R UUID of shipping option, selected to ship with. Should match UUID of one of the options in current order
option_type_handle string | null R UUID of shipping option, selected to ship with. Should match UUID of one of the options in current order
items array R Array of Item request objects
addresses array R Array of Address request objects
find_products boolean O If needed to import products from carriers after create
find_points boolean O If needed to import service points from carriers after create
Example request
{
  "source": null,
  "external_reference": null,
  "order_status": "completed",
  "currency": "SEK",
  "option_uuid": null,
  "product_handle": null,
  "point_handle": null,
  "option_type_handle": null,
  "items": [
    {
      "article_number": "sku_50",
      "name": "X-box 2009",
      "description": "A gaming pod",
      "quantity": 2,
      "unit_price": 2000,
      "weight": 300
    }
  ],
  "addresses": [
    {
      "type": "sender",
      "customer_type": "person",
      "name": "Max von Sydow",
      "country_code": "SE",
      "postal_code": "62142",
      "city": "Visby",
      "address_line": "Norra Hansegatan 2B",
      "contact_name": "Max von Sydow",
      "contact_phone": "+46851972000",
      "contact_email": "max@vonsydow.com"
    },
    {
      "type": "recipient",
      "customer_type": "person",
      "name": "Liv Ullmann",
      "country_code": "SE",
      "postal_code": "62464",
      "city": "Fårösund",
      "address_line": "Mellersta Batteriet, Bunge Bungenäs",
      "contact_name": "Liv Ullmann",
      "contact_phone": "+46851972000",
      "contact_email": "liv@ullmann.com"
    }
  ]
}
Example response
{
  "data": {
    "uuid": "91dfa550-6564-11e7-a526-c3103a95d016",
    "info_complete": true,
    "external_reference": null,
    "source": "__stidner_widget",
    "order_status": "completed",
    "shipping_status": "not_shipped",
    "currency": "SEK",
    "option_uuid": null,
    "product_handle": null,
    "point_handle": null,
    "option_type_handle": null,
    "items": [
      {
        "uuid": "91e4cbd0-6564-11e7-87c9-15fd4e7fa991",
        "article_number": "sku_50",
        "name": "X-box 2009",
        "description": "A gaming pod",
        "quantity": 2,
        "unit_price": 2000,
        "weight": 300,
        "height": null,
        "length": null,
        "width": null,
        "warehouse_location": null,
        "in_stock": null
      }
    ],
    "addresses": [
      {
        "customer_type": "person",
        "type": "sender",
        "name": "Max von Sydow",
        "country_code": "SE",
        "postal_code": "62142",
        "city": "Visby",
        "region": null,
        "address_line": "Norra Hansegatan 2B",
        "address_line_2": null,
        "contact_name": "Max von Sydow",
        "contact_phone": "+46851972000",
        "contact_email": "max@vonsydow.com"
      },
      {
        "customer_type": "person",
        "type": "recipient",
        "name": "Liv Ullmann",
        "country_code": "SE",
        "postal_code": "62464",
        "city": "Fårösund",
        "region": null,
        "address_line": "Mellersta Batteriet, Bunge Bungenäs",
        "address_line_2": null,
        "contact_name": "Liv Ullmann",
        "contact_phone": "+46851972000",
        "contact_email": "liv@ullmann.com"
      }
    ],
    "options": [
      {
        "uuid": "46e700c0-656e-11e7-a6ca-1fd7215b4b7c",
        "type": "service_point",
        "carrier": "bring",
        "carrier_logo": "http://webui-merchant.loc/build/images/bring.png",
        "trackable": true,
        "products": [
          {
            "name": null,
            "handle": null,
            "price": 8600,
            "delivery_time": "2017-11-01 13:00:00",
            "delivery_time_trust_level": "low"
          }
        ],
        "service_points": [
          {
            "handle": "5349340",
            "name": "Kareby"
          }
        ]
      },
      {
        "uuid": "46e89e90-656e-11e7-a8ac-af7b4fdec8ff",
        "type": "address",
        "carrier": "dhlexpress",
        "carrier_logo": "http://webui-merchant.loc/build/images/dhlexpress-trans.png",
        "trackable": true,
        "products": [
          {
            "name": "EXPRESS WORLDWIDE",
            "handle": "P",
            "price": 14400,
            "delivery_time": "2017-11-01 13:00:00",
            "delivery_time_trust_level": "high"
          },
          {
            "name": "EXPRESS 9:00",
            "handle": "K",
            "price": 22000,
            "delivery_time": "2017-11-01 09:00:00",
            "delivery_time_trust_level": "high"
          }
        ],
        "service_points": null
      },
      {
        "uuid": "46e9ef90-656e-11e7-9dbf-51d53ef62466",
        "type": "mail",
        "carrier": "postnord_varubrev",
        "carrier_logo": "http://webui-merchant.loc/build/images/postnord-trans.png",
        "trackable": false,
        "products": [
          {
            "name": null,
            "handle": null,
            "price": 5500,
            "delivery_time": "2017-11-01 13:00:00",
            "delivery_time_trust_level": "low"
          }
        ],
        "service_points": null
      }
    ],
    "packages": [
      {
        "uuid": "e3kl3fi3f-11dd-fosdm-2bkl-62d53k9r0132",
        "direction": "shipment",
        "shipment_number": "8939492939",
        "waybill_url": "https://shipping.stidner.com/waybill/8939492939",
        "customs_invoice_url": null,
        "autoprint": false,
        "items": [
          "91e4cbd0-6564-11e7-87c9-15fd4e7fa991"
        ],
        "shipped_at": "2017-11-01 14:00:00",
        "autoprinted_at": null
      },
      {
        "uuid": "e07d7250-5bf9-11e7-bef4-dfaad8144783",
        "direction": "return",
        "shipment_number": "8939492950",
        "waybill_url": "https://shipping.stidner.com/waybill/8939492950",
        "customs_invoice_url": null,
        "autoprint": false,
        "items": [
          "91e4cbd0-6564-11e7-87c9-15fd4e7fa991"
        ],
        "shipped_at": "2017-11-01 14:00:00",
        "autoprinted_at": null
      }
    ],
    "test_mode": true,
    "created_at": "2017-07-10 11:40:27",
    "completed_at": "2017-07-10 11:40:27"
  }
}

Orders collection

POST /api/v1/order/get

Returns paginated list of orders, that matches filter criteria.

Main request object

Attribute Type Description
filter array R Array of options to filter results.
pagination_limit integer O If none is given - the default value (20) will be used. There is no way to get orders list without pagination due to big amount of data per each order.
order_direction string O Orders are sorted by created_at date. Possible values are asc and desc. If none is given - the default value is desc.

Filter request object

Attribute Type Description
order_status array O Array of order statuses. Possible values: created, completed.
uuid string O UUID of order
shipping_status array O Array of shipping statuses. Possible values: not_shipped, partially_shipped, shipped.
currency string O 3-char currency code
items array O
    items.article_number string O
    items.name string O
    items.weight array O
        items.weight.from integer O
        items.weight.to integer O
addresses array O Array of Address filter request objects. Possible keys: sender, recipient, return.
search string O Search string, the search is performed on all text fields with LIKE %% function

Address filter request object

Attribute Type Description
customer_type string O Possible value: person, company.
country_code string O
Example request
{
  "filter": {
    "order_status": [
      "completed"
    ],
    "uuid": null,
    "shipping_status": [],
    "currency": null,
    "items": {
      "article_number": null,
      "name": null,
      "weight": {
        "from": null,
        "to": null
      }
    },
    "addresses": {
      "sender": {
        "customer_type": null,
        "country_code": null
      },
      "recipient": {
        "customer_type": null,
        "country_code": null
      },
      "return": {
        "customer_type": null,
        "country_code": null
      }
    },
    "search": null
  },
  "pagination_limit": 10,
  "order_direction": "desc"
}
Example response
{
  "data": [
    {
      "uuid": "b7d649f0-7770-11e7-8e84-5b1945c783a0",
      "widget_url": "http://shipping-widget.loc/order/b7d649f0-7770-11e7-8e84-5b1945c783a0",
      "widget_embed": "<script src=\"http://shipping-widget.loc/js/integration.js?v=100\" type=\"text/javascript\"></script>\n<iframe src=\"http://shipping-widget.loc/order/b7d649f0-7770-11e7-8e84-5b1945c783a0\" id=\"__stidner_shipping_iframe\" width=\"375\" frameborder=\"0\"></iframe>",
      "info_complete": true,
      "external_reference": null,
      "payment_reference": null,
      "source": null,
      "payment_system": null,
      "order_status": "completed",
      "shipping_status": "not_shipped",
      "currency": "SEK",
      "option_uuid": null,
      "product_handle": null,
      "point_handle": null,
      "option_type_handle": null,
      "shipping_price": null,
      "items": [
        {
          "uuid": "b7da21c0-7770-11e7-a7ec-d1df32628630",
          "article_number": "sku_50",
          "name": "X-box 2009",
          "description": "A gaming pod",
          "quantity": 2,
          "unit_price": 2000,
          "weight": 300,
          "height": null,
          "length": null,
          "width": null,
          "warehouse_location": null,
          "in_stock": null
        }
      ],
      "addresses": [
        {
          "info_complete": true,
          "customer_type": "person",
          "type": "sender",
          "name": "Max von Sydow",
          "country_code": "SE",
          "postal_code": "62142",
          "city": "Visby",
          "region": null,
          "address_line": "Norra Hansegatan 2B",
          "address_line_2": null,
          "contact_name": "Max von Sydow",
          "contact_phone": "+46851972000",
          "contact_email": "max@vonsydow.com",
          "latitude": 57.6373495,
          "longitude": 18.3054411
        },
        {
          "info_complete": true,
          "customer_type": "person",
          "type": "recipient",
          "name": "Liv Ullmann",
          "country_code": "SE",
          "postal_code": "62464",
          "city": "Fårösund",
          "region": null,
          "address_line": "Mellersta Batteriet, Bunge Bungenäs",
          "address_line_2": null,
          "contact_name": "Liv Ullmann",
          "contact_phone": "+46851972000",
          "contact_email": "liv@ullmann.com",
          "latitude": null,
          "longitude": null
        }
      ],
      "options": [],
      "packages": [],
      "created_at": "2017-08-02 13:52:46",
      "completed_at": "2017-08-02 12:52:46"
    },
    {
      "uuid": "ad6df130-7770-11e7-9e78-dd6286b5ea6d",
      "widget_url": "http://shipping-widget.loc/order/ad6df130-7770-11e7-9e78-dd6286b5ea6d",
      "widget_embed": "<script src=\"http://shipping-widget.loc/js/integration.js?v=13\" type=\"text/javascript\"></script>\n<iframe src=\"http://shipping-widget.loc/order/ad6df130-7770-11e7-9e78-dd6286b5ea6d\" id=\"__stidner_shipping_iframe\" width=\"375\" frameborder=\"0\"></iframe>",
      "info_complete": true,
      "external_reference": null,
      "payment_reference": null,
      "source": null,
      "payment_system": null,
      "order_status": "completed",
      "shipping_status": "not_shipped",
      "currency": "SEK",
      "option_uuid": null,
      "product_handle": null,
      "point_handle": null,
      "option_type_handle": null,
      "shipping_price": null,
      "items": [
        {
          "uuid": "ad78b380-7770-11e7-9b6a-514b299cd566",
          "article_number": "sku_50",
          "name": "X-box 2009",
          "description": "A gaming pod",
          "quantity": 2,
          "unit_price": 2000,
          "weight": 300,
          "height": null,
          "length": null,
          "width": null,
          "warehouse_location": null,
          "in_stock": null
        }
      ],
      "addresses": [
        {
          "info_complete": true,
          "customer_type": "person",
          "type": "sender",
          "name": "Max von Sydow",
          "country_code": "SE",
          "postal_code": "62142",
          "city": "Visby",
          "region": null,
          "address_line": "Norra Hansegatan 2B",
          "address_line_2": null,
          "contact_name": "Max von Sydow",
          "contact_phone": "+46851972000",
          "contact_email": "max@vonsydow.com",
          "latitude": 57.6373495,
          "longitude": 18.3054411
        },
        {
          "info_complete": true,
          "customer_type": "person",
          "type": "recipient",
          "name": "Liv Ullmann",
          "country_code": "SE",
          "postal_code": "62464",
          "city": "Fårösund",
          "region": null,
          "address_line": "Mellersta Batteriet, Bunge Bungenäs",
          "address_line_2": null,
          "contact_name": "Liv Ullmann",
          "contact_phone": "+46851972000",
          "contact_email": "liv@ullmann.com",
          "latitude": null,
          "longitude": null
        }
      ],
      "options": [
        {
          "uuid": "adc4a060-7770-11e7-8a04-a90f2143fd65",
          "type": "service_point",
          "carrier": "bring",
          "carrier_logo": "https://cdn.stidner.com/images/carriers/bring.png",
          "products": [
            {
              "handle": null,
              "name": null,
              "price": 8500,
              "delivery_time": "2017-08-03 13:00:00"
            }
          ],
          "service_points": [
            {
              "handle": "877829",
              "name": "Time Fårösund",
              "distance": 2300,
              "country_code": "SE",
              "postal_code": "62462",
              "city": "Fårösund",
              "address_line": "Fårövägen 27",
              "latitude": 57.8612588387,
              "longitude": 19.0539539416,
              "operation_hours": [
                {
                  "sort": 1,
                  "from": "07:00",
                  "to": "20:00",
                  "days": "Monday - Friday"
                },
                {
                  "sort": 2,
                  "from": "08:00",
                  "to": "19:00",
                  "days": "Saturday"
                },
                {
                  "sort": 3,
                  "from": "09:00",
                  "to": "19:00",
                  "days": "Sunday"
                }
              ]
            },
            {
              "handle": "878278",
              "name": "COOP Konsum Lärbro",
              "distance": 19300,
              "country_code": "SE",
              "postal_code": "62452",
              "city": "Lärbro",
              "address_line": "Lindvägen 1",
              "latitude": 57.7857118872,
              "longitude": 18.7890963391,
              "operation_hours": [
                {
                  "sort": 1,
                  "from": "09:00",
                  "to": "20:00",
                  "days": "Monday - Sunday"
                }
              ]
            },
            {
              "handle": "878514",
              "name": "Coop Konsum Slite",
              "distance": 29200,
              "country_code": "SE",
              "postal_code": "62448",
              "city": "Slite",
              "address_line": "Tullhagsplan 5",
              "latitude": 57.7043745825,
              "longitude": 18.8033610264,
              "operation_hours": [
                {
                  "sort": 1,
                  "from": "08:00",
                  "to": "21:00",
                  "days": "Monday - Saturday"
                },
                {
                  "sort": 2,
                  "from": "10:00",
                  "to": "21:00",
                  "days": "Sunday"
                }
              ]
            }
          ],
          "trackable": true
        },
        {
          "uuid": "adc70470-7770-11e7-8971-a9549fb7b4ba",
          "type": "service_point",
          "carrier": "dhl",
          "carrier_logo": "https://cdn.stidner.com/images/carriers/dhl.png",
          "products": [
            {
              "handle": null,
              "name": null,
              "price": 5600,
              "delivery_time": "2017-08-03 12:00:00"
            }
          ],
          "service_points": [
            {
              "handle": "SE-744500",
              "name": "TIME FÅRÖSUND",
              "distance": 2294,
              "country_code": "SE",
              "postal_code": "62462",
              "city": "FÅRÖSUND",
              "address_line": "FÅRÖVÄGEN 27",
              "latitude": 57.8612588387,
              "longitude": 19.0539539416,
              "operation_hours": [
                {
                  "sort": 1,
                  "from": "07:00",
                  "to": "20:00",
                  "days": "Monday - Friday"
                },
                {
                  "sort": 2,
                  "from": "08:00",
                  "to": "19:00",
                  "days": "Saturday"
                },
                {
                  "sort": 3,
                  "from": "09:00",
                  "to": "19:00",
                  "days": "Sunday"
                }
              ]
            },
            {
              "handle": "SE-671800",
              "name": "COOP KONSUM LÄRBRO",
              "distance": 15762,
              "country_code": "SE",
              "postal_code": "62452",
              "city": "LÄRBRO",
              "address_line": "LINDVÄGEN 1",
              "latitude": 57.7857118872,
              "longitude": 18.7890963391,
              "operation_hours": [
                {
                  "sort": 1,
                  "from": "09:00",
                  "to": "20:00",
                  "days": "Monday - Sunday"
                }
              ]
            },
            {
              "handle": "SE-672200",
              "name": "COOP KONSUM SLITE",
              "distance": 20440,
              "country_code": "SE",
              "postal_code": "62448",
              "city": "SLITE",
              "address_line": "TULLHAGSPLAN 5",
              "latitude": 57.7043745825,
              "longitude": 18.8033610264,
              "operation_hours": [
                {
                  "sort": 1,
                  "from": "08:00",
                  "to": "21:00",
                  "days": "Monday - Saturday"
                },
                {
                  "sort": 2,
                  "from": "10:00",
                  "to": "21:00",
                  "days": "Sunday"
                }
              ]
            }
          ],
          "trackable": true
        },
        {
          "uuid": "adc79be0-7770-11e7-9547-d9568540ec04",
          "type": "address",
          "carrier": "dhlexpress",
          "carrier_logo": "https://cdn.stidner.com/images/carriers/dhlexpress.png",
          "products": [
            {
              "handle": "N",
              "name": "EXPRESS DOMESTIC",
              "price": 41393,
              "delivery_time": "2017-08-03 23:59:00"
            }
          ],
          "service_points": [],
          "trackable": true
        },
        {
          "uuid": "adc840d0-7770-11e7-adac-d767b9efdf33",
          "type": "service_point",
          "carrier": "postnord_mypack",
          "carrier_logo": "https://cdn.stidner.com/images/carriers/postnord.png",
          "products": [
            {
              "handle": null,
              "name": null,
              "price": 15900,
              "delivery_time": "2017-08-03 09:00:00"
            }
          ],
          "service_points": [
            {
              "handle": "690768",
              "name": "ICA Supermarket Bungehallen",
              "distance": 3700,
              "country_code": "SE",
              "postal_code": "62462",
              "city": "FÅRÖSUND",
              "address_line": "Fårövägen 10",
              "latitude": 57.8632249,
              "longitude": 19.0545915,
              "operation_hours": [
                {
                  "sort": 1,
                  "from": "08:00",
                  "to": "20:00",
                  "days": "Monday"
                },
                {
                  "sort": 2,
                  "from": "08:00",
                  "to": "20:00",
                  "days": "Tuesday"
                },
                {
                  "sort": 3,
                  "from": "08:00",
                  "to": "20:00",
                  "days": "Wednesday"
                },
                {
                  "sort": 4,
                  "from": "08:00",
                  "to": "20:00",
                  "days": "Thursday"
                },
                {
                  "sort": 5,
                  "from": "08:00",
                  "to": "20:00",
                  "days": "Friday"
                },
                {
                  "sort": 6,
                  "from": "08:00",
                  "to": "20:00",
                  "days": "Saturday"
                },
                {
                  "sort": 7,
                  "from": "08:00",
                  "to": "20:00",
                  "days": "Sunday"
                }
              ]
            },
            {
              "handle": "690778",
              "name": "Coop Konsum Lärbro",
              "distance": 20859,
              "country_code": "SE",
              "postal_code": "62452",
              "city": "LÄRBRO",
              "address_line": "Korsbyvägen 23",
              "latitude": 57.7846775,
              "longitude": 18.7888874,
              "operation_hours": [
                {
                  "sort": 1,
                  "from": "09:00",
                  "to": "20:00",
                  "days": "Monday"
                },
                {
                  "sort": 2,
                  "from": "09:00",
                  "to": "20:00",
                  "days": "Tuesday"
                },
                {
                  "sort": 3,
                  "from": "09:00",
                  "to": "20:00",
                  "days": "Wednesday"
                },
                {
                  "sort": 4,
                  "from": "09:00",
                  "to": "20:00",
                  "days": "Thursday"
                },
                {
                  "sort": 5,
                  "from": "09:00",
                  "to": "20:00",
                  "days": "Friday"
                },
                {
                  "sort": 6,
                  "from": "09:00",
                  "to": "20:00",
                  "days": "Saturday"
                },
                {
                  "sort": 7,
                  "from": "09:00",
                  "to": "20:00",
                  "days": "Sunday"
                }
              ]
            },
            {
              "handle": "690766",
              "name": "Coop Konsum Slite",
              "distance": 30320,
              "country_code": "SE",
              "postal_code": "62448",
              "city": "SLITE",
              "address_line": "Tullhagsplan 5",
              "latitude": 57.7044217,
              "longitude": 18.8034952,
              "operation_hours": [
                {
                  "sort": 1,
                  "from": "08:00",
                  "to": "21:00",
                  "days": "Monday"
                },
                {
                  "sort": 2,
                  "from": "08:00",
                  "to": "21:00",
                  "days": "Tuesday"
                },
                {
                  "sort": 3,
                  "from": "08:00",
                  "to": "21:00",
                  "days": "Wednesday"
                },
                {
                  "sort": 4,
                  "from": "08:00",
                  "to": "21:00",
                  "days": "Thursday"
                },
                {
                  "sort": 5,
                  "from": "08:00",
                  "to": "21:00",
                  "days": "Friday"
                },
                {
                  "sort": 6,
                  "from": "08:00",
                  "to": "21:00",
                  "days": "Saturday"
                },
                {
                  "sort": 7,
                  "from": "10:00",
                  "to": "21:00",
                  "days": "Sunday"
                }
              ]
            }
          ],
          "trackable": true
        },
        {
          "uuid": "adcec520-7770-11e7-91f4-19e8c68f1b6a",
          "type": "mail",
          "carrier": "postnord_varubrev",
          "carrier_logo": "https://cdn.stidner.com/images/carriers/postnord.png",
          "products": [
            {
              "handle": null,
              "name": null,
              "price": 4100,
              "delivery_time": "2017-08-03 14:00:00"
            }
          ],
          "service_points": [],
          "trackable": false
        },
        {
          "uuid": "adcff1b0-7770-11e7-86cc-f9559824b618",
          "type": "store_pickup",
          "carrier": "store_pickup",
          "carrier_logo": null,
          "products": [
            {
              "handle": null,
              "name": null,
              "price": 0,
              "delivery_time": "2017-08-03 08:00:00"
            }
          ],
          "service_points": [
            {
              "handle": null,
              "name": "Max von Sydow",
              "distance": null,
              "country_code": "SE",
              "postal_code": "62142",
              "city": "Visby",
              "address_line": "Norra Hansegatan 2B",
              "latitude": 57.6373495,
              "longitude": 18.3054411,
              "operation_hours": null
            }
          ],
          "trackable": true
        }
      ],
      "packages": [],
      "created_at": "2017-08-02 13:52:28",
      "completed_at": "2017-08-02 12:52:28"
    },
    {
      "uuid": "a856c020-7770-11e7-be70-bdb64ee7a036",
      "widget_url": "http://shipping-widget.loc/order/a856c020-7770-11e7-be70-bdb64ee7a036",
      "widget_embed": "<script src=\"http://shipping-widget.loc/js/integration.js?v=28\" type=\"text/javascript\"></script>\n<iframe src=\"http://shipping-widget.loc/order/a856c020-7770-11e7-be70-bdb64ee7a036\" id=\"__stidner_shipping_iframe\" width=\"375\" frameborder=\"0\"></iframe>",
      "info_complete": true,
      "external_reference": null,
      "payment_reference": null,
      "source": null,
      "payment_system": null,
      "order_status": "completed",
      "shipping_status": "not_shipped",
      "currency": "SEK",
      "option_uuid": null,
      "product_handle": null,
      "point_handle": null,
      "option_type_handle": null,
      "shipping_price": null,
      "items": [
        {
          "uuid": "a85e71d0-7770-11e7-a3b3-0f95c83e3f7e",
          "article_number": "sku_50",
          "name": "X-box 2009",
          "description": "A gaming pod",
          "quantity": 2,
          "unit_price": 2000,
          "weight": 300,
          "height": null,
          "length": null,
          "width": null,
          "warehouse_location": null,
          "in_stock": null
        }
      ],
      "addresses": [
        {
          "info_complete": true,
          "customer_type": "person",
          "type": "sender",
          "name": "Max von Sydow",
          "country_code": "SE",
          "postal_code": "62142",
          "city": "Visby",
          "region": null,
          "address_line": "Norra Hansegatan 2B",
          "address_line_2": null,
          "contact_name": "Max von Sydow",
          "contact_phone": "+46851972000",
          "contact_email": "max@vonsydow.com",
          "latitude": 57.6373495,
          "longitude": 18.3054411
        },
        {
          "info_complete": true,
          "customer_type": "person",
          "type": "recipient",
          "name": "Liv Ullmann",
          "country_code": "SE",
          "postal_code": "62464",
          "city": "Fårösund",
          "region": null,
          "address_line": "Mellersta Batteriet, Bunge Bungenäs",
          "address_line_2": null,
          "contact_name": "Liv Ullmann",
          "contact_phone": "+46851972000",
          "contact_email": "liv@ullmann.com",
          "latitude": null,
          "longitude": null
        }
      ],
      "options": [],
      "packages": [],
      "created_at": "2017-08-02 13:52:20",
      "completed_at": "2017-08-02 12:52:20"
    }
  ],
  "meta": {
    "pagination": {
      "total": 3,
      "count": 3,
      "per_page": 10,
      "current_page": 1,
      "total_pages": 1,
      "links": []
    }
  }
}

Merchant endpoints

Merchant get

GET /api/v1/merchant

Gets information about current Merchant.

Example response
{
  "data": {
    "id": 1,
    "name": "Stidner Complete AB",
    "type": "AB",
    "organisation_number": "333333333333",
    "vat_number": "SE333333333333",
    "api_key_live": "8ab82c50-5d7b-11e7-b2e5-378a8251e138",
    "api_key_sandbox": "ef0v4p1a-239k-29oz-9dbf-51d53ef62466",
    "active": true,
    "addresses": [
      {
        "customer_type": "business",
        "type": "sender",
        "name": "Stidner Complete AB",
        "country_code": "SE",
        "postal_code": "191023",
        "city": "St. Petersburg",
        "region": null,
        "address_line": "Fontanka 77, 25",
        "address_line_2": null,
        "contact_name": "Anton Vorozheev",
        "contact_phone": "+79119590589",
        "contact_email": "mail@stidner.com"
      },
      {
        "customer_type": "business",
        "type": "return",
        "name": "Stidner Complete AB",
        "country_code": "SE",
        "postal_code": "191023",
        "city": "St. Petersburg",
        "region": null,
        "address_line": "Fontanka 77, 25",
        "address_line_2": null,
        "contact_name": "Anton Vorozheev",
        "contact_phone": "+79119590589",
        "contact_email": "mail@stidner.com"
      }
    ],
    "created_at": "2017-06-30 10:04:44"
  }
}

Merchant update

PUT /api/v1/merchant

Updates information about current Merchant.

Example request
{
  "addresses": [
    {
      "customer_type": "business",
      "type": "sender",
      "name": "Stidner Complete AB",
      "country_code": "BY",
      "postal_code": "210001",
      "city": "Malmo",
      "address_line": "Fontanka 77, 25",
      "contact_name": "Anton Vorozheev",
      "contact_phone": "+79119590589",
      "contact_email": "mail@stidner.com"
    },
    {
      "customer_type": "business",
      "type": "return",
      "name": "Stidner Complete AB",
      "country_code": "PL",
      "postal_code": "191023",
      "city": "St. Petersburg",
      "address_line": "Fontanka 77, 25",
      "contact_name": "Anton Vorozheev",
      "contact_phone": "+79119590589",
      "contact_email": "mail@stidner.com"
    }
  ]
}
Example response
{
  "data": {
    "id": 1,
    "name": "Stidner Complete AB",
    "type": "AB",
    "organisation_number": "333333333333",
    "vat_number": "SE333333333333",
    "api_key_live": "8ab82c50-5d7b-11e7-b2e5-378a8251e138",
    "api_key_sandbox": "ef0v4p1a-239k-29oz-9dbf-51d53ef62466",
    "active": true,
    "addresses": [
      {
        "customer_type": "business",
        "type": "sender",
        "name": "Stidner Complete AB",
        "country_code": "SE",
        "postal_code": "191023",
        "city": "St. Petersburg",
        "region": null,
        "address_line": "Fontanka 77, 25",
        "address_line_2": null,
        "contact_name": "Anton Vorozheev",
        "contact_phone": "+79119590589",
        "contact_email": "mail@stidner.com"
      },
      {
        "customer_type": "business",
        "type": "return",
        "name": "Stidner Complete AB",
        "country_code": "SE",
        "postal_code": "191023",
        "city": "St. Petersburg",
        "region": null,
        "address_line": "Fontanka 77, 25",
        "address_line_2": null,
        "contact_name": "Anton Vorozheev",
        "contact_phone": "+79119590589",
        "contact_email": "mail@stidner.com"
      }
    ],
    "created_at": "2017-06-30 10:04:44"
  }
}

Errors

If some error happens during request, API returns error JSON object, that contains as much details about what happened, as we may provide. That information should be enough to determine error origing and to react both application-wise and user-wise.

Error JSON object
Attribute Type Description
error string General error code, that shows the main reason of why the request failed. All possible error codes are listed in Error Codes section. There may be only one error code per error.
reasons array Array of more detailed information on error. For example, for error 'auth failed' reasons array will contain the exact reason of it (for example, not active credentials). All possible reason codes are listed in Reason Codes section. There may be several reasons per error.
messages array Array of input-related message. Usually messages are returned with the validation error and contain array of attributes and the validation messages for them, so they can be either just taken to consideration or displayed to application user.
flags array Different internal Stidner data, that may be useful for helping to trace your request, in case you contact our support about an error.
Error JSON example
{
  "error": "e_AUTH_FAILED",
  "reasons": [
    "r_MERCHANT_NOT_ACTIVATED"
  ],
  "messages": [

  ],
  "flags": [
    "7138a890-5e6f-11e7-9578-950f7e7c481d"
  ]
}
Error codes
Code Description Possible reason codes
e_AUTH_FAILED When authentication fails for any reason r_MERCHANT_CREDENTIALS_MISSING_IN_REQUEST
r_MERCHANT_NOT_FOUND
r_MERCHANT_NOT_ACTIVATED
e_ENDPOINT_NOT_FOUND When the request hits the endpoint, that is not implemented in API
e_METHOD_NOT_ALLOWED When the request hits the correct endpoint with the wrong method
e_USER_NOT_FOUND
e_ORDER_NOT_FOUND When any action with Order UUID is performed (get Order, update Order, import Options, create Package), and Order with specified UUID is not found
e_PACKAGE_NOT_FOUND
e_NOT_VALID_MODE
e_BAD_REQUEST When some unidentified error happened. We try not to use this error code at all, but if you see it - that means the error, that even we didn't expect, happeden. Please, contact us about such errors, so we can adjust our API to respond with the proper code.
Reason codes
Code Description Is returned with error
r_MERCHANT_CREDENTIALS_MISSING_IN_REQUEST Basic HTTP authentication lacks either Merchant ID, or API Key e_AUTH_FAILED
r_MERCHANT_NOT_FOUND Merchant with specified ID and API Key is not found e_AUTH_FAILED
r_MERCHANT_NOT_ACTIVATED e_AUTH_FAILED