The shipment lifecycle is split into 3 steps.
On this step the shipment data is registered in Stidner, and the possible shipping options are returned.
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
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.
| 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 |
|
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 |
|
Time when order was completed (when 'status' was changed to 'completed'). For not completed orders - null. | Yes |
| 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). |
| 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. |
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'.
| 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 of Service Point objects (for OrderProduct with type 'service_point') | Yes |
| Handle | Description |
|---|---|
| address | |
| express | |
| service_point | |
| pallet |
| 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 |
| 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 |
|
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 |
| 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 |
|
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 |
|
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 |
|
| 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 |
| 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 |