Create shipment

Shipments API v2
POSThttps://api.mollie.com/v2/orders/*orderId*/shipments

In addition to the Orders API, the create shipment endpoint can be used to ship order lines.

When using Klarna Pay later and Klarna Slice it this is mandatory for the order amount to be captured. An capture will automatically be created for the shipment.

The word “shipping” is used in the figurative sense here. It can also mean that a service was provided or digital content was delivered.

Parameters

lines

array
required

An array of objects containing the order line details you want to create a shipment for. If you send an empty array, the entire order will be shipped. If the order is already partially shipped, any remaining lines will be shipped.

id

string
The API resource token of the order line, for example: odl_jp31jz.

quantity

int
optional

The number of items that should be shipped for this order line. When this parameter is omitted, the whole order line will be shipped.

Must be less than the number of items already shipped for this order line.

amount

amount object
optional

The amount that you want to ship. In almost all cases, Mollie can determine the amount automatically.

The amount is required only if you are partially shipping an order line which has a non-zero discountAmount.

The amount you can ship depends on various properties of the order line and the create shipment request. The maximum that can be shipped is unit price x quantity to ship.

The minimum amount depends on the discount applied to the line, the quantity already shipped or canceled, the amounts already shipped or canceled and the quantity you want to ship.

If you do not send an amount, Mollie will determine the amount automatically or respond with an error if the amount cannot be determined automatically. The error will contain the extra.minimumAmount and extra.maximumAmount properties that allow you pick the right amount.

tracking

object
optional

An object containing tracking details for the shipment. When sent, the carrier and code parameters become required for this endpoint.

carrier

string
required
Name of the postal carrier (as specific as possible). For example PostNL.

code

string
required
The track and trace code of the shipment. For example 3SKABA000000000.

url

string
optional
The URL where your customer can track the shipment, for example: http://postnl.nl/tracktrace/?B=3SKABA000000000&P=1016EE&D=NL&T=C.

Access token parameters

If you are using organization access tokens or are creating an OAuth app, you should use the testmode parameter if you want to create a shipment in test mode.

testmode

boolean
optional
Set this to true to make this order a test shipment.

Response

201 application/hal+json

A shipment object is returned, as described in Get shipment.

Example

cURLPHPPythonRubyNode.js
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
curl -X POST https://api.mollie.com/v2/orders/ord_kEn1PlbGa/shipments \
   -H "Authorization: Bearer test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" \
   -d '{
            "lines": [
               {
                     "id": "odl_dgtxyl",
                     "quantity": 1
               },
               {
                     "id": "odl_jp31jz"
               }
            ],
            "tracking": {
               "carrier": "PostNL",
               "code": "3SKABA000000000",
               "url": "http://postnl.nl/tracktrace/?B=3SKABA000000000&P=1016EE&D=NL&T=C"
            }
         }'
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
<?php
$mollie = new \Mollie\Api\MollieApiClient();
$mollie->setApiKey('test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM');

$order = $mollie->orders->get('ord_kEn1PlbGa');
$shipment = $order->createShipment(
   [
   'lines' => [
         [
         'id' => 'odl_dgtxyl',
         'quantity' => 1, // you can set the quantity if not all is shipped at once
         ],
         [
         'id' => 'odl_jp31jz',
         // assume all is shipped if no quantity is specified
         ],
   ],
   [
         'tracking' => [
         'carrier' => 'PostNL',
         'code' => '3SKABA000000000',
         'url' => 'http://postnl.nl/tracktrace/?B=3SKABA000000000&P=1016EE&D=NL&T=C'
         ],
   ],
   ]
);

// Alternative shorthand for shipping all remaining order lines
$shipment = $order->shipAll([
'tracking' => [
   'carrier' => 'PostNL',
   'code' => '3SKABA000000000',
   'url' => 'http://postnl.nl/tracktrace/?B=3SKABA000000000&P=1016EE&D=NL&T=C'
],
]);
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
mollie_client = Client()
mollie_client.set_api_key('test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM')
order = mollie_client.orders.get('ord_kEn1PlbGa')
shipment = order.create_shipment({
   'lines': [
      {
         'id': 'odl_dgtxyl',
         'quantity': 1,  # you can set the quantity if not all is shipped at once
      },
      {
         'id': 'odl_jp31jz',  # all is shipped if no quantity is set
      }
   ],
   'tracking': {
      'carrier': 'PostNL',
      'code': '3SKABA000000000',
      'url': 'http://postnl.nl/tracktrace/?B=3SKABA000000000&P=1016EE&D=NL&T=C',
   }
})

# if all lines are shipped, there is no need to specify them
shipment = order.create_shipment({
   'tracking': {
      'carrier': 'PostNL',
      'code': '3SKABA000000000',
      'url': 'http://postnl.nl/tracktrace/?B=3SKABA000000000&P=1016EE&D=NL&T=C',
   }
})

# or when no tracking is specified:
shipment = order.create_shipment()
1
2
3
4
We don't have a Ruby code example for this API call yet.

If you have some time to spare, feel free to open a pull request at:
https://github.com/mollie/api-documentation
1
2
3
4
We don't have a Node.js code example for this API call yet.

If you have some time to spare, feel free to open a pull request at:
https://github.com/mollie/api-documentation

Response

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
HTTP/1.1 201 Created
Content-Type: application/hal+json

{
     "resource": "shipment",
     "id": "shp_3wmsgCJN4U",
     "orderId": "ord_kEn1PlbGa",
     "createdAt": "2018-08-09T14:33:54+00:00",
     "tracking": {
         "carrier": "PostNL",
         "code": "3SKABA000000000",
         "url": "http://postnl.nl/tracktrace/?B=3SKABA000000000&P=1016EE&D=NL&T=C"
     },
     "lines": [
         {
             "resource": "orderline",
             "id": "odl_dgtxyl",
             "orderId": "ord_pbjz8x",
             "name": "LEGO 42083 Bugatti Chiron",
             "sku": "5702016116977",
             "type": "physical",
             "status": "shipping",
             "isCancelable": true,
             "quantity": 1,
             "unitPrice": {
                 "value": "399.00",
                 "currency": "EUR"
             },
             "vatRate": "21.00",
             "vatAmount": {
                 "value": "51.89",
                 "currency": "EUR"
             },
             "discountAmount": {
                 "value": "100.00",
                 "currency": "EUR"
             },
             "totalAmount": {
                 "value": "299.00",
                 "currency": "EUR"
             },
             "createdAt": "2018-08-02T09:29:56+00:00",
             "_links": {
                 "productUrl": {
                     "href": "https://shop.lego.com/nl-NL/Bugatti-Chiron-42083",
                     "type": "text/html"
                 },
                 "imageUrl": {
                     "href": "https://sh-s7-live-s.legocdn.com/is/image//LEGO/42083_alt1?$main$",
                     "type": "text/html"
                 }
             }
         },
         {
             "resource": "orderline",
             "id": "odl_jp31jz",
             "orderId": "ord_pbjz8x",
             "name": "LEGO 42056 Porsche 911 GT3 RS",
             "sku": "5702015594028",
             "type": "physical",
             "status": "completed",
             "isCancelable": false,
             "quantity": 1,
             "unitPrice": {
                 "value": "329.99",
                 "currency": "EUR"
             },
             "vatRate": "21.00",
             "vatAmount": {
                 "value": "57.27",
                 "currency": "EUR"
             },
             "totalAmount": {
                 "value": "329.99",
                 "currency": "EUR"
             },
             "createdAt": "2018-08-02T09:29:56+00:00",
             "_links": {
                 "productUrl": {
                     "href": "https://shop.lego.com/nl-NL/Porsche-911-GT3-RS-42056",
                     "type": "text/html"
                 },
                 "imageUrl": {
                     "href": "https://sh-s7-live-s.legocdn.com/is/image/LEGO/42056?$PDPDefault$",
                     "type": "text/html"
                 }
             }
         }
     ],
     "_links": {
         "self": {
             "href": "https://api.mollie.com/v2/order/ord_kEn1PlbGa/shipments/shp_3wmsgCJN4U",
             "type": "application/hal+json"
         },
         "order": {
             "href": "https://api.mollie.com/v2/orders/ord_kEn1PlbGa",
             "type": "application/hal+json"
         },
         "documentation": {
             "href": "https://docs.mollie.com/reference/v2/shipments-api/get-shipment",
             "type": "text/html"
         }
     }
 }

Response (amount required)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/hal+json

{
     "status": 422,
     "title": "Unprocessable Entity",
     "detail": "Line 0 contains invalid data. An amount is required for this API call. The amount must be between €0.00 and €50.00.",
     "field": "lines.0.amount",
     "extra": {
         "minimumAmount": {
             "value": "0.00",
             "currency": "EUR"
         },
         "maximumAmount": {
             "value": "50.00",
             "currency": "EUR"
         }
     },
     "_links": {
         "documentation": {
             "href": "https://docs.mollie.com/reference/v2/shipments-api/create-shipment",
             "type": "text/html"
         }
     }
 }