Guides

Orders API overview

Suggest Edits

🚧

Our Orders API will be replaced with a full-featured Payments API

We no longer recommend implementing the Orders API. Please refer to the Payments API instead. We are actively working on adding support for Klarna, Billie, in3 and Vouchers to the Payments API later this year

The Orders API allows you to use Mollie for your order management.

For each order in your shop, you can create an order via the Mollie API. The order will remain valid for a certain amount of time (default 28 days).

Just as a regular payment, the order will have a _links.checkout property where you can redirect your customer to pay for the order. For each attempt to pay, a payment object is created. If the customer pays for the order, the order will transition to the paid state (or authorized in case of Klarna payment methods).

Should the initial payment fail, the order remains in the created state so that your customer can try to pay again. This can be done using a dedicated link available through the Dashboard which you can share with your customer, or you can create an additional payment on the order via the API.

Once you ship the goods to your customer, you should inform Mollie of the shipments via the API or via the Dashboard. This is mandatory for pay-after-delivery methods. Only shipped amounts will be settled to your account.

The following payment methods require the Orders API and cannot be used with the Payments API:

  • Pay after delivery payment methods, such as Klarna Pay later, Klarna Slice it and Billie
  • Klarna Pay now
  • Eco vouchers, gift vouchers, and meal vouchers

How does the Orders API work?

  1. A customer on your webshop decides to checkout.
  2. For every order in your webshop, you create an order using the Create order endpoint.
  3. The Create order endpoint response contains the _links.checkout property. This is a link where you should redirect your customer to for checking out.
  4. If the checkout is successful, the order will change its state to authorized or paid, depending on the payment method used by your customer.

We will use webhooks to inform your back office of the order state change.

  1. Processing the webhook request your website fetches the order status using the Mollie API. This fetched status serves to mark the payment paid, trigger fulfilment and send out an email confirmation to the customer.
  2. At this point Mollie returns the visitor to your website using the redirectUrl specified when the order was created. Your website already knows the payment was successful and thanks the customer.
  3. When the order is paid or authorized you can ship the order to your customer.
  4. Once you start shipping the order, you should send the shipment information to Mollie using the Create shipment endpoint. Alternatively, you can use the Mollie Dashboard. You should ship the order within 28 days or the order will expire.

For some payment methods, shipping is required to ensure you will be settled for the full order amount.

We will use webhooks to inform your back office that a shipment was created.

  1. Processing the webhook request your website fetches the order status using the Mollie API. You can check if a shipment has created and process this in your own system, if desired.

Cancel order lines

If there are some lines in the order you will not ship, you can cancel them using the Cancel order lines endpoint if they are authorized or you can create refunds if the lines are already paid.

Order expiry

An order expires after 28 days. Any authorizations on the order will be released. You can check the expiresAt property on the order or in the Mollie Dashboard to see when the order expires exactly.

Updated 21 days ago