Shopping API (LATEST)

Download OpenAPI specification:Download

API Integration Support: integration@dintero.com License: UNLICENSED

API for cart and orders

Changelog

All notable changes to the API.

2021-01-10

2021-01-08

  • Extend order item with optional external_id property

2021-01-06

2021-01-01

  • 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

2020-11-01

2020-09-01

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

2020-08-01

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

2020-07-01

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

2020-06-01

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.

2020-05-01

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

2019-07-01

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.

2019-06-01

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

2019-05-01

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

2019-04-01

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.

2019-03-02

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

2019-02-27

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

Webhooks

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

Events

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

Draft

Manage draft

Complete a draft order

Use this resource to transition the draft order into an Order. A draft with multiple sales locations will transition into one order per sales location.

scopes:

  • admin:shopping
  • write:shopping
scopes: ["admin:shopping","write:shopping"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

id
required
string <uuid>

The resource identifier string

Request Body schema: application/json
required

draft order resource

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": "bd04c959-d159-49b4-a096-2d84e014a8da",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "bd04c959-d159-49b4-a096-2d84e014a8da",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "bd04c959-d159-49b4-a096-2d84e014a8da",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "status": "open",
  • "_links": [
    ],
  • "orders": [
    ]
}

Get draft order

Get draft order.

scopes:

  • admin:shopping
  • read:shopping
scopes: ["admin:shopping","read:shopping"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

id
required
string <uuid>

The resource identifier string

Responses

Response samples

Content type
application/json
{
  • "id": "bd04c959-d159-49b4-a096-2d84e014a8da",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "bd04c959-d159-49b4-a096-2d84e014a8da",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "bd04c959-d159-49b4-a096-2d84e014a8da",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "status": "open",
  • "_links": [
    ],
  • "version": 0,
  • "events": [
    ],
  • "options": {
    },
  • "order": {
    }
}

Update draft order

Updates a draft order.

scopes:

  • admin:shopping
  • write:shopping
scopes: ["admin:shopping","write:shopping"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

id
required
string <uuid>

The resource identifier string

query Parameters
apply_discounts
boolean
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
required

draft order resource

required
object (OrderObject)
object

Responses

Request samples

Content type
application/json
{
  • "options": {
    },
  • "order": {
    }
}

Response samples

Content type
application/json
{
  • "id": "bd04c959-d159-49b4-a096-2d84e014a8da",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "bd04c959-d159-49b4-a096-2d84e014a8da",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "bd04c959-d159-49b4-a096-2d84e014a8da",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "status": "open",
  • "_links": [
    ],
  • "version": 0,
  • "events": [
    ],
  • "options": {
    },
  • "order": {
    }
}

Create a draft order

Use this resource to create orders in draft state.

scopes:

  • admin:shopping
  • write:shopping
scopes: ["admin:shopping","write:shopping"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
apply_discounts
boolean
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
required

draft order resource

required
object (OrderObject)
object

Responses

Request samples

Content type
application/json
{
  • "options": {
    },
  • "order": {
    }
}

Response samples

Content type
application/json
{
  • "id": "bd04c959-d159-49b4-a096-2d84e014a8da",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "bd04c959-d159-49b4-a096-2d84e014a8da",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "bd04c959-d159-49b4-a096-2d84e014a8da",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "status": "open",
  • "_links": [
    ],
  • "version": 0,
  • "events": [
    ],
  • "options": {
    },
  • "order": {
    }
}

Draft items

Manage draft items

Remove item from draft

Remove a item line from the draft

scopes:

  • admin:shopping
  • write:shopping
scopes: ["admin:shopping","write:shopping"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

id
required
string <uuid>

The resource identifier string

line_id
required
integer

The resource identifier string

query Parameters
apply_discounts
boolean
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.

Responses