Shopping API (2020-05-01)

API Integration Support: License: UNLICENSED

API for cart and orders


All notable changes to the API.


  • new support filter orders by: itinerary_travel_mode, itinerary_arrival_address, itinerary_departure_address and items_discount_lines_discount_type.
  • Extend the Order itinerary with new properties
    • Add support for route_id and vehicle_id.
    • Add support for external_ids in arrival_address and departure_address




  • Extend payment operations items to include payout for order items that have a payout rule The new property shows how the payment operation item amounts should be splitt by its payout rule destinations
  • Extend the draft options to support replace of existing order. Use options.replace="order" option to replace an order when the draft is completed. This option is only valid for existing orders that have no payment operations registered (when draft is completed)


  • Create order with custom order_id. The new property is only supported when creating draft with split_draft=false. The order.order_id will be set to if no order_id is provied.


  • Extend order with external_ids
  • Extend order with external_links.
  • Extend order itinerary and attachments
    • Add name and id to itinerary arrival_address and `departure_address. Make all address properties options
    • Add line_ids and id to itinerary and attachments
    • Add operator to itinerary
    • Extend itinerary.travel_mode with CUSTOM
  • Extend order events with event_type to support event types api-event and service-event.
  • Extend order event with draft_id, a readOnly property that are included in events where the order was created or updated by a draft.
  • Extend order with itinerary and attachment for including travel details
  • Extern order items with readOnly version property that will be set when the draft order item is added or updated.
  • Extend order payment operation definition with processed_by and payment_details.



  • Extend the draft options to allow more control for how payout is configured
  • Extend the draft order items to support including manual_payout to support use of any payout rule when calculating the split for the order items.


  • Extend order item with attachment. Add support for including details about car, bus and train reservation as attachment in order items.



  • Add events to draft. A event will be added to the draft events list when the draft is updated.
  • Add payout option to enable calculating the payout for the order items store id. See Billing API
  • Add support for dynamic payout rules via options.payout.rules.
  • Add order_id option to allow creating a draft that will be added to an existing order.
  • Add split_draft option to allow one-to-many mapping between draft and order
  • Add support for including store when creating a draft.
  • Add support for adding draft items with reversed_reason property. Use the property in case when an item should be reversed and the payment refunded.
  • Add support for item related_item.type=reversed, that should be used when reversing an existing item.
  • Add support for negative item gross_amount to support reversing items.


  • Include authorizations and cancellations in order details
  • Include payment_details to the order.

sessions Add support for creating sessions for and order

refunds Require items to be specified when creating a refund

captures Require items to be specified when creating a capture

cancellations Add support for creating cancellations for an order

authorizations Add support for creating authorizations for an order


orders Extend order definitions with Discounts

orders store orders add support for include_events on order requests. The order event state and events list will be included in the response.


draft orders

  • extend draft definition with optional options.serial_order_number_suffix property.


  • extend order definition with courier_id and pickup_at that can be set and updated after the order is created
  • extend order definition with delivery_id that can be set after the the order is created
  • extend order definition with optional pre_order property
  • extend order definition with optional type property.
  • extend order shipping_address and billing_address property with optional comment property that can be used for additional information needed for the address.


  • allow scopes
    • read:shopping:/orders/ANY/events
    • write:shopping:/orders/ANY/events


draft orders

  • filter by status: open, completed, deleted
  • filter by created_at.gte and created_at.lte

customer orders

  • filter by status: open, closed, cancelled
  • filter by payment_status: pending, partially_paid, paid, partially_refunded, refunded
  • filter by created_at.gte and created_at.lte

store orders

  • filter by status: open, closed, cancelled
  • filter by payment_status: pending, partially_paid, paid, partially_refunded, refunded
  • filter by created_at.gte and created_at.lte


  • filter by status: open, closed, cancelled
  • filter by payment_status: pending, partially_paid, paid, partially_refunded, refunded
  • filter by created_at.gte and created_at.lte
  • accept any format

order payments


store orders

customer orders

  • Remove uuid format requirement on customer_id path parameter

complete draft order

  • remove support for apply_discounts query parameter, the parameter will only be supported from endpoints updating the draft order.


complete draft order

  • change the response to include one or more orders created from the draft.

Rename the API, Shopping API, all endpoints will now be prefixed with

  • /v1/accounts/{aid}/shopping/


  • Add salesperson_id and salesperson_name properties
  • Add delivery_at property for specifying when the order should be delivered (in the future)

order item

  • Require percentage in tax_lines for an order item
  • Add quantity property to item.additions, and allow negative gross_amount
  • Add related_item property that can be used to create a relationship between two items
  • Add description_alias, shorter item description for receipt
  • Add salesperson_id and salesperson_name property


order item

  • Add metadata property that can be used to included additional key/values on order items.
  • Add additions array property. The property can be used to describe customization the customer want to be included with the order item.
  • Add comment property for recording customer comments on the item


  • Add comment property for recording customer comments on the order


Use webhooks to get notification on shopping events. See Create new subscription for details on how to create a webhooks subscription


Following event types are supported

Event Description
shopping_draft_add new draft order created
shopping_draft_update existing draft order updated
shopping_draft_complete draft completed, includes orders created
shopping_order_update existing order updated
shopping_order_event_add new event added to order



Bearer authentication (also called token authentication) should be used when accessing the API.

Use Get Token to get an access token

Authorization by using the Bearer schema The content of the header should look like the following:

Authorization: Bearer {access_token}

where the access_token is JSON Web Tokens (JWT).

Security Scheme Type API Key
Header parameter name: Authorization


Create a draft order

Use this resource to create orders in draft state.


  • admin:shopping
  • write:shopping
path Parameters
string <^[PT]{1}\d{8}$> 9 characters

An id that uniquely identifies the account.

query Parameters
Default: false

Calculate available discounts and apply them to the order.

Requires additional scope for accessing the DealEngine, one of

  • admin:discounts
  • write:discounts
  • write:discounts:/available_for_receipt

The tax_lines will be updated if apply_discount results in new net_amount.

  • net_amount = gross_amount - Σ discount_lines.amount

tax_line.amount will be calculated from tax_line.percentage and net_amount.

Request Body schema: application/json

draft order resource



Request samples

Content type
  • "options": {
  • "order": {