Shopping API (2020-05-01)

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

API for cart and orders

Changelog

All notable changes to the API.

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. See Billing API
  • 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.

order

  • Include authorizations and cancellations in order details
  • Support creating order directly without creating a draft
  • Add 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

Authentication

JWT

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

Draft

Create a draft order

post /accounts/{aid}/shopping/draft_orders
https://api.dintero.com/v1/accounts/{aid}/shopping/draft_orders
https://test.dintero.com/v1/accounts/{aid}/shopping/draft_orders

Use this resource to create orders in draft state.

scopes:

  • admin:shopping
  • write:shopping
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

draft order resource

order
required
object
options
object

Responses

201

draft order was created

400

Bad / Invalid request

401

Access forbidden, invalid JWT token was used

403

Forbidden

500

Unexpected Error

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "options":
    {
    },
  • "order":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "bd04c959-d159-49b4-a096-2d84e014a8da",
  • "created_at": "2020-04-07T08:40:44Z",
  • "created_by": "bd04c959-d159-49b4-a096-2d84e014a8da",
  • "updated_at": "2020-04-07T08:40:44Z",
  • "deleted_by": "bd04c959-d159-49b4-a096-2d84e014a8da",
  • "deleted_at": "2020-04-07T08:40:44Z",
  • "status": "open",
  • "_links":
    [
    ],
  • "version": 0,
  • "events":
    [
    ],
  • "options":
    {
    },
  • "order":
    {