/
Media Order B2C and Shipment

Media Order B2C and Shipment

Revision

Date

Description

Date

Description

mid-March 2026
Exact date is not yet known, to be announced later

As of April 1, CB will discontinue the e-commerce packing slip.
In mid-March 2026 we will offer the option of adding an order reference to the carrier's shipping label if desired. The shipping label already includes the details of the B2C client (publisher, webshop) as the sender, and the order reference (also known to the consumer) will be added to this.

AddressLabelInstructions: required: - AddressLabel type: object properties: AddressLabel: maxLength: 14 minLength: 1 pattern: "^[^#]*$" type: string description: A label remark to be printed on the shipment label. example: "Shop: 12345678" description: Address Label instruction for the order.

With the AddressLabelInstructions, the following attributes will be discontinued. Once AddressLabelInstructions is transmitted, the following attributes may no longer be submitted.

PackingSlipInstructions GreetingCardInstructions Attachments

Mar 4, 2025

New version due to move to a new server. URL change and new yaml versions MediaOrderB2C and MediaShipment

Functional changes:

  • MediaOrderB2C Get Orderstatus: The "OwnerName" has been included in the OpenApi specification. Up until now, this field was incorrectly not included as a tag and therefore also not as a value. In this new version, this is the case (if applicable).

  • MediaShipment Get ShippingUnit: The ShippingUnitId has been extended, so that it remains unique. Even over the years.

Jun 2, 2023

Added extra information authorisation: “Basic ”||"Base64 encoding of username and password joined by a single colon : "

May 3, 2022

Media Order B2C: Yaml file version 1.3.0. Changelog version 1.2.0 to version 1.3.0:

  • Add Article with ArticleId as product identification for dedicated stock

  • Use either EAN or Article in placeOrder (EAN is now optional), if both are supplied the EAN is used and Article is ignored

  • Report either EAN or Article in getOrderStatus based on provided input in placeOrder

MediaShipment: Yaml file version 1.0.0 version 1.1.0. Changelog version 1.0.0 to version 1.1.0:

  • Add ArticleId as product identification for dedicated stock

  • Report either EAN or ArticleId in getShippingUnit based on provided input in placeOrder

Jan 25, 2022

Test and order simulation added

Dec 15, 2021

Add Tag matrix for Standard (without packing slip) and Old (with packing slip)

Oct 19, 2021

Update yaml file MediaOrderNotify v.1.0.2.yaml

Aug 19, 2021

Update generic error messages

May 7, 2021

Align with updated order notifications

Nov 12, 2020

Update yaml file MediaOrderB2C v1.2.0.yaml

Jun 8, 2020

Update MediaOrderB2C version; Correct resource for notifyOrder and notityShipment

Apr 28, 2020

Update yaml versions

Mar 12, 2020

Add volume limits and error messages; Correct typo in process flow diagrams

Jan 13, 2020

Add flows and sequence diagrams

Nov 11, 2019

Add operations

Aug 30, 2019

Initial document

Introduction

This document contains a description of the standard interfaces for implementation of data exchange with CB via webservices.

Tag matrix for Standard (without packing slip) and Old (with packing slip)

CB has two options for submitting e-commerce orders:

  • Standard option no document attached to shipment

  • “Old” option packing slip or invoice included with shipment

The entire set for the standard data exchange with CB consists of the following documents and files:

File versus webservice. Communication about orders is based on the receiving channel, i.e. file base communication is used for orders received via file based interfaces and webservice communication is used for orders received via the webservice MediaOrderB2C. Order are processed independent from the receiving channel

The mapping from file based to webservice based messages

File based

Webservice operation

OPDNAW

placeOrder

ANNOPD

cancelOrder

UITOPD

notifyOrder / getOrderStatus + notifyShipment / getShippingUnit

NUITOP

notifyOrder / getOrderStatus

Migration strategy from batch file to webservice

Suggested migration strategy from batch file to webservice:

  • Verify technical and functional process with a live connection to the CB test environment.

  • Arrange for shadow-run(s) in a combination of production and test environments,, i.e. send an OPDNAW message to the CB production environment, extract a few orders and send them via the webservice to the CB test environment. CB can verify the received data in the test environment against the production data from the OPDNAW.

  • Arrange for go-live date

  • Send a limited number of orders via the webservice to the CB production environment. CB can monitor the processing of these orders.

  • Verify the information in the order status and shipping unit operations.

  • Step-by-step increase the webservice load until the required level is reached.

  • If applicable then disable the file based flow.

Authentication & Authorisation

MediaOrderB2C and Shipment

Header-parameters "Username" + "Password"  

Webservice information

Webservice approache

REST - Representational State Transfer

MediaOrderB2C

OpenAPI Specification

Resource

Orders

Operations provided by CB:

placeOrder

Send one (1) order to CB

cancelOrderLine

Cancel one (1) orderline

getOrderStatus

Retrieve the status if one (1) order

MediaOrderNotify

OpenAPI Specification

Resource: 

Notifications

Operations provided by you:

notifyOrder

CB calls your webservice to inform you about status updates of an order

Authentication mode

CB supports:

  • Basic - username:password   “Basic ”||"Base64 encoding of username and password joined by a single colon : "

  • Token 

MediaShipment

Definition

Resource

ShippingUnits

Operations provided by CB:

getShippingUnit

Retrieve the shipment information for a shipping unit

MediaShipmentNotify

Definition: 

Resource: 

Notifications

Operations provided by you:

notifyShipment

CB calls your webservice to inform you about shipment for your order

Authentication mode

CB supports:

  • Basic - username:password   “Basic ”||"Base64 encoding of username and password joined by a single colon : "

  • Token 

Content type

The content /body in the request and response has to be, will be in json format

‘Optional’ parameter

For any optional Attribute ons of th following options applies:

  • be filled with the correct value

  • be left out

  • be filled with ““ (read empty)

An optional parameter may therefore never be filled with the value null

Attribute name

Attribute names are case sensitive in accordance with the YAML file

URL Test

 

MediaOrderB2C base: https://media.tst.cb-api.nl/mediaorderb2c

MediaShipment base:  https://media.tst.cb-api.nl/mediashipment

URL Production

 

MediaOrderB2C base: https://media.cb-api.nl/mediaorderb2c

MediaShipment base: https://media.cb-api.nl/mediashipment

Supported SSL/TLS protocols

TLS 1.2

TLS 1.3

Overview webservices

This chapter gives an overview of the available interaction patterns for data exchange with CB. The figure below gives an high level overview of the CB system landscape and the available webservice operations.

MoB2C_Overview_webservices.jpg

The webservices provide online creation and cancelation of media orders at CB. Changes to an order (other than cancel) are not available. Resending an order is possible only when the order was not accepted by CB earlier. 

Operations

Order - placeOrder

The operation placeOrder supports sending one order for a customer. An order can contain multiple orderlines, each for a specific title. Confirmation of the operation is provided with a http-response-code.

Check order identification (Requestor Order Id)

The identification of an order is used to check if an order already exists in the CB systems. If this is the case the new order is rejected. Only open orders are taken into account, so closed/cancelled orders are ignored.

Order type

The operation is available for order types ShipBuyer (LNAFN), ShipOwner (LNEIG) and ShipSecundaryOwner (LMEONE).

Sender and Owner

In the common scenario for media orders the sender requests CB to ship titles owned by a publisher to a consumer. This scenario identifies the publisher as owner, the sender (shop) as buyer from the owner and the consumer as receiver (and buying from the shop). An alternative scenario is secondary ownership, in this alternative scenario the sender (shop) already purchased titles from the publisher and requests CB to ship from its own stock.

Party

Because parties where goods have to be delivered are not known by CB the PartyType “ReceiverAddress,” is mandatory and all name and address information must be provided.

Values added services (VAS)

VAS activities can be controlled by means of special handling instructions for the order.

Examples of instructions:

  • Wrap the books in gift paper

  • Add leaflet to the package

Available special handling instructions must be agreed upon in advance by requestor and CB.

Order - cancelOrderLine

The operation cancelOrderLine supports cancellation of one orderline. Cancellation is available until the orderline is released for production (“vrijgegeven”). Confirmation of the operation is provided with a http-response-code. The operation requires the OrderId and OrderLineId as input and is available for orders entered via webservices only.

Order - getOrderStatus

When the status of an order or orderline is changed a notifyOrder message is sent. This is the preferred trigger to call the operation getOrderStatus.

The operation getOrderStatus provides the status summary of the requested order. An order can contain multiple orderlines, each for a specific product. The status of every orderline is reported separately. An orderline can also be reported in multiple statuses, for instance when part of the quantity is available and ready for production and the remaining quantity is in backorder. If (a part of) the order is not delivered, the status includes an explanation why.

The operation requires the OrderId as input and available for orders entered via webservices only.

Available statuses for notifyOrder:

  • New Order is accepted after being received during the service window

  • InProgress Order(line) passed validation

  • ProductionReady Order(line) is ready for pick/pack in warehouse

  • Warning Order processing started with an issue for at least one orderline

  • Processed Order is finished with shipment

  • Cancelled Order is finished without shipment

Shipment - getShippingUnit

When a shipment is ready to be shipped a notifyShipment message is sent per available shipping unit. The operation getShippingUnit provides the contents of the shipping unit and the relation to order and orderlines. An order can be shipped in multiple shipping units.

The operation requires the ShippingUnitId as input.

Available statuses for notifyShipment:

  • Processed ShippingUnit is ready for shipping

Response messages

For the error handling of reports applies:

  • All syntactic errors are no longer reported with a separate code, but with error code CEP-002, with further details in the description.

  • authentication errors are reported using CEP-003.

  • the more substantive/processing errors, which are not covered by the above, are unchanged

MediaOrderB2C

MediaOrderB2C

HTTP code

Error code

Description/Message

getOrderStatus

placeOrder

cancelOrderLine

200

 

Request executed

 

 

204

 

Request executed

 

206

 

Request executed with pending status

 

400

 

Request failed

 

401

 

Not authorised

404

 

Order not found

HTTP code

Error code

Description/Message
The list of error codes within these groups may change in time without notice

getOrderStatus

placeOrder

cancelOrderLine

CEP-***

CEP-002

The request does not comply with the yaml definition; Value is not one of the possible/allowed values

[instance value (\"1234567890\") not found in enum (possible values: [\"SecundaryOwnerStock\",\"SecundaryOrPrimary\",\"PrimaryOwnerStock\",\"PrimaryOrSecundary\"]), format attribute \"decimal\" not supported, format attribute \"int32\" not supported]

 

 

CEP-002

The request does not comply with the yaml definition; Value does not meet regex

[ECMA 262 regex \"^[^#]*$\" does not match input string \"#\", format attribute \"int32\" not supported]

 

 

CEP-002

The request does not comply with the yaml definition; Value does not meet set minimum or maximum value

[numeric instance is lower than the required minimum (minimum: 6000000, found: 123), format attribute \"decimal\" not supported, format attribute \"int32\" not supported]

 

 

CEP-003

Authentication/Authorisation error

You are not authenticated

 

 

WMO-***

WMO-00503

The request encountered a mapping error, mainly due to incorrect shipment date(s); Delivery period and delivery date cannot both be given

If Delivery is specified, then either DeliveryDate or DeliveryPeriod must be supplied

 

 

WMO-00508

The request encountered a mapping error, mainly due to incorrect shipment date(s); Date must be in the future

The DeliveryDate is in the past

 

 

WMO-00509

The request encountered a mapping error, mainly due to incorrect shipment date(s); Invalid date

Invalid date for Delivery/DeliveryPeriod/Till: <Submitted ShipmentPeriod.Till> compared to Delivery/DeliveryPeriod/From <Submitted ShipmentPeriod.From>

 

 

WMO-00510

The request encountered a mapping error, mainly due to incorrect shipment date(s); Date must be in the future

The Delivery/DeliveryPeriod/From is in the past

 

 

WMO-00511

The request encountered a mapping error, mainly due to incorrect shipment date(s); Date must be in the pastThe