Order

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

Properties

Property Description
affiliate UID of an affiliate partner.
changed Date and time of when the order was last modified.
costs The cost details of the order broken down into the subobjects 'cart', 'payment' and 'shipment', and then aggregated into 'total'. See Costs below.
currency The currency of the order which is used in the Costs objects.
customer The personal details of the customer broken down into the subobjects 'address', 'deliveryAddress' and 'info'. See Customer below.
delivery Delivery details including 'method' (but excluding delivery status). See Delivery below.
deliveryStatus The delivery status of the order, e.g. "sent" or "unsent".
discarded Whether the order has been cancelled by the administrator.
exchangeRate 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.
externalOrderNumber Order number used in external systems such as accounting software
items The unique identifiers of the OrderItems as an array.
hasVat Whether the order contains value-added tax.
language Language of the order.
note An optional note by the administrator, e.g. "Double check the serial number before shipment".
ordered Date and time of the order, if placed.
paymentStatus The payment status of the order, e.g. "paid" or "unpaid".
payments 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.
orderNumber Webshop specific order identifier
uid The unique indentifier of the order.

Costs

These are the properties for the costs object:

Property Description
cart The costs of the articles added to cart excluding any payment and shipment fees.
payment The fee of the selected payment method, if any.
shipment The fee of the selected shipment method, if any.
total 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 Description
exVat The amount excluding value-added tax.
incVat The amount including value-added tax.
vat Value-added tax of the order.
vatRate Value-added tax rate of the order as a decimal number, e.g. 0.12 for 12%.

Customer

These are the properties for the customer object.

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

Property Description
address The address and contact details of the customer. See 'address' below.
customer 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 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 The address to which the order shall be sent. See 'deliveryAddress' below.
info Additional details of the customer, e.g. customer type. See 'info' below.

The 'address' subobject has the following properties:

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

The 'deliveryAddress' subobject has the following properties:

Property Description
address Address line 1 of the customer, e.g. street name and number.
address2 Additional address details, such as apartment, suite or building, if any.
company Company name of the customer, if any.
country Delivery country of the customer.
name Full name of the customer.
phoneDay Daytime phone number of the customer.
phoneMobile Mobile phone number of the customer.
postcode Postcode of the customer.
state State or province of the customer, e.g. "AL" (Alabama), if any.
town Post town of the customer.

The 'info' subobject has the following properties:

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

Delivery

These are the properties for the delivery object:

Property Description
method The unique identifier of the delivery method.

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 Description
integer order The unique identifier of an Order or null to create a new order.
integer article The unique identifier of an Article.
object choices An object containing choices, according to the Article's choiceSchema.
query Query passed to get on the created item, for return value. Defaults to all.

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.

JSON
{
  "jsonrpc": "2.0",
  "id":      1,
  "method":  "Order.addArticle",
  "params":  [
    null,               // Order UID null for creating new Order
    1234567,            // Article UID to add
    { "quantity":  1 },
    { "order": "uid" }  // We only want the Order UID
  ],
}
Response
{
  "jsonrpc": "2.0",
  "id":      1,
  "result":  {
    "order": 7654321
  }
}

addDiscountCode

Applies a discount code to the order.

Parameters

Parameter Description
string code The discount code
mixed query What to return; defaults to nothing. See Query language.

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.

Please 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 getAddessLookupSchema.

Example

JSON
{
  "nin":      "123456789",
  "postcode": "41264"
}

Returns

Object Description
array addresses 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.

Important: Make sure to check the redirect field in returned state.

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

Parameter object

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

Returns object with one of these properties:

Property Description
done Whether the payment is fully completed.
redirect 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
Order.get(12345678, ["uid", "currency", "language", "items", "costs", "paymentStatus", "delivery", "deliveryStatus"])
Response
{
  "costs": {
    "total": {
      "exVat": 1012
    },
    "cart": {
      "exVat": 1000
    },
    "payment": {
      "exVat": 2
    },
    "shipment": {
      "exVat": 10
    }
  },
  "currency": "EUR",
  "delivery": {
    "method": 15433
  },
  "deliveryStatus": "sent"
  "items": [1234567, 1234568, 1234569],
  "language": "en",
  "paymentStatus": "paid",
  "uid": 123456
}

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:

JSON
{
  "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
}

getAddessLookupSchema

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

Parameters

Parameter Description
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.

JSON
{
  "jsonrpc": "2.0",
  "id":      1,
  "method":  "Order.getCartMessages",
  "params":  []
}
Response
{
  "jsonrpc": "2.0",
  "id":      1,
  "result":  "Article 234141 only exists in 1 example, the cart has been adjusted."
}

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.

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

Returns HTML representing an IFRAME object used for performing a checkout process using Klarna Checkout. 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

Parameters

The unique identifier of the 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.

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
Order.list( {"costs": {"cart": {"exVat": true, "currency": true}}}, {"filters":  {"/ordered": {"min": "2014-01-01T00:00:00Z"}}})
Response
[
  {
    "costs": {
      "cart": {
        "currency": "GBP",
        "exVat": 99
      }
    }
  },
  {
    "costs": {
      "cart": {
        "currency": "SEK",
        "exVat": 999
      }
    }
  },
  {
    "costs": {
      "cart": {
        "currency": "SEK",
        "exVat": 999
      }
    }
  }
]

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
Order.set(null, {"currency": "EUR", "language": "en"}, ["uid", "language", "currency"])
Response
{
  "uid": 123123123,
  "language": "en",
  "currency": "EUR"
}

Example 2

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

API Console
Order.set(54051042, {"currency": "SEK", "language": "en"}, ["uid", "language", "currency"])
Response
{
  "uid": 123123123,
  "language": "sv",
  "currency": "SEK"
}

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.

Please note that you can only set a payment method if the order has an allowed currency for the particular payment method.

Parameters

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

setAffiliate

Stores an affiliate partner id to the order.

Parameters

Parameter Description
integer Order UID
integer Affiliate partner id