Create order

post https://api.mollie.com/v2/orders

⚠️ 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.

When creating an order, a payment will automatically be created to allow your customer to pay for the order. You can then redirect your customer to the URL in the _links.checkout property from the response, similar to the Payments API.

Unlike the Payments API, if a payment fails, expires, or is canceled, you can create a new payment under the same order using the Create order payment endpoint. This is only possible for orders that still have the created status.

🔑
Access with
API key
Access token with orders.write

Query Params

embed

string | null

This endpoint allows embedding related API items by appending the following values via the embed query string parameter.

payments: Include all payments created for this order.

Body Params

orderNumber

string

required

The order number for this order. We recommend each order number to be unique.

lines

array of objects

required

The order lines for the order. Each line contains details such as a description of the item ordered and its price.

All lines must have the same currency as the payment.

lines*

amount

object

required

The amount that you want to charge, e.g. {currency:"EUR", value:"1000.00"} if you would want to charge €1000.00.

You can find the minimum and maximum amounts per payment method in our help center. Additionally, they can be retrieved using the Get method endpoint.

redirectUrl

string | null

The URL your customer will be redirected to after the payment process.

It could make sense for the redirectUrl to contain a unique identifier – like your order ID – so you can show the right page referencing the order when your customer returns.

The parameter is normally required, but can be omitted for recurring payments (sequenceType: recurring) and for Apple Pay payments with an applePayPaymentToken.

cancelUrl

string | null

The URL your customer will be redirected to when the customer explicitly cancels the payment. If this URL is not provided, the customer will be redirected to the redirectUrl instead — see above.

Mollie will always give you status updates via webhooks, including for the canceled status. This parameter is therefore entirely optional, but can be useful when implementing a dedicated customer-facing flow to handle payment cancellations.

webhookUrl

string | null

The webhook URL where we will send order status updates to.

The webhookUrl is optional, but without a webhook you will miss out on important status changes to your order.

The webhookUrl must be reachable from Mollie's point of view, so you cannot use localhost. If you want to use webhook during development on localhost, you must use a tool like ngrok to have the webhooks delivered to your local machine.

billingAddress

object

required

The customer's billing address details. The billing address is required, unless a fast checkout method like PayPal Express Checkout is providing the billing address.

shippingAddress

object

The customer's shipping address details. We advise to provide these details to improve fraud protection and conversion. This is particularly relevant for card payments.

locale

string

required

Allows you to preset the language to be used in the hosted payment pages shown to the customer. Setting a locale is highly recommended and will greatly improve your conversion rate. When this parameter is omitted the browser language will be used instead if supported by the payment method. You can provide any xx_XX format ISO 15897 locale, but our hosted payment pages currently only support the specified languages.

For bank transfer payments specifically, the locale will determine the target bank account the customer has to transfer the money to. We have dedicated bank accounts for Belgium, Germany, and The Netherlands. Having the customer use a local bank account greatly increases the conversion and speed of payment.

Possible values: en_US en_GB nl_NL nl_BE fr_FR fr_BE de_DE de_AT de_CH es_ES ca_ES pt_PT it_IT nb_NO sv_SE fi_FI da_DK is_IS hu_HU pl_PL lv_LV lt_LT

method

string | null

Normally, a payment method screen is shown. However, when using this parameter, you can choose a specific payment method and your customer will skip the selection screen and is sent directly to the chosen payment method. The parameter enables you to fully integrate the payment method selection into your website.

You can also specify the methods in an array. By doing so we will still show the payment method selection screen but will only show the methods specified in the array. For example, you can use this functionality to only show payment methods from a specific country to your customer ['bancontact', 'belfius'].

Possible values: applepay bancomatpay bancontact banktransfer belfius billie creditcard directdebit eps giftcard ideal in3 kbc klarna klarnapaylater klarnapaynow klarnasliceit mybank paypal paysafecard przelewy24 riverty satispay trustly twint voucher

shopperCountryMustMatchBillingCountry

boolean

For digital goods, you must make sure to apply the VAT rate from your customer's country in most jurisdictions. You can use this parameter to restrict the payment methods available to your customer to methods from the billing country only.

This field is similar to the restrictPaymentMethodsToCountry field in the Payments API.

metadata

payment

object | null

Any payment specific properties (for example, the dueDate for bank transfer payments) can be passed here. See method-specific parameters for all the possible fields.

profileId

string | null

The identifier referring to the profile this entity belongs to.

Most API credentials are linked to a single profile. In these cases the profileId can be omitted in the creation request. For organization-level credentials such as OAuth access tokens however, the profileId parameter is required.

expiresAt

string | null

The date the order should expire in YYYY-MM-DD format. The minimum date is tomorrow and the maximum date is 100 days after tomorrow.

It is not possible to use Klarna when your expiry date is more than 28 days in the future, unless you agreed on a different maximum with Klarna.

testmode

boolean | null

Defaults to false

Whether to create the entity in test mode or live mode.

Most API credentials are specifically created for either live mode or test mode, in which case this parameter can be omitted. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting testmode to true.

Responses

Language

Credentials

Request


xxxxxxxxxx
48
    -d "lines[1][productUrl]=https://shop.lego.com/nl-NL/Porsche-911-GT3-RS-42056" \
1
curl -X POST https://api.mollie.com/v2/orders \
2
    -H "Content-Type: application/json" \
3
    -H "Authorization: Bearer live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" \
4
    -d "orderNumber=34629" \
5
    -d "lines[0][type]=physical" \
6
    -d "lines[0][name]=LEGO 42083 Bugatti Chiron" \
7
    -d "lines[0][quantity]=2" \
8
    -d "lines[0][vatRate]=21.00" \
9
    -d "lines[0][unitPrice][currency]=EUR" \
10
    -d "lines[0][unitPrice][value]=399.00" \
11
    -d "lines[0][totalAmount][currency]=EUR" \
12
    -d "lines[0][totalAmount][value]=698.00" \
13
    -d "lines[0][discountAmount][currency]=EUR" \
14
    -d "lines[0][discountAmount][value]=100.00" \
15
    -d "lines[0][vatAmount][currency]=EUR" \
16
    -d "lines[0][vatAmount][value]=121.14" \
17
    -d "lines[0][sku]=5702016116977" \
18
    -d "lines[0][productUrl]=https://shop.lego.com/nl-NL/Bugatti-Chiron-42083" \
19
    -d "lines[0][imageUrl]=https://sh-s7-live-s.legocdn.com/is/image/LEGO/42083" \
20
    -d "lines[1][type]=physical" \
21
    -d "lines[1][name]=LEGO 42056 Porsche 911 GT3 RS" \
22
    -d "lines[1][quantity]=1" \
23
    -d "lines[1][vatRate]=21.00" \
24
    -d "lines[1][unitPrice][currency]=EUR" \
25
    -d "lines[1][unitPrice][value]=329.99" \
26
    -d "lines[1][totalAmount][currency]=EUR" \
27
    -d "lines[1][totalAmount][value]=329.99" \
28
    -d "lines[1][vatAmount][currency]=EUR" \
29
    -d "lines[1][vatAmount][value]=57.27" \


xxxxxxxxxx
124
}
1
{
2
  "resource": "order",
3
  "id": "ord_pbjz8x",
4
  "mode": "live",
5
  "orderNumber": "34629",
6
  "lines": [
7
    {
8
      "resource": "orderline",
9
      "id": "odl_dgtxyl",
10
      "type": "physical",
11
      "name": "LEGO 42083 Bugatti Chiron",
12
      "quantity": 2,
13
      "vatRate": "21.00",
14
      "unitPrice": {
15
        "currency": "EUR",
16
        "value": "399.00"
17
      },
18
      "totalAmount": {
19
        "currency": "EUR",
20
        "value": "698.00"
21
      },
22
      "discountAmount": {
23
        "currency": "EUR",
24
        "value": "100.00"
25
      },

201The newly created order object. For a complete reference of the order object, refer to the Get order endpoint documentation.

422The request contains issues. For example, if the order number is missing, or if the specified amount is higher than the maximum allowed amount.