Orders API

Create order

⚠️ We no longer recommend using the Orders API. Please refer to the Payments API instead.

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

Advanced access token with orders.write

OAuth access with orders.write

post/orders

Request

Base URL
https://api.mollie.com/v2
URL
https://api.mollie.com/v2/orders
Auth
- HTTP bearer
- or HTTP bearer
- or OAuth 2
  Authorization code: https://my.mollie.com/oauth2/authorize
  Token URL: https://api.mollie.com/oauth2/tokens scopes: orders.write

Query parameters

embed'payments' | 'refunds' | 'shipments'

Example:payments

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

Request body

resourcestring

Indicates the response contains an order object. Will always contain the string order for this endpoint.

idstring

The identifier uniquely referring to this order. Mollie assigns this identifier at payment creation time. Mollie will always refer to the order by this ID. Example: ord_vsKJpSsabw.

modestring

Whether this entity was created in live mode or in test mode.

Possible values: live test

orderNumberstring required

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

redirectUrlstring nullable

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.

cancelUrlstring

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.

webhookUrlstring

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.

localestring 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: ca_ES cs_CZ da_DK de_AT de_CH de_DE de_LU el_GR en_BE en_GB en_NL en_US es_ES fi_FI fr_BE fr_FR fr_LU hu_HU is_IS it_IT lt_LT lv_LV nb_NO nl_BE nl_NL pl_PL pt_PT sk_SK sl_SI sv_SE tr_TR

methodstring nullable

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

shopperCountryMustMatchBillingCountryboolean

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.

statusstring

The order's status. Refer to the documentation regarding statuses for more info about which statuses occur at what point.

Possible values: created pending authorized paid shipping canceled expired completed

isCancelableboolean

Whether the order can be canceled. This parameter is omitted if the order reaches a final state.

profileIdstring

The identifier referring to the profile this entity belongs to.

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

createdAtstring

The entity's date and time of creation, in ISO 8601 format.

authorizedAtstring

The date and time the order became authorized, in ISO 8601 format. This parameter is omitted if the order is not authorized (yet).

paidAtstring

The date and time the order became paid, in ISO 8601 format. This parameter is omitted if the order is not completed (yet).

canceledAtstring

The date and time the order was canceled, in ISO 8601 format. This parameter is omitted if the order is not canceled (yet).

expiresAtstring

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.

expiredAtstring

The date and time the order was expired, in ISO 8601 format. This parameter is omitted if the order did not expire (yet).

completedAtstring

The date and time the order was completed, in ISO 8601 format. This parameter is omitted if the order is not completed (yet).

consumerDateOfBirthstring

The date of birth of the consumer in YYYY-MM-DD format.

testmodeboolean nullable

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 must not be sent. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting testmode to true.

Example request

{
  "id": "ord_5B8cwPMGnU",
  "mode": "live",
  "amount": {
    "currency": "EUR",
    "value": "10.00"
  },
  "amountRefunded": {
    "currency": "EUR",
    "value": "10.00"
  },
  "amountCaptured": {
    "currency": "EUR",
    "value": "10.00"
  },
  "redirectUrl": "https://www.example.com/redirect",
  "cancelUrl": "https://www.example.com/cancel",
  "webhookUrl": "https://www.example.com/webhook",
  "billingAddress": {
    "title": "Mr.",
    "givenName": "John",
    "familyName": "Doe",
    "organizationName": "Mollie B.V.",
    "streetAndNumber": "Keizersgracht 126",
    "streetAdditional": "4th floor",
    "postalCode": "5678AB",
    "email": "example@email.com",
    "city": "Amsterdam",
    "region": "Noord-Holland",
    "country": "NL"
  },
  "shippingAddress": {
    "title": "Mr.",
    "givenName": "John",
    "familyName": "Doe",
    "organizationName": "Mollie B.V.",
    "streetAndNumber": "Keizersgracht 126",
    "streetAdditional": "4th floor",
    "postalCode": "5678AB",
    "email": "example@email.com",
    "city": "Amsterdam",
    "region": "Noord-Holland",
    "country": "NL"
  },
  "locale": "en_US",
  "method": "creditcard",
  "shopperCountryMustMatchBillingCountry": true,
  "status": "created",
  "isCancelable": true,
  "profileId": "pfl_5B8cwPMGnU",
  "createdAt": "2024-03-20T09:13:37+00:00",
  "authorizedAt": "2025-04-03T14:03:17+00:00",
  "paidAt": "2025-04-03T14:03:17+00:00",
  "canceledAt": "2025-04-03T14:03:17+00:00",
  "expiresAt": "2025-01-01",
  "expiredAt": "2025-04-03T14:03:17+00:00",
  "completedAt": "2025-04-03T14:03:17+00:00",
  "consumerDateOfBirth": "2000-01-01",
  "lines": [
    {
      "id": "odl_5B8cwPMGnU",
      "type": "physical",
      "name": "Ready Player One",
      "quantity": 2,
      "quantityShipped": 1,
      "amountShipped": {
        "currency": "EUR",
        "value": "10.00"
      },
      "quantityRefunded": 1,
      "amountRefunded": {
        "currency": "EUR",
        "value": "10.00"
      },
      "quantityCanceled": 1,
      "amountCanceled": {
        "currency": "EUR",
        "value": "10.00"
      },
      "shippableQuantity": 1,
      "refundableQuantity": 1,
      "cancelableQuantity": 1,
      "unitPrice": {
        "currency": "EUR",
        "value": "10.00"
      },
      "discountAmount": {
        "currency": "EUR",
        "value": "10.00"
      },
      "totalAmount": {
        "currency": "EUR",
        "value": "10.00"
      },
      "vatAmount": {
        "currency": "EUR",
        "value": "10.00"
      },
      "sku": "978-1524763282",
      "category": "eco",
      "status": "created",
      "isCancelable": true,
      "orderId": "ord_5B8cwPMGnU",
      "imageUrl": "https://www.example.com/image",
      "productUrl": "https://www.example.com/product",
      "createdAt": "2024-03-20T09:13:37+00:00",
      "_links": {
        "self": {
          "href": "https://...",
          "type": "application/hal+json"
        },
        "imageUrl": {
          "href": "https://...",
          "type": "application/hal+json"
        },
        "productUrl": {
          "href": "https://...",
          "type": "application/hal+json"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "checkout": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "dashboard": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "documentation": {
      "href": "https://...",
      "type": "application/hal+json"
    }
  }
}

Response

The newly created order object.