Skip to content

orders

Jump to bottom Edit New page
Ola Valø Pettersen edited this page Mar 15, 2021 · 18 revisions

Orders API

Table of contents

Appendix:

Get all orders

Request

Retrieve a list of orders by executing a GET request: GET /api/v1/orders.

The following optional arguments are available:

Name Description Type Default
limit The number of elements which shall be returned int 100
offset The offset at which the returning array starts int 0
since The earliest requested modified date (Unix timestamp) int null
until The latest requested modified date (Unix timestamp) int null

Note that the limit must not be used without setting the offset, too. If given as sole argument, it would be interpreted as an order number (see section Get one order).

Response

The response status code will be 200 OK on success. The response body is a JSON object with an element data, which itself is an array of orders:

{"data":
    [
        {<order>},
        …
    ]
}

If the given arguments are invalid, a 400 Bad Request response will be sent, and the response body will be empty.

Get one order

Request

Retrieve one single order by executing a GET request: GET /api/v1/orders/<order_no>.

Response

The response status code will be 200 OK on success. The response body is a JSON object with an element data, which is an array with one element, namely an order:

{"data":
    [
        {<order>}
    ]
}

If no order exists to the given order number, a 404 Not Found status is returned.

Quick check for changes

Request

In order to make a quick check whether or not some database records have been updated recently, a HEAD request can be sent: HEAD /api/v1/orders.

Response

The response header is identical to that returned by the GET request, but the request body is omitted. This allows for a cheap check on the Last-Modified header field, in order to determine whether or not the data has been altered since the preceding check.

Get all order lines in an order

Request

Retrieve the order lines in an order by executing a GET request: GET /api/v1/orders/<order_no>/lines.

Response

The response code will be 200 OK on success. The response body is a JSON object with an element data, which is an array of order lines.

{"data":
    [
        {<order_line>},
        …
    ]
}

If no order exists to the given order number, a 404 Not Found status is returned.

Get one order line in an order

Request

Retrieve one order line in an order by executing a GET request: GET /api/v1/orders/<order_no>/lines/<order_line_id>.

Response

The response code will be 200 OK on success. The response body is a JSON object with an element data, which is an array with one element, namely an order line.

{"data":
    [
        {<order_line_object>}
    ]
}

If no order exists to the given order number, and/or no order line exists to the given order line ID, a 404 Not Found status is returned.

Update an order

Request

Update specific fields in an order by executing a PATCH request: PATCH /api/v1/orders/<order_no>. Send the new data as JSON object along with the request, e.g.: {"status":"sent","sent_date":"2015-03-13"}. For available fields see the order resource.

Note that setting the order status to either "sent" or "sent with rest" will always trigger the sending of a delivery confirmation PDF to the customer. Please make sure that you update all order lines before setting the order status. Otherwise, the delivery confirmation will contain erroneous information.

Also note that if the order has a fraud_status equal to either PENDING or REJECTED, you will not be able to perform any PUT or PATCH requests towards the order.

The payment method is set by either handing over its ID (field payment_method_id) or plain text value (field payment_method, evaluated case-insensitively). If both fields are given, the ID overrides the plain text. See the list of default payment methods, but note that each shop might add its own.

The shipping_method must be set via the ID. The related plain text shipping_method_text is ignored.

Response

The response code will be 204 No Content on success, and the response body will be empty. If no order exists to the given order number, a 404 Not Found status is returned. If the request URI is malformed, a 400 Bad Request status is returned. If the data provided in the request is not a valid JSON object, a 415 Unsupported Media Type response will be sent.

Update an order line

Request

Update specific fields in an order line by executing a PATCH request: PATCH /api/v1/orders/<order_no>/lines/<order_line_id>. Send the new data as JSON object along with the request, e.g.: {"sent":true,"sent_date":"2015-03-13","tracking_number":654321}. For available fields see the order line resource.

Note that changing attributes has to be done via the unique_product_id field. The attributes will automatically be altered accordingly. Setting the attributes manually in the input data has no effects.

Also note that if the order has a fraud_status equal to either PENDING or REJECTED, you will not be able to perform any PUT or PATCH requests towards the order.

Response

The response code will be 204 No Content on success, and the response body will be empty. If no order exists to the given order number, and/or no order line exists to the given order line ID, a 404 Not Found status is returned. If the request URI is malformed, a 400 Bad Request status is returned. If the data provided in the request is not a valid JSON object, a 415 Unsupported Media Type response will be sent.

Replace an order

Request

Replace a complete order by executing a PUT request: PUT /api/v1/orders/<order_no>. Send the new data as JSON object along with the request. Each of an order’s fields must be present.

Note that setting the order status to either "sent" or "sent with rest" will always trigger the sending of a delivery confirmation PDF to the customer. Please make sure that you update all order lines before setting the order status. Otherwise, the delivery confirmation will contain erroneous information.

The payment method is set by either handing over its ID (field payment_method_id) or plain text value (field payment_method, evaluated case-insensitively). If both fields are given, the ID overrides the plain text. See the list of default payment methods, but note that each shop might add its own.

The shipping_method must be set via the ID. The related plain text shipping_method_text is ignored.

Response

The response code will be 204 No Content on success, and the response body will be empty. If no order exists to the given order number, a 404 Not Found status is returned. If the request URI is malformed, a 400 Bad Request status is returned.

Replace an order line

Request

Replace a complete order line by executing a PUT request: PUT /api/v1/orders/<order_no>/lines/<order_line_id>. Send the new data as JSON object along with the request. Each of an order line’s fields must be present.

Note that changing attributes has to be done via the unique_product_id field. The attributes will automatically be altered accordingly. Setting the attributes manually in the input data has no effects.

Response

The response code will be 204 No Content on success, and the response body will be empty. If no order exists to the given order number, and/or no order line exists to the given order line ID, a 404 Not Found status is returned. If the request URI ist malformed, a 400 Bad Request status is returned.

Fullfill an order/order lines

Request

To fullfill/ partially fullfill an order, send a PATCH request to PATCH /api/v1/orders/send. The request must also contain a JSON object containing an array of order line IDs and potential tracking information. All order line IDs in the request must belong to the same order. This endpoint does not allow for fullfulling multiple different orders.

NOTE: Fullfilling an order will trigger all integrations associated with the store and their order flow. This includes payment and printing of labels/documents via SmartPrint.

The JSON object structure:

  • orderItemIds Required Array of OrderItem ids.
  • consignmentId String
  • trackingUrl String
  • labelUrl String

Example:

{
	"orderItemIds": [
		101,
		102,
		103,
	],
	"consignmentId": "abc123",
	"trackingUrl": "https://example.com/abc123",
	"labelUrl": "https://example.com/label.pdf"
}

Response

The response code will be 204 No Content on success, and the response body will be empty. On error, the response will either result in 404 Not Found, or a JSON response with a message.

Split an order line

To split an order line, send PATCH /api/v1/orders/orderline/lines/split. The request must have a JSON object consisting of the ID of the order line you wish to split, and the quantity you wish to split from the original.

Example:

{
	"orderItems": [
        {
            "1000": 1
        },
        {
            "1000": 1
        }
    ]
}

Given the example above, assuming the orderline with an ID of 1000 has a quantity of 4, this will set the quantity of order line 1000 to 2, and create two new orderlines, each with a quantity of 1.

Response

The response code will be 204 No Content on success, and the response body will be empty. On error, the response will either result in 404 Not Found, or a JSON response with a message.

Appendix

Order resource

Field name Description Type
order_no The order number string
customer_id The ID of the customer who has placed this order int
customer_comment The comment the customer has attached to the order string
status The order status (see the available order statuses) string
fraud_status The order fraud status (see the available fraud statuses) string
order_date The date the order was placed. Format YYYY-MM-DD string
order_time The time the order was placed. Format HH:MM:SS (24-hour notation) string
sent_date The date the order was sent. Format YYYY-MM-DD string
payment_method_id The ID of the payment method int
payment_method The payment method. Norwegian names, customised to Norwegian circumstances string
payment_addition The amount of an addition to the payment. Two decimals precision float
shipping_method The shipping method ID int
shipping_method_text The shipping method as plain text. May be defined and altered by the shop owner string
shipping_costs The shipping costs. Two decimals precision float
shipping_svalbard The costs for shipping to Svalbard. Two decimals precision float
vat The percentage of value added tax. Two decimals precision float
addition_vat The percentage of value added tax for the addition to the payment. Two decimals precision float
effected Whether or not the order has been effected bool
transaction_no The transaction number to identify the payment in some payment methods string
invoice_no The invoice number int
paid Whether or not the order has been completely paid bool
deleted Whether or not the order has been deleted bool
deletion_date The date when the order was deleted. Format YYYY-MM-DD string
deleted_by The person who has deleted the order. "customer" or some name string
effecting_date The date when the order has been effected. Format YYYY-MM-DD string
gift_card Whether or not a gift card is used in the payment of the order bool
shop_comment The comment the shop has attached to the order string
blocked Whether or not the order is blocked bool
tripletex_sent Whether or not the order has been sent to the Tripletex accounting software bool
rest Whether or not the order has been partially sent bool
currency The currency the order’s amounts are given in. Three letter code (ISO 4217) string
exchange_rate The exchange rate of the order’s currency in relation to NOK, at the time the order was placed. Two decimals precision float
total_amount_gross The gross total amount of the order. Two decimals precision float
total_vat The total value added tax due. Two decimals precision float
pickuppoint A JSON representation of the chosen customer chosen pickup point. string
modified_on The timestamp when this order has been modified the last time string
order_lines  An array of order line items belonging to this order array
used_gift_cards  An array of gift card use items used to pay for this order, if any exist. Note that when gift cards are used, the total_amount_gross of the order is reduced with the same amount as is spent from the gift card. Consequently, an order paid entirely by gift card(s) will have a total_amount_gross of 0. array

Order line resource

Field name Description Type
id The order line ID int
order_no The number of the order this order line is contained in int
product_id The product ID. All variants (i.e. attribute combinations) share the same product ID. int
unique_product_id The unique product ID. Each variant (i.e. attribute combination) is determined by a distinct unique product ID.
product_name The product name string
quantity The quantity that has been ordered – the number of items, amounts, lengths … float
unit_price The price for one item or one unit float
sent Whether or not this order line has been sent bool
quantity_sent The quantity that actually has been sent float
sent_date The date when this order line has been sent. Format YYYY-MM-DD string
tracking_number The tracking number for the shipment which contains this order line string
vat The VAT percentage, 2 decimals float
blocked Whether or not the order line is blocked bool
extra_field Extra information about the product string
extra_price The amount of possible extra costs, 2 decimals float
discount The absolute amount of discount, 2 decimals float
total_amount_gross The gross total amount this order line costs, 2 decimals float
total_vat The total VAT amount for this order line, 2 decimals float
attributes An associative array of attributes with the attribute name as key and the actual quality as value. E.g. {"Size": "M", "Colour": "Black"} object

Gift card use resource

Field name Description Type
id The gift card usage ID. A gift card may be used partially, on several orders. This ID defines each use uniquely. int
order_no  Which order number the gift card usage belongs to. int
gift_card_no   The gift card number that was used  int
date  The date the gift card was used, same as the order date, format YYYY-MM-DD. string
unit_price The amount that was used from the gift card. This may or may not be the entire gift card sum.  float

Order statuses

The order contains a status field which can attain the following values:

Name Description
received The order has been received.
in process The order has been accepted and is awaiting to be processed.
collecting *The items are being collected and the package is being packed.
intermitted *The processing of the order is temporarily paused.
sent The package has been sent.
sent with rest The package has been sent but does not contain all ordered items.
delivered *The package has been delivered to the customer.
cancelled *The order has been cancelled by the customer.
rejected *The order has been rejected by the shop.
  • = In order to use these statuses, 24Nettbutikk has to enable them in the store. Contact us at [email protected] in order to enable them.

Fraud statuses

The order contains a fraud_status field which can contain one of the following values:

Name Description
ACCEPTED The order has passed fraud check, and is ready to be fulfilled.
PENDING The order is being manually verified and is locked from being fulfilled.
REJECTED The order has been rejected, and cannot be fulfilled.
null The order is not subject to fraud checks and can be fulfilled.

Payment methods

The following payment methods are defined per default. Note that each shop may extend this list with custom payment methods.

ID Plain text
1 Postoppkrav
2 PayPal - Visa/MasterCard
3 DIBS Visa / MasterCard
4 Forskuddsbetaling
5 Faktura Bedrift - 14 dager, sendes via brevpost
7 Gavekort
9 NETS Netaxept - Visa/MasterCard
10 PayEx - Visa/MasterCard
12 Klarna - Faktura per 14 dager
13 Klarna - delbetaling
18 DIBS Visa / MasterCard
21 DIBS Kort
22 Klarna Checkout
23 Klarna - Delbetaling / Faktura
24 Paypal
25 Svea Webpay Visa
26 Svea Webpay Faktura
27 Svea Webpay Delbetaling
28 DIBS Faktura
Add a custom footer
Add a custom sidebar
Clone this wiki locally