Shopping API (LATEST)

All notable changes to the API.

• new add support for order item status property order.items.status. The new property can be included when creating and updating drafts items and when updating an order.
  • POST /v1/accounts/{aid}/shopping/draft_orders
  • POST /v1/accounts/{aid}/shopping/draft_orders/{id}/items
  • PUT /v1/accounts/{aid}/shopping/draft_orders/{id}/items/{line_id}
  • PUT /v1/accounts/{aid}/shopping/orders/{id}

• new support updating order.external_ids
  • PUT /v1/accounts/{aid}/shopping/orders/{id}

• Extend order item with optional external_id property

• new support updating order.itinerary
  • PUT /v1/accounts/{aid}/shopping/orders/{id}

• Extend the draft with options.generate_order_id=ALPHANUMERIC_9_RESERVE The draft order.order_id will be set when the new option is used.
  • POST /v1/accounts/{aid}/shopping/draft_orders

• Extend the draft options with multiple_authorizations Use options.multiple_authorizations to enable support for multiple authorizations on order items.
  • POST /v1/accounts/{aid}/shopping/draft_orders
  • PUT /v1/accounts/{aid}/shopping/orders/{id}
• Require authorization_id to be included in captures, refunds and cancellations if order was created with options.multiple_authorizations enabled.
  • POST /v1/accounts/{aid}/shopping/orders/{order_id}/captures
  • POST /v1/accounts/{aid}/shopping/orders/{order_id}/refunds
  • POST /v1/accounts/{aid}/shopping/orders/{order_id}/cancellations

• new support filter orders by: itinerary_travel_mode, itinerary_arrival_address, itinerary_departure_address and items_discount_lines_discount_type.
  • GET /v1/accounts/{aid}/shopping/orders

• 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

• new suport include_events when updating an order
  • PUT /v1/accounts/{aid}/shopping/orders/{id}
  • POST /v1/accounts/{aid}/shopping/orders/{id}/comments
  • POST /v1/accounts/{aid}/shopping/orders/{id}/cancel
  • POST /v1/accounts/{aid}/shopping/orders/{id}/close
  • POST /v1/accounts/{aid}/shopping/orders/{id}/open
  • DELETE /v1/accounts/{aid}/shopping/orders/{id}/comments/{comment_id}

• new endpoint for deleting comment
  • DELETE /v1/accounts/{aid}/shopping/orders/{id}/comments/{comment_id}

• Request for creating authorization, capture, refund or cancellation can fail with 409 Conflict error.
  • POST /v1/accounts/{aid}/shopping/orders/{order_id}/authorizations
  • POST /v1/accounts/{aid}/shopping/orders/{order_id}/captures
  • POST /v1/accounts/{aid}/shopping/orders/{order_id}/refunds
  • POST /v1/accounts/{aid}/shopping/orders/{order_id}/cancellations

• Extend the draft options to specify TTL for the order Use options.order_time_to_live to set expiry for when the order and its draft data will be removed.
  • POST /v1/accounts/{aid}/shopping/draft_orders
  • PUT /v1/accounts/{aid}/shopping/orders/{id}

• 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
  • captures
  • cancellations
  • authorizations

• Extend endpoint for listing draft and orders to support currency filter
  • GET /v1/accounts/{aid}/shopping/draft_orders
  • GET /v1/accounts/{aid}/shopping/orders

• 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)
  • POST /v1/accounts/{aid}/shopping/draft_orders

• Extend include_events query parameter to support multiple values. The parameter accept now:

  • false
  • true
  • api-event
  • service-event.

  api-event will be excluded from the store/customer endpoints:

  • GET /v1/accounts/{aid}/shopping/stores/{sid}/orders/
  • GET /v1/accounts/{aid}/shopping/stores/{sid}/orders/{oid}
  • GET /v1/accounts/{aid}/shopping/customers/{cid}/orders/
  • GET /v1/accounts/{aid}/shopping/customers/{cid}/orders/{oid}

• Support adding comments to an order
  • POST /v1/accounts/{aid}/shopping/orders/{id}/comments

• Extend the draft options to allow alphanumeric short order_id. Use options.generate_order_id to control the ID format for generated order.order_id.
  • POST /v1/accounts/{aid}/shopping/draft_orders

• 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 order.id if no order_id is provied.
  • POST /v1/accounts/{aid}/shopping/draft_orders

• Extend endpoint for listing draft and orders to support filtering
  • GET /v1/accounts/{aid}/shopping/draft_orders
  • GET /v1/accounts/{aid}/shopping/orders

• 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.

draft

• 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.

draft

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

draft

• 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.

order

• 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.

• GET shopping/orders/
• GET shopping/orders/{order_id}
• GET shopping/customers/{customer_id}/orders/
• GET shopping/customers/{customer_id}/orders/{order_id}
• GET shopping/stores/{store_id}/orders/
• GET shopping/stores/{store_id}/orders/{order_id}

draft orders

• extend draft definition with optional options.serial_order_number_suffix property.

orders

• 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.

events

• 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

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
• accept any customer.id format

order payments

• require amount and processed_at when creating a refund
• require amount and processed_at when creating a capture

store orders

• Add endpoint for list orders for a store
• Add endpoint for get order for a store

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/

order

• 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

order

• 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

Manage draft