General notes

Last updated: May 17th, 2018

Lifecycle of shipment

The shipment lifecycle is split into 3 steps.

1. Creating Order

On this step the shipment data is registered in Stidner, and the possible shipping options are returned.

2. Creating Package

Specifying one of the shipment options from above with the extra attributes (service-point handle - if service-point delivery), Package is created. This is the step where merchant gets the label for the shipment. There is an option to ship only part of order, providing items uuids. The remaining items can be shipped by the separate request

3. Requesting pickup from carrier

If you need your shipment to be picked up and selected Carrier supports it, you can request pickup for th Package created on step 2.

Objects

Order

Name Type Description Readonly
uuid string String UUID of shipment order. Is autoassigned to Order on creation and cannot be changed. Is used for identifying order in any further requests. Yes
is_editable boolean Yes
order_products_ready boolean Shows if OrderProducts are ready for the. If Order is created with async = true, you will get an instant response with the order object. In that case options_ready will be false, because the options are still being grabbed in background. Yes
is_valid boolean If provided information is valid. We allow to create packages only on fully valid orders. Yes
validation_flags array | null If is_valid = false, here will be listed the flags with failed information. Yes
widget_url string URL of shipping widget Yes
widget_embed string Full code of shipping widget, ready to be embed on the page Yes
internal_reference string Short unique internal reference of Order. Yes
external_reference string Identifier of order at external Marketplace. If order was imported from external Marketplace, or if it is connected to order in external Marketplace (for example, when payment is performed in a separate system), here is specified ID of correspondent order there.
payment_reference string Reference of order in payment system
payment_system string
order_status string Status of order. Possible values are explained in Order Statuses section.
shipping_status string Status of order shipment, is auto-assigned to order after creating Package. Possible values are explained in Shipping Statuses section. Yes
return_waybills_status string Yes
items array Array of Item objects.
addresses array Array of Address objects.
currency string Currency of Order in ISO-4217 format (read more about the format). Specifying the code of currency, you state, that all prices inside the Order (item prices and further returned Shipping Option prices) are given in this currency.
locale string Language locale of Order
order_products array Array of OrderProduct objects. Yes
packages array Array of Package objects. Yes
product_uuid string | null UUID of selected OrderProduct.
point_handle string | null Handle of selected ServicePoint.
selected_services array
required_data array Yes
suggested_data array Yes
shipping_price int | null Yes
shipping_price_carrier int | null Yes
test_mode boolean Order can be created in test mode. The Package-labels of such orders cannot be used for real shipments, and also pickup is not requested on test-mode orders
notification_url string | null URL for http-notifications on any Order notable event (completed, package sent, pickup requested)
meta array | null Array of custom fields, connected to Order, it is used to store non-formalized information
extra array | null
created_at datetime Time when order was created. Yes
completed_at datetime | null Time when order was completed (when 'status' was changed to 'completed'). For not completed orders - null. Yes

Order statuses

Handle Description
pending Default status of order. It means, that order is created, but not finished yet. No packages can be created for the order in this status. The example of usage: when customer proceeded to the checkout, we make the order in 'created' status, but if customer abandons it - the order is not turned in 'completed' status.
completed The final status of order. Orders in 'completed' statuses can be placed for shipping (package creation). You should update order with 'completed' status only when you are sure, that it is finished (for example, when it's paid in any external system).

Shipping statuses

Handle Description
not_shipped No Packages are created for order.
partially_shipped Order has Packages, but not all items are shipped.
shipped Order has Packages, and all items are shipped.

You cannot manually change shipping status

Be careful, shipping status is in readonly state, it is changed automatically on Package creation. You cannot change it manually. It is designed like that to keep data integrity and prevent user-errors, that lead to the cases, when no Packages are created for the order, but the status is, for example, 'shipped'.

OrderProduct

Name Type Description Readonly
uuid string String UUID of OrderProduct. Is autoassigned and cannot be changed. Is used for specifying what OrderProduct should be used in Order for creating Package. Yes
type string Handle of delivery type. The information about the available types can be found in Delivery Types section. Yes
carrier_handle string Handle of Carrier. Yes
handle string Handle of CarrierProduct. Yes
name string Name of CarrierProduct. Yes
available_services array Array of CarrierService handles, that can be selected when shipping with this OrderProduct Yes
default_services array Array of CarrierService handles, that are selected by default when shipping with this OrderProduct and cannot be disabled Yes
price_carrier_without_tax int Yes
price_carrier_tax_amount int Yes
price_carrier_with_tax int Yes
price_merchant_without_tax int Yes
price_merchant_tax_amount int Yes
price_merchant_with_tax int Yes
delivery_time datetime Yes
delivery_time_trust_level string Yes
service_points array Array of Service Point objects (for OrderProduct with type 'service_point') Yes

Delivery types

Handle Description
address
express
mail
service_point
pallet

Service Point

Name Type Description Readonly
handle string String identifier of service-point, used by carrier. Yes
name string Name of service-point, that can be displayed to customer and that is put on the waybill. Yes
distance int Yes
country_code string Yes
postal_code string Yes
city string Yes
address_line string Yes
latitude float Yes
longitude float Yes
operation_hours array Yes

Address

Name Type Description Readonly
customer_type string Type of customer. Is used to identify, if address belongs to person or to company. Possible values: person, business.
type string Type of address. Different address types used for different purposes in shipping ecosystem. Possible values: sender, recipient, return.
name string Name of address owner. For companies - business name of company, for persons - first and last name.
country_code string Country code in ISO 3166-1 Alpha-2 format (more information about the format).
postal_code string Postal code of address. Should be compatible with country code.
city string City of address.
region string | null If address has a region - we recommend to specify it to give more detailed information to carrier.
address_line string The main address information. Usually it contains street, house and apartment/office.
address_line_2 string | null Address description, if needed. Everything, that don't fit in address_line, should go here. For example, some short hints on how to find the building.
contact_name string First and last name of contact person.
contact_phone string Phone of contact person in E164 format. Should be compatible with country code.
contact_email string Email of contact person. Sould be a valid email address.
latitude float | null
longitude float | null

Item

Name Type Description Readonly
uuid string String UUID of item. Is autoassigned on creation and cannot be changed. Is used for identifying item in any further requests (Items update, Package creation). Yes
article_number string | null Article number or identifier of item in merchant's system. Can be null, but we recommend specifying this attribute (if possible) to make things easier in further processing of Order in Merchant UI or Warehouse UI. Article number is not used outside Stidner ecosystem (not provided to carriers).
sku string | null
ean string | null
name string Name of item. It is put on the shipment waybill.
description string | null Text description of item. If you need some more detail about item in Merchant UI (for example, different extra attributes to define similar items from each other), you can specify them here.
vendor string | null
quantity integer Quantity of item.
unit_price integer Item price (per one item) in minor units. Price is given in currency, specified in currency attribute of parent Order.
tax_rate integer
weight integer Item weight (per one item) in grams. Be careful specifying weight, because all further relations with carriers is based on order weight - shipping prices, carriers availability (for example, there are weight restrictions in sending 'mail' packages).
height integer | null Item height (per one item) in centimeters. It's recommended to specify height of item, but it's not required. The more accurate are the dimenstions of item, the more exact is the price of shipment.
length integer | null Item length (per one item) in centimeters. It's recommended to specify length of item, but it's not required. The more accurate are the dimenstions of item, the more exact is the price of shipment.
width integer | null Item width (per one item) in centimeters. It's recommended to specify width of item, but it's not required. The more accurate are the dimenstions of item, the more exact is the price of shipment.
warehouse_location string | null Location code of item at warehouse. It is used to give the more detailed info in Warehouse UI. If you are not planning to use Warehouse UI, you can always set this attribute to null.
in_stock boolean | null If item is currently in stock or not in stock. Is used to perform shipments from Warehouse UI. If you are not planning to use Warehouse UI, you can always set this attribute to null.
meta array | null

Package

Name Type Description Readonly
uuid string String UUID of package. Is autoassigned on creation and cannot be changed. Yes
package_status string Yes
test_mode boolean Yes
direction string Direction of package. Possible values: shipment, return. Yes
carrier_handle string Yes
product_handle string Yes
shipment_number String Shipment number of package, returned from carrier. This number is used in carrier's ecosystem to identify the package (it is put on labels and used for tracking). Yes
label_url url URL to download shipment label Yes
customs_declaration_form_url url | null URL to download customs invoice for international shipments. If package is international (outside EU), this attribute contains link to invoice. If package is inside EU - this attribute is null Yes
tracking_url url Yes
items array Array of Item UUIDs, bound to this package. Yes
order Yes
shipped_at datetime Date and time when package was registered at carrier and waybills were created. Yes
pickup_status string Yes
pickup_identifier string Yes

Merchant

Name Type Description Readonly
id integer Numeric ID of Merchant. Is autoassigned to Merchant on creation and cannot be changed. Along with API key it is used for identifying Merchant in any API request. Yes
customer_type string Possible values: business, person Yes
name string Name of Merchant
If customer_type=business - business name, if customer_type=person - first and last name
Yes
type string If customer_type=business, type of company: AB (Stock Company), HB (Parntership), KB (Limited Partnership), EF (Sole Partnership). Yes
identifier string Identity number of Merchant: organisation number for customer_type=business, or social security number for customer_type=person.
Format: 10-digit string validated agains checksum.
vat_number string VAT number. It is calculated automatically based on identifier. Yes
api_key_live string API key to perform live requests. Yes
api_key_sandbox string API key to perform sandbox requests. Yes
live_mode boolean Non-live merchants can perform sandbox requests, but cannot perform live requests. Yes
addresses array Array of Address objects.
Merchant can have the following addresses: Register - the address where the company or person is registered, this address is fetched automatically and cannot be changed. Sender - shipping address, if not specified, the register address will be considered as sender. Return - return address, if not specified, the returns will be sent to register address.
created_at datetime Date and time of when Merchant was created. Yes