Outbounds

Outbounds — Let us know what products we should ship. On this page, we'll dive into the different outbound endpoints you can use to manage outbounds programmatically. We'll look at how to query, create, update, and delete outbounds.

The outbound model

The outbound model contains all the information about outbounds, such as their ref, prefered shipping method and contents.

Properties

Name
ref
Type
string
Description
Your unique reference that identifies the outbound.
This will be the ref we communicate back to you. Make sure to make it unique, especially when you have multiple source systems.
Name
orderRef
Type
string
maxLength(35)
Description
The order reference as given to the receiver, helping them recognizing the outbound as it is received
Name
message
Type
string
Description
An optional message for us
Name
shippingAdvice
Type
enum
Description
Advice us on how to ship the outbound. Valid values: complete, partial, partialonce
When you update an outbound's shippingAdvice to partialonce we will ship the products we have on stock and put the shipping advice back to complete.
Name
deliveryDate
Type
date
Description
The date the outbound should be delivered to the recipient
Name
shipToName
Type
string
maxLength(100)
Description
The name of the recipient
Name
shipToContact
Type
string
maxLength(100)
Description
The contact or second name line for the recipient
Name
shipToAddressLine1
Type
string
maxLength(100)
Description
Address Line 1
Name
shipToAddressLine2
Type
string
maxLength(100)
Description
Address Line 2
Name
shipToCity
Type
string
maxLength(30)
Description
The city of the recipient
Name
shipToCountryCode
Type
string
maxLength(2)
Description
The code for the country of the recipient
Name
shipToPostCode
Type
string
maxLength(20)
Description
The zipcode for the shipTo Address
Name
shippingContactName
Type
string
maxLength(100)
Description
The name of the contact for the shipping, the shipping agent can contact the recipient to plan the shipment or if they are not at home.
Name
shippingContactEmail
Type
string
maxLength(80)
Description
The emailaddress of the contact for the shipping.
Name
shippingContactPhonenumber
Type
string
maxLength(30)
Description
The phonenumber of the contact for the shipping.
Name
shippingContactAddress
Type
string
maxLength(100)
Description
The address of the contact for the shipping. Used by the shipping agent for example to verify ownership when picking up.
Name
shippingContactPostCode
Type
string
maxLength(20)
Description
The zipcode of the contact for the shipping.
Name
shippingContactCity
Type
string
maxLength(30)
Description
The city of the contact for the shipping.
Name
shippingContactCountryCode
Type
string
maxLength(2)
Description
The country code of the contact for the shipping.
Name
status
Type
enum
Description
The status of the outbound. Valid values: new, in_progress, partially_shipped, fully_shipped, cancelled, on_hold, ready_for_pickup and picked_up
Name
shipmentMethodCode
Type
string
Description
Tell us how you want us to ship this outbound. Valid values can be found in your partner portal under settings/shipping.
Name
lines
Type
array
Description
The collection containing the lines for this outbound. Refer to the outboundLine model on this page to see the properties for an outboundLine.
Name
shipments
Type
array
Description
The collection containing the shipments for this outbound. Refer to the shipment model to see the properties for a shipment.

GET/fulfilment/v3/outbounds?skip=:skip&take=:take&filter=:filter

List your outbounds

This endpoint allows you to retrieve a list of outbounds.

Optional arguments

Name
skip
Type
number
Description
How many outbounds to skip
Name
take
Type
number
Description
How many outbounds to return
Name
filter
Type
filter
Description
Consult the filtering guide for more information.
Name
change-interval
Type
integer
Description
Get all records that have changed in the last change-interval minutes. Value between 5 and 2800
Allthough we support polling. We recommend using webhooks. If you are going to poll please use this property to keep traffic manageable.
Name
include
Type
enum
Description
The releated record to include. Valid values: lines, shipments

Request

GET

/fulfilment/v3/outbounds

curl --location https://partner.punt-uit.nl/api/fulfilment/v3/outbounds \
  --header "Authorization: Bearer {token}" \

Response

[
{
    "ref": "9QI57GUOMB",
    "orderRef": "1705",
    "message": null,
    "shippingAdvice": "complete",
    "shipToName": "OBS 't Eenspan",
    "shipToContact": "Dhr. Jansen",
    "shipToAddressLine1": "Oosterstraat 58",
    "shipToAddressLine2": null,
    "shipToCity": "Emmen",
    "shipToCountryCode": "NL",
    "shipToPostCode": "7822 HG",
    "shippingContactName": null,
    "shippingContactEmail": null,
    "shippingContactPhonenumber": null,
    "shippingContactAddress": null,
    "shippingContactPostCode": null,
    "shippingContactCity": null,
    "shippingContactCountryCode": null,
    "shipmentMethodCode": "PNLS",
    "deliveryDate": "2023-10-07",
    "status": "new",
    "lines": [
        {
            "ref": "_RhjUOwZXQKVBZyNNJo1h",
            "quantity": 11,
            "quantityShipped": 0,
            "sku": "LI00P01"
        },
        {
            "ref": "13MVNVP9Z",
            "quantity": 1,
            "quantityShipped": 0,
            "sku": "LI00P02"
        }
    ],
    "shipments": [
      {
            "id": "clofu5kni000bjp08fv0o2k60",
            "shipmentDate": "2023-11-01",
            "trackingCode": "3SQXDX0163325",
            "shippingAgent": "POSTNL",
            "shippingService": "4946",
            "trackingLink": "http://postnl.nl/tracktrace/?L=en&B=3SQXDX0163325&P=2200&D=BE&T=C",
            "lines": [
                {
                    "sku": "15129",
                    "outboundRef": "249047969",
                    "outboundLineRef": "492815843",
                    "quantity": 1
                }
            ]
        }
    ]
}
]

POST/fulfilment/v3/outbounds/

Create an outbound

This endpoint allows you to add an outbound.

We recommend limiting Outbound creation to 30 orders/minute, to ensure that outbounds are processed without error.

Required attributes

Name
body
Type
json
Description
json containing the outbound to create. Refer to the outbound model at the top of this page to see the properties we support.

Optional arguments

Name
include
Type
enum
Description
The releated record to include. Valid values: lines, shipments

Request

POST

/fulfilment/v3/outbounds

curl https://partner.punt-uit.nl/api/fulfilment/v3/outbounds \
  -H "Authorization: Bearer {token}" \
  -d '{
      "ref": "12408",
      "orderRef": "1083",
      "shipToName": "Bart Smit",
      "shipToContact": "Simone Haring",
      "shipToAddressLine1": "Picassopassage 35",
      "shipToCity": "Emmen",
      "shipToPostCode": "7811 DN",
      "shipToCountryCode": "NL",
      "shippingContactName": "Status 418",
      "shippingContactEmail": "info@status418.nl",
      "shippingContactPhonenumber": "06123456789",
      "shippingContactAddress": "Picassopassage 35",
      "shippingContactPostCode": "7811 DN",
      "shippingContactCity": "Emmen",
      "shippingContactCountryCode": "NL",
      "shipmentMethodCode": "POSTNL-3085-DAP",
      "deliveryDate": "2024-02-01",
      "message": "afleveren bij de buren",
      "lines": [
          {
              "ref": "12406-03",
              "sku": "SKUAPI02",
              "quantity": 5
          }
      ]
  }

Response

{
  "ref": "12408",
  "orderRef": "1083",
  "message": "afleveren bij de buren",
  "shippingAdvice": "complete",
  "shipToName": "Bart Smit",
  "shipToContact": "Simone Haring",
  "shipToAddressLine1": "Picassopassage 35",
  "shipToAddressLine2": null,
  "shipToCity": "Emmen",
  "shipToCountryCode": "NL",
  "shipToPostCode": "7811 DN",
  "shippingContactName": "Status 418",
  "shippingContactEmail": "info@status418.nl",
  "shippingContactPhonenumber": "06123456789",
  "shippingContactAddress": "Picassopassage 35",
  "shippingContactPostCode": "7811 DN",
  "shippingContactCity": "Emmen",
  "shippingContactCountryCode": "NL",
  "shipmentMethodCode": "POSTNL-3085-DAP",
  "deliveryDate": "2024-02-01",
  "status": "new",
  "lines": [
      {
          "ref": "12406-03",
          "quantity": 5,
          "quantityShipped": 0,
          "sku": "SKUAPI02"
      }
  ],
  "shipments": []
}

POST/fulfilment/v3/bulk/outbounds/

Create multiple outbounds

This endpoint allows you to add multiple outbounds.

We recommend limiting Outbound creation to 30 orders/minute, to ensure that outbounds are processed without error.

Required attributes

Name
body
Type
json
Description
json array containing the outbounds to create. Refer to the outbound model at the top of this page to see the properties we support.

Optional arguments

Name
include
Type
enum
Description
The releated record to include. Valid values: lines, shipments

Request

POST

/fulfilment/v3/bulk/outbounds

curl https://partner.punt-uit.nl/api/fulfilment/v3/outbounds \
  -H "Authorization: Bearer {token}" \
  -d '
    [
      {
        "ref": "12406",
        "orderRef": "1083",
        "shipToName": "Bart Smit",
        "shipToContact": "Simone Haring",
        "shipToAddressLine1": "Picassopassage 35",
        "shipToCity": "Emmen",
        "shipToPostCode": "7811 DN",
        "shipToCountryCode": "NL",
        "shippingContactName": "Status 418",
        "shippingContactEmail": "info@status418.nl",
        "shippingContactPhonenumber": "06123456789",
        "shippingContactAddress": "Picassopassage 35",
        "shippingContactPostCode": "7811 DN",
        "shippingContactCity": "Emmen",
        "shippingContactCountryCode": "NL",
        "shipmentMethodCode": "PNLS",
        "lines": [
            {
                "ref": "12406-01",
                "sku": "LI00P01",
                "quantity": 5
            }
        ]
      },
      {
        ...
      }
    ]

Response

[
  {
    "ref": "2023121201",
    "orderRef": "1083",
    "shipToName": "Bart Smit",
    "shipToContact": "Simone Haring",
    "shipToAddressLine1": "Picassopassage 35",
    "shipToCity": "Emmen",
    "shipToPostCode": "7811 DN",
    "shipToCountryCode": "NL",
    "shippingContactName": "Status 418",
    "shippingContactEmail": "info@status418.nl",
    "shippingContactPhonenumber": "06123456789",
    "shippingContactAddress": "Picassopassage 35",
    "shippingContactPostCode": "7811 DN",
    "shippingContactCity": "Emmen",
    "shippingContactCountryCode": "NL",
    "shipmentMethodCode": "POSTNL-3085-DAP",
    "lines": [
        {
            "ref": "2023121201-01",
            "sku": "19636",
            "quantity": 5
        }
    ]
  },
  {
    ...
  }
]

GET/fulfilment/v3/outbounds/:ref

Retrieve an outbound

This endpoint allows you to retrieve an outbound by providing your ref. Refer to the outbound at the top of this page to see which properties are included with outbound objects.

Required arguments

Name
ref
Type
string
Description
Path parameter representing your ref of the outbound.

Optional arguments

Name
include
Type
enum
Description
The releated record to include. Valid values: lines, shipments

Request

GET

/fulfilment/v3/outbounds/:ref

curl --location https://partner.punt-uit.nl/api/fulfilment/v3/outbounds/HJ8HV8EGO \
  --header "Authorization: Bearer {token}"

Response

{
    "ref": "HJ8HV8EGO",
    "orderRef": "trehe1a45uitdy",
    "message": null,
    "shippingAdvice": "complete",
    "shipToName": "Bart Smit",
    "shipToContact": "Simone Haring",
    "shipToAddressLine1": "Picassopassage 35",
    "shipToCity": "Emmen",
    "shipToPostCode": "7811 DN",
    "shipToCountryCode": "NL",
    "shippingContactName": "Status 418",
    "shippingContactEmail": "info@status418.nl",
    "shippingContactPhonenumber": "06123456789",
    "shippingContactAddress": "Picassopassage 35",
    "shippingContactPostCode": "7811 DN",
    "shippingContactCity": "Emmen",
    "shippingContactCountryCode": "NL",
    "shipmentMethodCode": "POSTNL-3085-DAP",
    "deliveryDate": "2023-12-22",
    "status": "fully_shipped",
    "lines": [
        {
            "ref": "6LUQ7QM4L",
            "quantity": 10,
            "quantityShipped": 10,
            "sku": "happy123"
        }
    ],
    "shipments": [
        {
            "id": "TOR0000699",
            "shipmentDate": "2023-12-21",
            "trackingCode": "3SDEVC9020388",
            "shippingAgent": "POSTNL",
            "shippingService": "3085",
            "trackingLink": "http://postnl.nl/tracktrace/?L=NL&B=3SDEVC9020388&P=7814VN&D=NL&T=C",
            "lines": [
                {
                    "quantity": 10,
                    "outboundRef": "HJ8HV8EGO",
                    "outboundLineRef": "6LUQ7QM4L",
                    "sku": "happy123"
                }
            ]
        }
    ]
}

PUT/fulfilment/v3/outbounds/:ref

Update an outbound

This endpoint allows you to perform an update on an outbound. Examples of updates are changing the delivery date or shippingAdvice.

Required attributes

Name
ref
Type
string
Description
Path parameter representing your ref of the outbound.
Name
body
Type
string
Description
A json body containing the new values.

Optional arguments

Name
include
Type
enum
Description
The releated record to include. Valid values: lines, shipments

Request

PUT

/fulfilment/v3/outbounds/2023121201

curl --location --request PUT https://partner.punt-uit.nl/api/fulfilment/v3/outbounds/2023121201 \
  --header "Authorization: Bearer {token}" \
  --data '{
    "message": "Dit is een opmerking"
  }'

Response

{
  "ref": "12408",
  "orderRef": "1083",
  "message": "Dit is een opmerking",
  "shippingAdvice": "complete",
  "shipToName": "Bart Smit",
  "shipToContact": "Simone Haring",
  "shipToAddressLine1": "Picassopassage 35",
  "shipToAddressLine2": null,
  "shipToCity": "Emmen",
  "shipToCountryCode": "NL",
  "shipToPostCode": "7811 DN",
  "shippingContactName": "Status 418",
  "shippingContactEmail": "info@status418.nl",
  "shippingContactPhonenumber": "06123456789",
  "shippingContactAddress": "Picassopassage 35",
  "shippingContactPostCode": "7811 DN",
  "shippingContactCity": "Emmen",
  "shippingContactCountryCode": "NL",
  "shipmentMethodCode": "POSTNL-3085-DAP",
  "deliveryDate": "2024-02-01",
  "status": "new",
  "lines": [
      {
          "ref": "12406-03",
          "quantity": 5,
          "quantityShipped": 0,
          "sku": "SKUAPI02"
      }
  ],
  "shipments": []
}

DELETE/fulfilment/v3/outbounds/:ref

Delete an outbound

When we have shipped anything for the outbound you cannot delete it.

This endpoint allows you to delete outbounds. Note: This will permanently delete the outbound.

Required attributes

Name
ref
Type
string
Description
Path parameter representing your ref of the outbound.

Request

DELETE

/fulfilment/v3/outbounds/3234425353

curl --location --request DELETE https://partner.punt-uit.nl/api/fulfilment/v3/outbounds/3234425353 \
  --header "Authorization: Bearer {token}"

The outboundLine model

The outboundLine model contains all the information about outboundlines, such as their product, quantity and quantityShipped.

Properties

Name
ref
Type
string
Description
Your unique reference that identifies the outboundLine
Name
sku
Type
string
Description
Unique reference to the product for the outboundLine
Name
quantity
Type
integer
Description
The number of items to ship for this outboundLine
Name
quantityShipped
Type
integer
Description
The number of items shipped on this outboundLine

GET/fulfilment/v3/outbounds/:ref/lines?skip=:skip&take=:take

List the lines for an outbound

This endpoint allows you to retrieve the lines for an outbound.

Required arguments

Name
ref
Type
url param
Description
Your ref for the outbound to get the lines for.

Optional arguments

Name
skip
Type
number
Description
How many lines to skip
Name
take
Type
number
Description
How many lines to return. Minimum for this argument is 10 maximum is 100

Request

GET

/v3/outbounds/:ref/lines

curl --location https://partner.punt-uit.nl/api/fulfilment/v3/outbounds/202303221138002/lines \
  --header "Authorization: Bearer {token}" \

Response

[
  {
    "ref": "202303221138002:01",
    "quantity": 100,
    "quantityShipped": 10,
    "sku": "LI00P01"
  },
  {
    ...
  }
]

POST/fulfilment/v3/outbounds/:ref/lines

Create an outboundLine

This endpoint allows you to add a outboundLine to an existing outbound.

Required attributes

Name
body
Type
json
Description
json containing the outboundLine to create. Refer to the outboundLine model to see the properties we support.

Request

POST

/fulfilment/v3/outbounds/:ref/lines

curl --location https://partner.punt-uit.nl/api/fulfilment/v3/outbounds/202303221138002/lines \
  --header "Authorization: Bearer {token}" \
  --data '{
    "sku": "SKUAPI02",
    "ref": "3234425353.03",
    "quantity": 42
  }

Response

{
  "ref": "202303221138002:11",
  "sku": "SKUAPI02",
  "quantity": 42,
  "quantityShipped": 0
}

GET/fulfilment/v3/outbounds/:ref/lines/:lineRef

Retrieve a outboundLine

This endpoint allows you to retrieve a outboundLine by providing your refs for the outbound and line. Refer to the outbound model to see which properties are included with outboundLine objects.

Request

GET

/fulfilment/v3/outbounds/:ref/lines/:lineRef

curl --location https://partner.punt-uit.nl/api/fulfilment/v3/outbounds/202303221138002/lines/202303221138002:01 \
  --header "Authorization: Bearer {token}"

Response

{
    "ref": "202303221138002:01",
    "quantity": 100,
    "quantityShipped": 0,
    "sku": "LI00P01"
}

PUT/fulfilment/v3/inbounds/:ref/lines/:lineRef

Update an outboundLine

This endpoint allows you to perform an update on an outboundLine. Examples of updates are changing the quantity.

Required attributes

Name
body
Type
string
Description
A json body containing the new values. Refer to the outboundLine model to see the properties we support.

Request

PUT

/fulfilment/v3/outbounds/:ref/lines/:lineRef

curl --location --request PUT https://partner.punt-uit.nl/api/fulfilment/v3/outbounds/202303221138002/lines/202303221138002:01 \
  --header "Authorization: Bearer {token}" \
  --data '{
    "quantity": 46
  }'

Response

{
    "ref": "202303221138002:01",
    "quantity": 46,
    "quantityShipped": 0,
    "sku": "LI00P01"
}

DELETE/fulfilment/v3/outbounds/:ref/lines/:lineRef

Delete an outboundLine

When we have shipped anything for the outboundLine you cannot delete it.

This endpoint allows you to delete an outboundLine. Note: This will permanently delete the outboundLine.

Request

DELETE

/fulfilment/v3/outbounds/:ref/lines/:lineRef

curl --location --request DELETE https://partner.punt-uit.nl/api/fulfilment/v3/outbounds/202303221138002/lines/202303221138002:02 \
  --header "Authorization: Bearer {token}"