PostNL Checkout API

Return the delivery and pickup options to show in a webshop checkout (v1).

GitHub OpenAPI

Operations 1

POST /shipment/v1/checkout Checkout #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/postnl:checkout-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

postnl-checkout-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: PostCIF-CheckoutService Checkout API
  description: Returns delivery information
  version: v1
servers:
- url: https://api-sandbox.postnl.nl
  description: Non-Production server
- url: https://api.postnl.nl
  description: Production server
security:
- APIKeyHeader: []
tags:
- name: Checkout
paths:
  /shipment/v1/checkout:
    post:
      tags:
      - Checkout
      summary: Checkout
      operationId: Checkout
      security:
      - APIKeyHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/checkoutRequest'
            examples:
              Delivery and pickup options:
                $ref: '#/components/examples/checkoutExampleFull'
              Delivery options only:
                $ref: '#/components/examples/checkoutExampleDelivery'
              Pickup options only:
                $ref: '#/components/examples/checkoutExamplePickup'
        required: true
      responses:
        '200':
          description: Status object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkoutResponse'
              example:
                DeliveryOptions:
                - DeliveryDate: 09-07-2019
                  Timeframe:
                  - From: '18:00:00'
                    To: '22:30:00'
                    Options:
                    - Daytime
                    ShippingDate: 08-07-2019
                    Sustainability:
                      Code: '02'
                      Description: Sustainable option
                PickupOptions:
                - PickupDate: 09-07-2019
                  ShippingDate: 08-07-2019
                  Option: Pickup
                  Locations:
                  - Address:
                      Street: Siriusdreef
                      Zipcode: 2132WT
                      HouseNr: 42
                      HouseNrExt: '-60'
                      Countrycode: NL
                      CompanyName: Pickup company BV
                    PickupTime: '15:00'
                    OpeningHours:
                      Monday:
                        From: 08:30:00
                        To: '22:30:00'
                      Tuesday:
                        From: 08:30:00
                        To: '22:30:00'
                      Wednesday:
                        From: 08:30:00
                        To: '22:30:00'
                      Thursday:
                        From: 08:30:00
                        To: '22:30:00'
                      Friday:
                        From: 08:30:00
                        To: '22:30:00'
                      Saturday:
                        From: 08:30:00
                        To: '22:30:00'
                      Sunday:
                        From: 08:30:00
                        To: '22:30:00'
                    Distance: 234
                    LocationCode: '8101163043'
                    PartnerID: PNPNL-01
                    Sustainability:
                      Code: '02'
                      Description: Sustainable option
                Warnings:
                - DeliveryDate: 07-07-2019
                  Code: '5034'
                  Description: No delivery option found on date
                  Options: Daytime
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequest'
              example:
                Date: '2024-06-11T12:38:45.413Z'
                Error:
                  ErrorCode: '3000'
                  ErrorDescription: Request format is invalid
                RequestId: 09fd61fe-0099-4349-b71d-dce5c2472be9
        '401':
          description: Invalid apikey
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              example:
                message: Failed to resolve API Key variable 'request.header.apikey'
                http_status_code: 401
        '405':
          description: Method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowedOnlyPost'
              example:
                message: Only POST requests allowed
                http_status_code: 405
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
              example:
                message: Too many requests. Rate limit exceeded!
                http_status_code: 429
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
              example:
                fault:
                  faultstring: Unexpected token in object literal
                  detail:
                    errorcode: Validation Fault
components:
  schemas:
    InvalidRequest:
      type: object
      properties:
        Date:
          type: string
          format: date-time
        Error:
          type: object
          properties:
            ErrorCode:
              type: string
              example: '3000'
            ErrorDescription:
              type: string
              example: Request format is invalid
        RequestId:
          type: string
          example: 09fd61fe-0099-4349-b71d-dce5c2472be9
    checkoutWarningOption:
      type: string
      enum:
      - Daytime
      - Evening
      - Sameday
      - 08:00-10:00
      - 08:00-12:00
      - 08:00-17:00
      - Pickup
      example: Daytime
    checkoutLocation:
      type: object
      properties:
        Address:
          $ref: '#/components/schemas/checkoutPickupAddress'
        PickupTime:
          type: string
          description: Time from when the parcel can be retrieved at the pickup location
          example: '15:00'
        OpeningHours:
          type: object
          description: The standard opening hours of the pickup location
          properties:
            Monday:
              $ref: '#/components/schemas/openingHoursPerDay'
            Tuesday:
              $ref: '#/components/schemas/openingHoursPerDay'
            Wednesday:
              $ref: '#/components/schemas/openingHoursPerDay'
            Thursday:
              $ref: '#/components/schemas/openingHoursPerDay'
            Friday:
              $ref: '#/components/schemas/openingHoursPerDay'
            Saturday:
              $ref: '#/components/schemas/openingHoursPerDay'
            Sunday:
              $ref: '#/components/schemas/openingHoursPerDay'
        Distance:
          type: integer
          description: The calculated distance (in meters) between the location specified and the address provided in the request
          example: 234
        LocationCode:
          type: string
          description: The location identifier
          example: '8101163043'
        PartnerID:
          type: string
          description: The partner identifier; not used anymore
          example: PNPNL-01
        Sustainability:
          type: object
          description: Sustainability score; see [Sustainability codes](https://developer.postnl.nl/docs/#/http/reference-data/reference-codes/sustainability-codes) for possible values.
          properties:
            Code:
              type: string
              description: Sustainability score code
              example: '02'
              enum:
              - '00'
              - '01'
              - '02'
              - '03'
            Description:
              type: string
              description: Sustainability score code description
              example: Sustainable option
    checkoutPickupAddress:
      type: object
      description: The pickup location address
      properties:
        Street:
          type: string
          description: The pickup location street
          example: Siriusdreef
        Zipcode:
          type: string
          description: The pickup location zipcode
          example: 2132WT
        HouseNr:
          type: integer
          description: The pickup location housenumber
          example: 42
        HouseNrExt:
          type: string
          description: The pickup location housenumber extension
          example: '-60'
        Countrycode:
          type: string
          description: The pickup location country
          example: NL
        CompanyName:
          type: string
          description: The pickup location company name
          example: Pickup company BV
    checkoutResponse:
      type: object
      properties:
        DeliveryOptions:
          type: array
          description: Array of delivery options
          items:
            $ref: '#/components/schemas/checkoutDeliveryOption'
        PickupOptions:
          type: array
          description: Array of possible pickup options
          items:
            $ref: '#/components/schemas/checkoutPickupOption'
        Warnings:
          type: array
          description: An array of warnings
          items:
            $ref: '#/components/schemas/checkoutWarning'
    InternalServerError:
      type: object
      properties:
        fault:
          type: object
          properties:
            faultstring:
              type: string
              example: Unexpected token in object literal
            detail:
              type: object
              properties:
                errorcode:
                  type: string
                  example: Validation Fault
    checkoutTimeFrame:
      type: object
      properties:
        From:
          type: string
          description: Format hh:mm:ss
          example: '18:00:00'
        To:
          type: string
          description: Format hh:mm:ss
          example: '22:30:00'
        Options:
          type: array
          description: The delivery options applicable to the timeframe information. See [Delivery Options](https://developer.postnl.nl/docs/#/http/reference-data/reference-codes/delivery-options) for possible values.
          items:
            $ref: '#/components/schemas/checkoutOption'
        ShippingDate:
          type: string
          description: The date when you need to deliver the shipment to PostNL to ensure the expected delivery date is achieved. Will be returned as 'null' if not calculated
          example: 08-07-2019
        Sustainability:
          type: object
          description: Sustainability score; see [Sustainability codes](https://developer.postnl.nl/docs/#/http/reference-data/reference-codes/sustainability-codes) for possible values.
          properties:
            Code:
              type: string
              description: Sustainability score code
              example: '02'
              enum:
              - '00'
              - '01'
              - '02'
              - '03'
            Description:
              type: string
              description: Sustainability score code description
              example: Sustainable option
    checkoutWarning:
      type: object
      properties:
        DeliveryDate:
          type: string
          description: Deliverydate that triggered the warning
          example: 07-07-2019
        Code:
          type: string
          description: Warning code (for a possible list of warnings, see the generic error codes page)
          example: '5034'
        Description:
          type: string
          description: Warning description (for a possible list of warnings, see the generic error codes page)
          example: No delivery option found on date
        Options:
          $ref: '#/components/schemas/checkoutWarningOption'
    openingHoursPerDay:
      type: object
      properties:
        From:
          type: string
          example: 08:30:00
        To:
          type: string
          example: '22:30:00'
    checkoutCutOffDay:
      type: string
      description: The day for which the cutoff time applies. 00 is your default cutoff that applies to all otherwise not specified days, 01 to 07 is Monday to Sunday.
      enum:
      - '00'
      - '01'
      - '02'
      - '03'
      - '04'
      - '05'
      - '06'
      - '07'
      example: '00'
    Unauthorized:
      type: object
      properties:
        message:
          type: string
          example: Failed to resolve API Key variable 'request.header.apikey'
        http_status_code:
          type: number
          example: 401
    checkoutCutOffTime:
      type: object
      required:
      - Day
      properties:
        Day:
          $ref: '#/components/schemas/checkoutCutOffDay'
        Available:
          type: boolean
          description: Specifies whether you are available to process shipments during the selected day
          example: true
        Type:
          $ref: '#/components/schemas/checkoutCutOffType'
        Time:
          type: string
          description: Specifies the cutoff time (mandatory when Available is true)
          example: '23:00:00'
          pattern: ^[0-2]\d:[0-5]\d:[0-5]\d$
    checkoutCutOffType:
      type: string
      description: Specifies the type belonging to the cutoff time.
      enum:
      - Regular
      - Sameday
      - Today
      example: Regular
    checkoutAddress:
      type: object
      required:
      - AddressType
      - HouseNr
      - Zipcode
      - Countrycode
      properties:
        AddressType:
          type: string
          description: Address type. 01 is for the receiver address, 02 is for the sender address.
          enum:
          - '01'
          - '02'
          example: '01'
        Street:
          type: string
          description: Street name; for Belgian addresses, it is strongly recommended to fill in the  street value
          example: Molengraaffplantsoen
          maxLength: 35
        HouseNr:
          type: integer
          description: The house number of the delivery address
          example: 74
        HouseNrExt:
          type: string
          description: House number extension
          example: bis
          maxLength: 7
        Zipcode:
          type: string
          description: Zipcode of the address
          minLength: 4
          maxLength: 6
          example: 3571ZZ
        City:
          type: string
          description: City of the address
          example: Utrecht
          maxLength: 35
        Countrycode:
          type: string
          description: ISO2 country code. Limited to NL and BE.
          enum:
          - NL
          - BE
          example: NL
    MethodNotAllowedOnlyPost:
      type: object
      properties:
        message:
          type: string
          example: Only POST requests allowed
        http_status_code:
          type: number
          example: 405
    checkoutOption:
      type: string
      enum:
      - Daytime
      - Evening
      - Sameday
      - 08:00-10:00
      - 08:00-12:00
      - 08:00-17:00
      - Pickup
      example: Daytime
    TooManyRequests:
      type: object
      properties:
        message:
          type: string
          example: Too many requests. Rate limit exceeded!
        http_status_code:
          type: number
          example: 429
    checkoutDeliveryOption:
      type: object
      properties:
        DeliveryDate:
          type: string
          description: The possible delivery date
          example: 09-07-2019
        Timeframe:
          type: array
          description: Array of timeframes
          items:
            $ref: '#/components/schemas/checkoutTimeFrame'
    checkoutRequest:
      type: object
      required:
      - OrderDate
      - CutOffTimes
      - Options
      - Locations
      - Days
      - Addresses
      properties:
        OrderDate:
          type: string
          description: The order date of the shipment. Format dd-MM-YYYY HH:mm:ss
          example: 11-07-2019 12:34:54
          pattern: ^[0-3]\d-[0-1]\d-20\d{2}\s[0-2]\d:[0-5]\d:[0-5]\d$
        ShippingDuration:
          type: integer
          description: The amount of days it takes for a parcel to be received by PostN. If you delivery the parcel the same day as the order is placed on the webshop, please use the value of 1. A value of 2 means the parcel will arrive at PostNL a day later etc.
          example: 1
        CutOffTimes:
          type: array
          description: Array of CutOffTimes
          items:
            $ref: '#/components/schemas/checkoutCutOffTime'
        HolidaySorting:
          type: boolean
          description: Specifies whether you are available to ship parcels to PostNL during holidays
          example: true
        Options:
          type: array
          description: Specifies the delivery and pickup options.
          items:
            $ref: '#/components/schemas/checkoutOption'
          example:
          - Daytime
          - Evening
          - Pickup
        Locations:
          type: integer
          description: Specifies the number of locations you want returned. This can be a value of 1-3
          minimum: 1
          maximum: 3
          example: 2
        Days:
          type: integer
          description: Specifies the number of days for which the timeframes are returned. This can be a value of 1-9
          minimum: 1
          maximum: 9
          example: 3
        Addresses:
          type: array
          description: Array of addresses
          items:
            $ref: '#/components/schemas/checkoutAddress'
    checkoutPickupOption:
      type: object
      properties:
        PickupDate:
          type: string
          description: Date from which the parcel can be picked up at the PostNL location
          example: 09-07-2019
        ShippingDate:
          type: string
          description: The date when you need to deliver the shipment to PostNL to ensure the expected delivery date is achieved. Will be returned as 'null' if not calculated
          example: 08-07-2019
        Option:
          type: string
          description: The pickup option
          example: Pickup
        Locations:
          type: array
          description: Array of pickup locations
          items:
            $ref: '#/components/schemas/checkoutLocation'
  examples:
    checkoutExampleDelivery:
      value:
        OrderDate: 24-02-2021 12:00:00
        ShippingDuration: '1'
        CutOffTimes:
        - Day: '00'
          Available: 'true'
          Type: Regular
          Time: '20:00:00'
        - Day: '00'
          Available: 'true'
          Type: Today
          Time: '12:00:00'
        HolidaySorting: 'true'
        Options:
        - Daytime
        - Evening
        Locations: '2'
        Days: '3'
        Addresses:
        - AddressType: '01'
          Street: Molengraaffplantsoen
          HouseNr: '74'
          Zipcode: 3571ZZ
          City: Utrecht
          Countrycode: NL
    checkoutExampleFull:
      value:
        OrderDate: 24-02-2021 12:00:00
        ShippingDuration: '1'
        CutOffTimes:
        - Day: '00'
          Available: 'true'
          Type: Regular
          Time: '20:00:00'
        - Day: '00'
          Available: 'true'
          Type: Today
          Time: '12:00:00'
        HolidaySorting: 'true'
        Options:
        - Daytime
        - Evening
        - Pickup
        Locations: '2'
        Days: '3'
        Addresses:
        - AddressType: '01'
          Street: Molengraaffplantsoen
          HouseNr: '74'
          Zipcode: 3571ZZ
          City: Utrecht
          Countrycode: NL
    checkoutExamplePickup:
      value:
        OrderDate: 24-02-2021 12:00:00
        ShippingDuration: '1'
        CutOffTimes:
        - Day: '00'
          Available: 'true'
          Type: Regular
          Time: '20:00:00'
        HolidaySorting: 'true'
        Options:
        - Pickup
        Locations: '2'
        Days: '3'
        Addresses:
        - AddressType: '01'
          Street: Molengraaffplantsoen
          HouseNr: '74'
          Zipcode: 3571ZZ
          City: Utrecht
          Countrycode: NL
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      name: apikey
      in: header