# Order

An object representing an order. A cart is an unfinished order.

# Properties

Property	Type	Description
uid	integer	The unique indentifier of the order.
orderNumber	string	Webshop specific order identifier.
ordered	string	Date and time of the order, if placed.
changed	string	Date and time of when the order was last modified.
customer	Customer	The personal details of the customer broken down into the subobjects 'address', 'deliveryAddress' and 'info'.
currency	string	The currency of the order as a three-letter ISO 4217 code which is used in the Costs objects.
exchangeRate	number	Exchange rate of the currency of the order to the base currency of the shop at the time of when the order was placed. Available to administrators only. If, for instance, the base currency is `EUR` and the order currency is `USD` and assuming that 1 EUR = 1.29 USD, then the exchange rate of the order will be `1.29`.
items	array	The unique identifiers of the OrderItems as an array.
costs	Costs	The cost details of the order broken down into the subobjects 'cart', 'payment', 'shipment' and aggregated into 'total'.
language	string	The language of the order as a two-letter ISO 639-1 code, e.g. 'sv'.
note	string	An optional note by the administrator, e.g. `"Double check the serial number before shipment"`.
tags	array	A list of all tags on the order, set by an administrator.
externalOrderNumber	string	Order number used in external systems such as accounting software.
discarded	boolean	Whether the order has been cancelled by the administrator.
hasVat	boolean	Whether the order contains value-added tax.
payments	array	The Payments by the customer as an array. An order can be paid in one or more transactions, e.g. as a single card payment, or, in the case of a payment plan, split up in multiple invoices.
delivery	Delivery	Delivery details including 'method' (but excluding delivery status).
paymentStatus	string	The payment status of the order, e.g. `"paid"` or `"unpaid"`.
deliveryStatus	string	The delivery status of the order, e.g. `"sent"` or `"unsent"`.
affiliate	integer	UID of an affiliate partner.
discountInfo	DiscountInfo	Discount information for an order, if a discount is applied.

# Costs

These are the properties for the costs object:

Property	Type	Description
cart	object	The costs of the articles added to cart excluding any payment and shipment fees.
payment	object	The fee of the selected payment method, if any.
shipment	object	The fee of the selected shipment method, if any.
total	object	The total amount of the order, i.e. the sum of cart, payment and shipment.

In turn, the above objects have the following properties:

Property	Type	Description
exVat	number	The amount excluding value-added tax.
incVat	number	The amount including value-added tax.
vat	number	Value-added tax of the order.
vatRate	number	Value-added tax rate of the order as a decimal number, e.g. `0.12` for 12%.
currency	string	The currency used for this cost.

# Customer

These are the properties for the customer object.

Note that the following grouping of customer details and their contents exist independently of whether a registered customer is connected with the order.

Property	Type	Description
address	object	The address and contact details of the customer. See 'address' below.
customer	integer	The unique identifier of the customer, if any. This 'customer' property inside the 'customer' object exists only if the order is created by a registered customer and then refers to the personal details stored in the customer register. The latter are accessible with the method Customer.get and can be changed by a logged-in customer, as opposed to the details connected with the order.
comment	string	An optional comment by the customer, e.g. `"I will be away until 21 February so please don't deliver the goods until then."`
deliveryAddress	object	The address to which the order shall be sent. See 'deliveryAddress' below.
info	object	Additional details of the customer, e.g. customer type. See 'info' below.

# Address

The 'address' subobject has the following properties:

Property	Type	Description
address	string	Address line 1 of the customer, e.g. street name and number.
address2	string	Additional address details, such as apartment, suite or building.
country	string	Country of residence of the customer.
firstName	string	First name of the customer.
lastName	string	Last name of the customer.
phoneDay	string	Daytime phone number of the customer.
phoneMobile	string	Mobile phone number of the customer.
postcode	string	Postcode of the customer.
state	string	State or province of the customer, e.g. `"AL"` (Alabama), if any.
town	string	Post town of the customer.

# DeliveryAddress

The 'deliveryAddress' subobject has the following properties:

Property	Type	Description
company	string	Delivery company name, if any.
name	string	Delivery name
address	string	Delivery address line 1, e.g. street name and number.
address2	string	Additional delivery address details, such as apartment, suite or building, if any.
country	string	Delivery country of the customer.
postcode	string	Delivery postcode
town	string	Delivery city
state	string	Delivery state or province, e.g. `"AL"` (Alabama), if any.
phone	string	Delivery phone number
copyAddress	boolean	Whether the delivery address should be copied from the address.

# Info

The 'info' subobject has the following properties:

Property	Type	Description
email	string	Email address of the customer.
nin	string	National identification number or organization number of the customer, if any.
type	string	Customer type (`"business"` or `"individual"`).

# Delivery

These are the properties for the delivery object:

Property	Type	Description
method	integer	The unique identifier of the DeliveryMethod.
params	object	Parameters for the delivery method.

# DiscountInfo

These are the properties for the discountInfo object:

Property	Type	Description
name	string	Discount name.
discount	integer	The unique identifier of the Discount.
type	string	The type of discount.
exVat	number	The amount excluding value-added tax.
incVat	number	The amount including value-added tax.
vatRate	number	Value-added tax rate of the discount as a decimal number, e.g. `0.12` for 12%.
vat	number	Value-added tax of the discount.
rate	number	@TODO

# Methods

# addArticle

Adds an article to the order. The Article's choices are sent as an object, according to the choiceSchema you can get from the Article. Example: One common choice existing for most articles is 'quantity'.

# Parameters

Parameter	Type	Description
order	integer	The unique identifier of an Order or `null` to create a new order.
article	integer	The unique identifier of an Article.
choices	object	An object containing choices, according to the Article's choiceSchema.
query	mixed	Query passed to get on the created item, for return value. Defaults to all. See Query language.

# Returns

Data based on the query parameter, from the OrderItem that is created.

# Example

To create a new order by directly adding an article, and fetching the created Order, you can get the unique identifier of the Order from the created OrderItem. This example assumes that Webshop is set in the context of the request.

API Console
PHP
JSON
Response

Order.addArticle(null, 1234567, {
  "quantity": 1
}, {
  "order": "uid"
})

# addDiscountCode

Applies a discount code to the order.

# Parameters

Parameter	Type	Description
code	string	The discount code.
query	mixed	What to return; defaults to nothing.

# Errors

Code	Message	Description
2030	Discount code already specified	With the code as data.
2031	Invalid discount code	With the code as data.
2032	Discount code offers no additional discount	With the code as data.

# Returns

Order data based on the query parameter.

# addGiftCertificate

Adds a gift certificate to the order. If a payment method has already been selected (using setPaymentMethod) the remaining value of the gift certificate is checked against the order total. If the remaining value is greater than or equal to the order total, then all previously selected payment methods will be replaced by the gift certificate. If the remaining value of the gift certificate is less than the order total, then the gift certificate will deduct its remaining value from the previously selected payment method.

Note that some payment methods cannot be combined with a gift certificate. If such a method is selected before calling this method, the latter will throw a 2051 error (see below).

# Parameters

The gift-certificate code as a string.

# Errors

Code	Message
2050	Invalid gift certificate
2051	Uncombinable with selected payment method

# addressLookup

Takes an address lookup schema and returns an array of addresses.

# Parameter object

Parameter	Description
JSON object	Address matching the schema from getAddressLookupSchema.

# Example

API Console
PHP
JSON

Order.addressLookup({
  "nin": "123456789",
  "postcode": "41264"
})

# Returns

Object	Type	Description
addresses	object	Addresses matching the lookup parameters.

# Errors

Code	Message	Description
2040	Address lookup unavailable	No planned payments support address lookup.
9001	Validation error	An array of validation-error objects, each containing the keys `pointer` (a property referenced using a JSON Pointer) and `message` (a readable text in the language of the context). If there are no validation errors, then an empty array is returned.

# checkout

Performs the actual checkout. This places the order and carries out the payment. Please note that certain payments will require a second step to be completed. See continueCheckout.

Make sure to check the redirect field in returned state.

When the browser arrives at the returnUrl, check status/messages with <checkCheckout>.

# Parameter object

Parameter	Description
returnUrl	URL to which the user is returned after an external payment has succeeded.

# Returns

Property	Type	Description
done	boolean	Whether the payment is fully completed.
redirect	string	URL to which the end user is returned, if a `redirect` property is present.

# Errors

Code	Message	Description
2010	Payment failed	When the payment provider says that the payment has failed. The data is a message from the provider as a string.
2011	Payment not configured	When trying to perform checkout without matching planned payments.
2012	Payment unavailable	The order cannot be paid (needs payment but no payment method is available to the customer).
2013	Insufficient purchase amount	The shop accepts orders only above a certain purchase amount.
2020	Delivery not configured	When trying to perform checkout without having configured delivery.
2021	Delivery unavailable	The order cannot be delivered (needs delivery but no delivery method is available).
2080	Creditsafe check failed	When failing a Creditsafe lookup during checkout (if active)
9001	Validation error	The order is missing mandatory information needed for checkout.

# get

Fetches information about an order.

# Parameters

Parameter	Description
uid	The unique identifier of an order.
query	Which info to return. See Query language.

# Example

API Console
PHP
JSON
Response

Order.get(12345678, [
  "uid",
  "currency",
  "language",
  "items",
  "costs",
  "paymentStatus",
  "delivery",
  "deliveryStatus"
])

# getAvailableDeliveryMethods

Fetches a list of available delivery methods for the order in the current session. This may change whenever the order is modified (e.g. cost or country).

# Returns

An array containing DeliveryMethod specifications (ordered by preferred display positions). "fee" only occurs if there is a fee for the delivery method in question. "parameters" is a schema with additional settings for the delivery method, e.g. selection of pick-up location, and that should be included in the call to setDeliveryMethod.

Each specification contains the following:

{
  "uid": 3456,
  "title": "My delivery method",
  "description": "A <em>description</em>, possibly containing <strong>HTML</strong> code.",
  "parameters": {},
  "fee": {
    "exVat": 8,
    "incVat": 10,
    "vat": 2
  }
}

# getAvailablePaymentMethods

Fetches a list of payment methods available for the order in the current session. This specification may change whenever the order is changed (e.g. cost, currency, or country).

# Returns

An array of PaymentMethod specifications (ordered by the preferred display position). A "fee" only occurs if there is a fee for the payment method in question. "parameters" is a schema with additional settings to be made for the payment transaction, e.g. the selection of a payment plan, and that should be given to setPaymentMethod.

If "isCombinable" is true it means that the payment method can be combined with other payment methods, otherwise the payment method can only be used on its own.

The specification contains the following:

{
  "uid": 1234,
  "title": "My paymethod",
  "description": "A <em>description</em>, possibly containing <strong>HTML</strong> code.",
  "allowedCurrencies": [
    "SEK",
    "NOK"
  ],
  "parameters": {},
  "fee": {
    "exVat": 8,
    "incVat": 10,
    "vat": 2
  },
  "isCombinable": true
}

# getAddressLookupSchema

Returns the address lookup schema for the first planned payment that supports address lookup.

# Parameters

Parameter	Description
uid	The unique identifier of the order.

# Returns

JSON Schema describing the fields required for performing address lookup.

# Example

# JSON

{
  "properties": {
    "nin": {
      "type": "string"
    },
    "postcode": {
      "type": "string"
    }
  },
  "required": [
    "nin"
  ]
}

# Errors

Code	Message	Description
2040	Address lookup unavailable	No planned payments support address lookup.

# getCartMessages

After interacting with a cart, for example adding or changing the quantity of an item, getCartMessages should be called. The method returns a message in the specified context language. Messages can be anything related to a cart but usually they concern the stock. These messages are intended for the end user.

# Example

Request below follows an addArticle request for "id": 234141, "quantity": 2.

API Console
PHP
JSON
Response

Order.getCartMessages()

# getCheckoutHtml new

NEW

This API method is new, that unfortunately means it does not yet have any documentation.

# getCheckoutSchema

Fetches a JSON Schema with fields required for checkout marked as required, and fields that shouldn't be shown removed. This schema is compatible with the full Order schema but can be used to validate whether the Order is ready to be checked out.

# getCheckoutState new

NEW

This API method is new, that unfortunately means it does not yet have any documentation.

# getCheckoutStatus

Returns the object with any of these properties:

Property	Description
done	Whether the payment is fully completed.
status	String, e.g. 'new', 'done', 'should_redirect', or 'error'.
error	A JSON-RPC 2.0 error object, if any.

# getKcoHtml deprecated

DEPRECATED

This API method is deprecated. Use getCheckoutHtml instead.

Returns HTML representing an IFRAME object used for performing a checkout process using Klarna Checkout (opens new window). Klarna Checkout must be set as the current payment method (using setPaymentMethod) before calling this method, otherwise an error will be thrown.

# Parameters

Type	Property	Description
integer	order	The unique identifier of an order.
string	returnUrl	The page to redirect to after checkout is complete.

# Errors

Code	Message	Description
2010	Payment failed	With a message from Klarna Checkout stating why.

# getSchema

Fetches the JSON Schema which can be used for client-side validation.

# Parameters

Parameter	Description
uid	The unique identifier of an order.

# getShipmentInformation

# Parameters

The unique identifier of the order.

# Returns

A list of shipment information for the order if the request is done with a logged in user allowed to review the order, such as the customer who created it.

# getShipments

Get all shipments for an order. See Shipment.

# Parameters

Parameter	Description
uid	The unique identifier for the order.
query	Which info to return. See Query language.

# list

Fetches multiple orders as an array of order objects.

# Parameters

Parameter	Description
query	Which info to return. See Query language.
selection	Which orders to list. See List selection.

# Filter aliases:

webshop
ordered

# Orderings:

ordered
company
currency
firstName
lastName
paid
sent
uid

# Example

The following request returns the currency and cart cost excluding VAT of all the orders placed ("ordered") since 1 January 2014:

API Console
PHP
JSON
Response

Order.list({
  "costs": {
    "cart": {
      "exVat": true,
      "currency": true
    }
  }
}, {
  "filters": {
    "/ordered": {
      "min": "2014-01-01T00:00:00Z"
    }
  }
})

# set

Creates or updates an order.

# Parameters

Parameter	Description
uid	The unique identifier of an article or `null` to create a new order.
patch	An object containing the properties and values to set for the order.
query	A query specifying what to return after a successful set (optional).

# Example 1

The request below creates a new order with the language set to English and currency set to Euro. It then returns the unique identifier, language and currency of the newly created order.

API Console
PHP
JSON
Response

Order.set(null, {
  "currency": "EUR",
  "language": "en"
}, [
  "uid",
  "language",
  "currency"
])

# Example 2

The request below updates an order (see Example 1) with new values for currency and language.

API Console
PHP
JSON
Response

Order.set(54051042, {
  "currency": "SEK",
  "language": "sv"
}, [
  "uid",
  "language",
  "currency"
])

# setAffiliate

Stores an affiliate partner id to the order.

# Parameters

Parameter	Type	Description
uid	integer	Order UID
partner	integer	Affiliate partner id

# setDeliveryMethod

Selects a delivery method for the order. If at least one article in the order needs delivery (not code or download), then the delivery method must be set before performing checkout.

# setPaymentMethod

Selects a payment method for the order. (Gift certificates are added separately.) If the total cost of the order (after gift certificates are handled) is more than 0, then a payment method must be set on the order to make checkout possible.

NOTE

You can only set a payment method if the order has an allowed currency for the particular payment method.

# Parameters

Parameter	Type	Description
uid	integer	PaymentMethod UID
parameters	mixed	Parameters matching the parameter schema of the payment method.