openapi: 3.0.0
info:
title: Shopping API
contact:
name: API Integration Support
email: integration@dintero.com
description: >
API for cart and orders
# Changelog
All notable changes to the API.
## 2026-06-01
> - **new**: Add support for order operation item with exchange rate
information
> The new properties can be included when creating payment operations
> - [POST
/v1/accounts/{aid}/shopping/orders/{order_id}/authorizations](/orders-api/orderauthorizations/aid_orders_id_authorization_post)
> - [POST
/v1/accounts/{aid}/shopping/orders/{order_id}/captures/{capture_id}](/orders-api/ordercaptures/aid_orders_id_capture_post)
> - [POST
/v1/accounts/{aid}/shopping/orders/{order_id}/refunds](/orders-api/orderrefunds/aid_orders_id_refunds_post)
> - [POST
/v1/accounts/{aid}/shopping/orders/{order_id}/cancellations](/orders-api/ordercancellations/aid_orders_id_cancellation_post)
## 2025-11-30
> - **new**: Add support for order item with exchange rate information
> The new properties can be included when creating and updating draft
items
> and when updating an order
> - [POST
/v1/accounts/{aid}/shopping/draft_orders](/orders-api/draft/aid_draft_orders_post)
> - [POST /v1/accounts/{aid}/shopping/draft_orders/{id}/items
](/orders-api/draftitems/aid_draft_orders_id_items_post)
> - [PUT
/v1/accounts/{aid}/shopping/draft_orders/{id}/items/{line_id}](/orders-api/draftitems/aid_draft_orders_id_items_line_id_put)
> - [PUT
/v1/accounts/{aid}/shopping/orders/{id}](/orders-api/order/aid_orders_id_put)
## 2025-06-01
> - **new**: Add support for order item discount_lines with
`discount_subtype`
> The new property can be included when creating and updating draft items
> and when updating an order
> - [POST
/v1/accounts/{aid}/shopping/draft_orders](/orders-api/draft/aid_draft_orders_post)
> - [POST /v1/accounts/{aid}/shopping/draft_orders/{id}/items
](/orders-api/draftitems/aid_draft_orders_id_items_post)
> - [PUT
/v1/accounts/{aid}/shopping/draft_orders/{id}/items/{line_id}](/orders-api/draftitems/aid_draft_orders_id_items_line_id_put)
> - [PUT
/v1/accounts/{aid}/shopping/orders/{id}](/orders-api/order/aid_orders_id_put)
## 2021-01-10
> - **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](/orders-api/draft/aid_draft_orders_post)
> - [POST /v1/accounts/{aid}/shopping/draft_orders/{id}/items
](/orders-api/draftitems/aid_draft_orders_id_items_post)
> - [PUT
/v1/accounts/{aid}/shopping/draft_orders/{id}/items/{line_id}](/orders-api/draftitems/aid_draft_orders_id_items_line_id_put)
> - [PUT
/v1/accounts/{aid}/shopping/orders/{id}](/orders-api/order/aid_orders_id_put)
> - **new** support updating `order.external_ids`
> - [PUT
/v1/accounts/{aid}/shopping/orders/{id}](/orders-api/order/aid_orders_id_put)
## 2021-01-08
> - Extend order item with optional `external_id` property
> - **new** support updating `order.itinerary`
> - [PUT
/v1/accounts/{aid}/shopping/orders/{id}](/orders-api/order/aid_orders_id_put)
## 2021-01-06
> - 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](/orders-api/draft/aid_draft_orders_post)
> - 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](/orders-api/draft/aid_draft_orders_post)
> - [PUT
/v1/accounts/{aid}/shopping/orders/{id}](/orders-api/order/aid_orders_id_put)
> - 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](/orders-api/ordercaptures/aid_orders_id_capture_post)
> - [POST
/v1/accounts/{aid}/shopping/orders/{order_id}/refunds](/orders-api/orderrefunds/aid_orders_id_refunds_post)
> - [POST
/v1/accounts/{aid}/shopping/orders/{order_id}/cancellations](/orders-api/ordercancellations/aid_orders_id_cancellation_post)
## 2021-01-01
> - **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](/orders-api/orderlist/aid_orders_get)
> - 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** support `include_events` when updating an order
> - [PUT
/v1/accounts/{aid}/shopping/orders/{id}](/orders-api/order/aid_orders_id_put)
> - [POST
/v1/accounts/{aid}/shopping/orders/{id}/comments](/orders-api/ordercomments/aid_orders_id_comments_post)
> - [POST
/v1/accounts/{aid}/shopping/orders/{id}/cancel](/orders-api/orderstatus/aid_orders_id_cancel_post)
> - [POST
/v1/accounts/{aid}/shopping/orders/{id}/close](/orders-api/orderstatus/aid_orders_id_close_post)
> - [POST
/v1/accounts/{aid}/shopping/orders/{id}/open](/orders-api/orderstatus/aid_orders_id_open_post)
> - [DELETE
/v1/accounts/{aid}/shopping/orders/{id}/comments/{comment_id}](/orders-api/ordercomments/aid_orders_id_comments_comment_id_delete)
> - **new** endpoint for deleting comment
> - [DELETE
/v1/accounts/{aid}/shopping/orders/{id}/comments/{comment_id}](/orders-api/ordercomments/aid_orders_id_comments_comment_id_delete)
## 2020-12-01
> - Request for creating authorization, capture, refund or cancellation
> can fail with `409 Conflict` error.
> - [POST
/v1/accounts/{aid}/shopping/orders/{order_id}/authorizations](/orders-api/orderauthorizations/aid_orders_id_authorization_post)
> - [POST
/v1/accounts/{aid}/shopping/orders/{order_id}/captures](/orders-api/ordercaptures/aid_orders_id_capture_post)
> - [POST
/v1/accounts/{aid}/shopping/orders/{order_id}/refunds](/orders-api/orderrefunds/aid_orders_id_refunds_post)
> - [POST
/v1/accounts/{aid}/shopping/orders/{order_id}/cancellations](/orders-api/ordercancellations/aid_orders_id_cancellation_post)
## 2020-11-01
> - 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](/orders-api/draft/aid_draft_orders_post)
> - [PUT
/v1/accounts/{aid}/shopping/orders/{id}](/orders-api/order/aid_orders_id_put)
## 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 split by its payout rule destinations
> - [captures](#tag/order.captures)
> - [cancellations](#tag/order.cancellations)
> - [authorizations](#tag/order.authorizations)
> - Extend endpoint for listing draft and orders to support currency filter
> - [GET
/v1/accounts/{aid}/shopping/draft_orders](/orders-api/orderlist/aid_draft_orders_get)
> - [GET
/v1/accounts/{aid}/shopping/orders](/orders-api/orderlist/aid_orders_get)
> - 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](/orders-api/draft/aid_draft_orders_post)
## 2020-08-01
> - 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/](/orders-api/storeorder/aid_stores_sid_orders_get)
> - [GET
/v1/accounts/{aid}/shopping/stores/{sid}/orders/{oid}](/orders-api/storeorder/aid_stores_sid_orders_id_get)
> - [GET
/v1/accounts/{aid}/shopping/customers/{cid}/orders/](/orders-api/customerorder/aid_customers_cid_orders_get)
> - [GET
/v1/accounts/{aid}/shopping/customers/{cid}/orders/{oid}](/orders-api/customerorder/aid_customers_cid_orders_id_get)
> - Support adding comments to an order
> - [POST
/v1/accounts/{aid}/shopping/orders/{id}/comments](/orders-api/ordercomments/aid_orders_id_comments_post)
> - 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](/orders-api/draft/aid_draft_orders_post)
> - 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 provided.
> - [POST
/v1/accounts/{aid}/shopping/draft_orders](/orders-api/draft/aid_draft_orders_post)
## 2020-07-01
> - Extend endpoint for listing draft and orders to support filtering
> - [GET
/v1/accounts/{aid}/shopping/draft_orders](/orders-api/orderlist/aid_draft_orders_get)
> - [GET
/v1/accounts/{aid}/shopping/orders](/orders-api/orderlist/aid_orders_get)
> - 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
> - Extend 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](#tag/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](#tag/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](#tag/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](/billing-api/payoutrules/aid_billing_payout_rules_get)
> - 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](#tag/order)**
>
> - Include authorizations and cancellations in order details
> - Include `payment_details` to the order.
> **[sessions](#tag/order.sessions)**
> Add support for creating sessions for and order
> **[refunds](#tag/order.refunds)**
> Require items to be specified when creating a refund
> **[captures](#tag/order.captures)**
> Require items to be specified when creating a capture
> **[cancellations](#tag/order.cancellations)**
> Add support for creating cancellations for an order
> **[authorizations](#tag/order.authorizations)**
> Add support for creating authorizations for an order
## 2019-07-01
> **[orders](/orders-api/orderlist/aid_orders_get)**
> Extend order definitions with Discounts
> **[orders](/orders-api/orderlist/aid_orders_get)** > **[store
orders](/orders-api/storeorder/aid_stores_sid_orders_get)**
> add support for `include_events` on order requests. The order event
> `state` and `events` list will be included in the response.
>
> - [GET shopping/orders/](/orders-api/orderlist/aid_orders_get)
> - [GET shopping/orders/{order_id}](/orders-api/order/aid_orders_id_get)
> - [GET
shopping/customers/{customer_id}/orders/](/orders-api/customerorder/aid_customers_cid_orders_get)
> - [GET
shopping/customers/{customer_id}/orders/{order_id}](/orders-api/customerorder/aid_customers_cid_orders_id_get)
> - [GET
shopping/stores/{store_id}/orders/](/orders-api/storeorder/aid_stores_sid_orders_get)
> - [GET
shopping/stores/{store_id}/orders/{order_id}](/orders-api/storeorder/aid_stores_sid_orders_id_get)
## 2019-06-01
> **[draft orders](/#tag/Draft)**
>
> - extend draft definition with optional
`options.serial_order_number_suffix`
> property.
> **[orders](#tag/Order)**
>
> - 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](#tag/Events)**
>
> - allow scopes
> - `read:shopping:/orders/ANY/events`
> - `write:shopping:/orders/ANY/events`
## 2019-05-01
> **[draft orders](/orders-api/orderlist/aid_draft_orders_get)**
>
> - filter by `status`: _open, completed, deleted_
> - filter by `created_at.gte` and `created_at.lte`
> **[customer
orders](/orders-api/customerorder/aid_customers_cid_orders_get)**
>
> - 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](/orders-api/storeorder/aid_stores_sid_orders_get)**
>
> - 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](/orders-api/orderlist/aid_orders_get)**
>
> - 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](#tag/Order-payment)**
>
> - require `amount` and `processed_at` when
> [creating a refund](/orders-api/orderrefunds/aid_orders_id_refunds_post)
> - require `amount` and `processed_at` when
> [creating a
capture](/orders-api/ordercaptures/aid_orders_id_capture_post)
## 2019-04-01
> **[store orders](#tag/Store-Orders)**
>
> - Add endpoint for [list
orders](/orders-api/storeorder/aid_stores_sid_orders_get) for a store
> - Add endpoint for [get
order](/orders-api/storeorder/aid_stores_sid_orders_id_get) for a store
> **[customer orders](#tag/Customer-Orders)**
>
> - Remove uuid format requirement on customer_id path parameter
> **[complete draft
order](/orders-api/draft/aid_draft_orders_id_complete_put)**
>
> - 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](/orders-api/draft/aid_draft_orders_id_complete_put)**
>
> - 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](/orders-api/order/aid_orders_id_get)**
>
> - Add `salesperson_id` and `salesperson_name` properties
> - Add `delivery_at` property for specifying when the order should be
> delivered (in the future)
> **[order item](/orders-api/order/aid_orders_id_get)**
>
> - 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](/orders-api/order/aid_orders_id_get)**
>
> - 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](/orders-api/order/aid_orders_id_get)**
>
> - Add `comment` property for recording customer comments on the order
# Webhooks
Use webhooks to get notification on shopping events. See
[Create subscription](/webhooks-api/subscriptions/aid_source_hooks_post)
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 |
version: LATEST
license:
name: UNLICENSED
url: https://dintero.com
x-logo:
url: https://docs.dintero.com/img/dintero-dark-padded.svg
altText: Dintero Logo
security:
- JWT: []
tags:
- name: order.sessions
x-displayName: Session
description: Manage order sessions
- name: order.authorizations
description: Manage order authorizations
x-displayName: Authorizations
- name: order.captures
description: Manage order captures
x-displayName: Captures
- name: order.refunds
description: Manage order refunds
x-displayName: Refunds
- name: order.cancellations
description: Manage order cancellations
x-displayName: Cancellations
- name: draft
description: Manage draft
x-displayName: Draft
- name: draft.items
description: Manage draft items
x-displayName: Draft items
- name: order
description: Manage order
x-displayName: Order
- name: order.comments
description: Manage order comments
x-displayName: Comments
- name: order.events
description: Manage order events
x-displayName: Events
- name: order.status
description: Manage order status
x-displayName: Status
- name: order.list
description: View orders
x-displayName: Collections
- name: customer.order
description: View customer orders
x-displayName: Customer
- name: store.order
description: View store orders
x-displayName: Store
paths:
/accounts/{aid}/shopping/customers/{customer_id}/orders/{order_id}:
get:
operationId: aid_customers_cid_orders_id_get
x-scopes:
- user:shopping
- admin:shopping
- read:shopping
tags:
- customer.order
summary: aid_customers_cid_orders_id_get
description: |
Retrieve Order details for an customer
scopes:
- user:shopping
- admin:shopping
- read:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/CustomerIdPath'
- $ref: '#/components/parameters/OrderId'
- $ref: '#/components/parameters/IncludeEventsLimited'
responses:
'200':
$ref: '#/components/responses/Order'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Get Order
sidebarTitle: Get Order
/accounts/{aid}/shopping/customers/{customer_id}/orders:
get:
operationId: aid_customers_cid_orders_get
x-scopes:
- user:shopping
- admin:shopping
- read:shopping
tags:
- customer.order
summary: aid_customers_cid_orders_get
description: |
Retrieve a list of orders belonging to a customer user
scopes:
- user:shopping
- admin:shopping
- read:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/CustomerIdPath'
- $ref: '#/components/parameters/StartingAfter'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/OrderStatus'
- $ref: '#/components/parameters/OrderPaymentStatus'
- $ref: '#/components/parameters/CreatedAtGte'
- $ref: '#/components/parameters/CreatedAtLte'
- $ref: '#/components/parameters/IncludeEventsLimited'
responses:
'200':
$ref: '#/components/responses/ExtendedOrderCollection'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Orders collection
sidebarTitle: Orders collection
/accounts/{aid}/shopping/draft_orders/{id}/complete:
put:
operationId: aid_draft_orders_id_complete_put
x-scopes:
- admin:shopping
- write:shopping
tags:
- draft
summary: aid_draft_orders_id_complete_put
description: >
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
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/ResourceId'
requestBody:
content:
application/json:
schema:
type: object
description: draft order resource
required: true
responses:
'200':
$ref: '#/components/responses/DraftOrderComplete'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Complete a draft order
sidebarTitle: Complete a draft order
/accounts/{aid}/shopping/draft_orders/{id}/items/{line_id}:
delete:
operationId: aid_draft_orders_id_items_line_id_delete
x-scopes:
- admin:shopping
- write:shopping
tags:
- draft.items
summary: aid_draft_orders_id_items_line_id_delete
description: |
Remove a item line from the draft
scopes:
- admin:shopping
- write:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/ResourceId'
- $ref: '#/components/parameters/LineId'
- $ref: '#/components/parameters/ApplyDiscounts'
responses:
'202':
$ref: '#/components/responses/DraftOrderUpdated'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Remove item from draft
sidebarTitle: Remove item from draft
put:
operationId: aid_draft_orders_id_items_line_id_put
x-scopes:
- admin:shopping
- write:shopping
tags:
- draft.items
summary: aid_draft_orders_id_items_line_id_put
description: |
Update item in draft
scopes:
- admin:shopping
- write:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/ResourceId'
- $ref: '#/components/parameters/LineId'
- $ref: '#/components/parameters/ApplyDiscounts'
requestBody:
$ref: '#/components/requestBodies/aid_draft_orders_id_items_line_id_putData'
responses:
'202':
$ref: '#/components/responses/DraftOrderUpdated'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Update item in draft
sidebarTitle: Update item in draft
/accounts/{aid}/shopping/draft_orders/{id}/items:
post:
operationId: aid_draft_orders_id_items_post
x-scopes:
- admin:shopping
- write:shopping
tags:
- draft.items
summary: aid_draft_orders_id_items_post
description: |
Updates a draft with new item
scopes:
- admin:shopping
- write:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/ResourceId'
- $ref: '#/components/parameters/ApplyDiscounts'
requestBody:
$ref: '#/components/requestBodies/aid_draft_orders_id_items_line_id_putData'
responses:
'202':
$ref: '#/components/responses/DraftOrderUpdated'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Add item to draft
sidebarTitle: Add item to draft
/accounts/{aid}/shopping/draft_orders/{id}:
get:
operationId: aid_draft_orders_id_get
x-scopes:
- admin:shopping
- read:shopping
tags:
- draft
summary: aid_draft_orders_id_get
description: |
Get draft order.
scopes:
- admin:shopping
- read:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
$ref: '#/components/responses/DraftOrder'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Get draft order
sidebarTitle: Get draft order
put:
operationId: aid_draft_orders_id_put
x-scopes:
- admin:shopping
- write:shopping
tags:
- draft
summary: aid_draft_orders_id_put
description: |
Updates a draft order.
scopes:
- admin:shopping
- write:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/ResourceId'
- $ref: '#/components/parameters/ApplyDiscounts'
requestBody:
$ref: '#/components/requestBodies/DraftOrder'
responses:
'202':
$ref: '#/components/responses/DraftOrderUpdated'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Update draft order
sidebarTitle: Update draft order
/accounts/{aid}/shopping/draft_orders:
get:
operationId: aid_draft_orders_get
x-scopes:
- admin:shopping
- read:shopping
tags:
- order.list
summary: aid_draft_orders_get
description: |
Retrieve a list of draft orders
scopes:
- admin:shopping
- read:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/StartingAfter'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/DraftOrderStatus'
- $ref: '#/components/parameters/CreatedAtGte'
- $ref: '#/components/parameters/CreatedAtLte'
- $ref: '#/components/parameters/OrderNetAmountGte'
- $ref: '#/components/parameters/OrderNetAmountLte'
- $ref: '#/components/parameters/OrderCurrency'
- $ref: '#/components/parameters/OrderSearch'
responses:
'200':
$ref: '#/components/responses/DraftOrderCollection'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Draft orders collection
sidebarTitle: Draft orders collection
post:
operationId: aid_draft_orders_post
x-scopes:
- admin:shopping
- write:shopping
tags:
- draft
summary: aid_draft_orders_post
description: |
Use this resource to create orders in draft state.
scopes:
- admin:shopping
- write:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/ApplyDiscounts'
requestBody:
$ref: '#/components/requestBodies/DraftOrder'
responses:
'201':
$ref: '#/components/responses/DraftOrder'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Create a draft order
sidebarTitle: Create a draft order
/accounts/{aid}/shopping/orders/{order_id}/authorizations/{authorization_id}:
get:
operationId: aid_orders_id_authorization_id_get
x-scopes:
- admin:shopping
- read:shopping
tags:
- order.authorizations
summary: aid_orders_id_authorization_id_get
description: |
Retrieve details about a authorization
scopes:
- admin:shopping
- read:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
- $ref: '#/components/parameters/AuthorizationId'
responses:
'200':
$ref: '#/components/responses/OrderAuthorization'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Get Authorization details
sidebarTitle: Get Authorization details
/accounts/{aid}/shopping/orders/{order_id}/authorizations:
get:
operationId: aid_orders_id_authorizations_get
x-scopes:
- admin:shopping
- read:shopping
tags:
- order.list
summary: aid_orders_id_authorizations_get
description: |
Retrieve list of authorizations for an order
scopes:
- admin:shopping
- read:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
responses:
'200':
$ref: '#/components/responses/OrderAuthorizationCollection'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Get Authorization Collection
sidebarTitle: Get Authorization Collection
post:
operationId: aid_orders_id_authorization_post
x-scopes:
- admin:shopping
- write:shopping
tags:
- order.authorizations
summary: aid_orders_id_authorization_post
description: |
Create a authorization for an order
scopes:
- admin:shopping
- write:shopping
> An authorization event will be added to the order
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderAuthorization'
description: order capture
required: true
responses:
'200':
$ref: '#/components/responses/OrderAuthorization'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Create an authorization
sidebarTitle: Create an authorization
/accounts/{aid}/shopping/orders/{order_id}/cancellations/{cancellation_id}:
get:
operationId: aid_orders_id_cancellation_id_get
x-scopes:
- admin:shopping
- read:shopping
tags:
- order.cancellations
summary: aid_orders_id_cancellation_id_get
description: |
Retrieve details about a cancellation
scopes:
- admin:shopping
- read:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
- $ref: '#/components/parameters/CancellationId'
responses:
'200':
$ref: '#/components/responses/OrderCancellation'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Get Cancellation details
sidebarTitle: Get Cancellation details
/accounts/{aid}/shopping/orders/{order_id}/cancellations:
get:
operationId: aid_orders_id_cancellations_get
x-scopes:
- admin:shopping
- read:shopping
tags:
- order.list
summary: aid_orders_id_cancellations_get
description: |
Retrieve list of cancellations for an order
scopes:
- admin:shopping
- read:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
responses:
'200':
$ref: '#/components/responses/OrderCancellationCollection'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Get Cancellation Collection
sidebarTitle: Get Cancellation Collection
post:
operationId: aid_orders_id_cancellation_post
x-scopes:
- admin:shopping
- write:shopping
tags:
- order.cancellations
summary: aid_orders_id_cancellation_post
description: |
Create a cancellation for an order
scopes:
- admin:shopping
- write:shopping
> An cancellation event will be added to the order
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OrderCancellation'
- $ref: '#/components/schemas/OperationReferenceId'
description: order cancellation
required: true
responses:
'200':
$ref: '#/components/responses/OrderCancellation'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Create an cancellation
sidebarTitle: Create an cancellation
/accounts/{aid}/shopping/orders/{order_id}/cancel:
post:
operationId: aid_orders_id_cancel_post
x-scopes:
- admin:shopping
- write:shopping
tags:
- order.status
summary: aid_orders_id_cancel_post
description: |
Cancel the Order
scopes:
- admin:shopping
- write:shopping
> A cancel event will be added to the order
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderCancelledState'
description: order resource
required: true
responses:
'200':
$ref: '#/components/responses/Order'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Cancel Order
sidebarTitle: Cancel Order
/accounts/{aid}/shopping/orders/{order_id}/captures/{capture_id}:
get:
operationId: aid_orders_id_captures_id_get
x-scopes:
- admin:shopping
- read:shopping
tags:
- order.captures
summary: aid_orders_id_captures_id_get
description: |
Retrieve details about a capture
scopes:
- admin:shopping
- read:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
- $ref: '#/components/parameters/CaptureId'
responses:
'200':
$ref: '#/components/responses/OrderCapture'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Get Capture details
sidebarTitle: Get Capture details
/accounts/{aid}/shopping/orders/{order_id}/captures:
get:
operationId: aid_orders_id_captures_get
x-scopes:
- admin:shopping
- read:shopping
tags:
- order.list
summary: aid_orders_id_captures_get
description: |
Retrieve list of captures for an order
scopes:
- admin:shopping
- read:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
responses:
'200':
$ref: '#/components/responses/OrderCaptureCollection'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Get Capture Collection
sidebarTitle: Get Capture Collection
post:
operationId: aid_orders_id_capture_post
x-scopes:
- admin:shopping
- write:shopping
tags:
- order.captures
summary: aid_orders_id_capture_post
description: |
Create a capture for an order
scopes:
- admin:shopping
- write:shopping
> A capture event will be added to the order
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OrderCapture'
- $ref: '#/components/schemas/OperationReferenceId'
description: order capture
required: true
responses:
'200':
$ref: '#/components/responses/OrderCapture'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Create a capture
sidebarTitle: Create a capture
/accounts/{aid}/shopping/orders/{order_id}/close:
post:
operationId: aid_orders_id_close_post
x-scopes:
- admin:shopping
- write:shopping
tags:
- order.status
summary: aid_orders_id_close_post
description: |
Close the order
scopes:
- admin:shopping
- write:shopping
> A close event will be added to the order
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
- $ref: '#/components/parameters/IncludeEvents'
responses:
'200':
$ref: '#/components/responses/Order'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Close order
sidebarTitle: Close order
/accounts/{aid}/shopping/orders/{order_id}/comments/{comment_id}:
delete:
operationId: aid_orders_id_comments_comment_id_delete
x-scopes:
- admin:shopping
- write:shopping
tags:
- order.comments
summary: aid_orders_id_comments_comment_id_delete
description: |
Delete an order comment
scopes:
- admin:shopping
- write:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
- $ref: '#/components/parameters/CommentId'
- $ref: '#/components/parameters/IncludeEvents'
responses:
'200':
$ref: '#/components/responses/Order'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Delete an order comment
sidebarTitle: Delete an order comment
/accounts/{aid}/shopping/orders/{order_id}/comments:
post:
operationId: aid_orders_id_comments_post
x-scopes:
- admin:shopping
- write:shopping
tags:
- order.comments
summary: aid_orders_id_comments_post
description: |
Create a new order comment
scopes:
- admin:shopping
- write:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
- $ref: '#/components/parameters/IncludeEvents'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderComment'
required: true
responses:
'200':
$ref: '#/components/responses/Order'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Create an order comment
sidebarTitle: Create an order comment
/accounts/{aid}/shopping/orders/{order_id}/events:
get:
operationId: aid_orders_id_events_get
x-scopes:
- admin:shopping
- read:shopping
- read:shopping:/orders/ANY/events
tags:
- order.list
summary: aid_orders_id_events_get
description: |
Retrieve a list of latest order events
scopes:
- admin:shopping
- read:shopping
- read:shopping:/orders/ANY/events
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
responses:
'200':
$ref: '#/components/responses/OrderEvents'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Order events collection
sidebarTitle: Order events collection
post:
operationId: aid_orders_id_events_post
x-scopes:
- admin:shopping
- write:shopping
- write:shopping:/orders/ANY/events
tags:
- order.events
summary: aid_orders_id_events_post
description: |
Create a new order event
scopes:
- admin:shopping
- write:shopping
- write:shopping:/orders/ANY/events
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceEvent'
description: order event
required: true
responses:
'200':
$ref: '#/components/responses/OrderEvent'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Create an order event
sidebarTitle: Create an order event
/accounts/{aid}/shopping/orders/{order_id}/open:
post:
operationId: aid_orders_id_open_post
x-scopes:
- admin:shopping
- write:shopping
tags:
- order.status
summary: aid_orders_id_open_post
description: |
Re-open a closed order
scopes:
- admin:shopping
- write:shopping
> A open event will be added to the order
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
- $ref: '#/components/parameters/IncludeEvents'
responses:
'200':
$ref: '#/components/responses/Order'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Open order
sidebarTitle: Open order
/accounts/{aid}/shopping/orders/{order_id}/refunds/{refund_id}:
get:
operationId: aid_orders_id_refunds_id_get
x-scopes:
- admin:shopping
- read:shopping
tags:
- order.refunds
summary: aid_orders_id_refunds_id_get
description: |
Retrieve specific refund
scopes:
- admin:shopping
- read:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
- $ref: '#/components/parameters/RefundId'
responses:
'200':
$ref: '#/components/responses/OrderRefund'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Get Refunds details
sidebarTitle: Get Refunds details
/accounts/{aid}/shopping/orders/{order_id}/refunds:
get:
operationId: aid_orders_id_refunds_get
x-scopes:
- admin:shopping
- read:shopping
tags:
- order.list
summary: aid_orders_id_refunds_get
description: |
Retrieve list of refunds for an order
scopes:
- admin:shopping
- read:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
responses:
'200':
$ref: '#/components/responses/OrderRefundCollection'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Get Refunds Collection
sidebarTitle: Get Refunds Collection
post:
operationId: aid_orders_id_refunds_post
x-scopes:
- admin:shopping
- write:shopping
tags:
- order.refunds
summary: aid_orders_id_refunds_post
description: |
Create a refund for an order
scopes:
- admin:shopping
- write:shopping
> A refund event will be added to the order
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OrderRefund'
- $ref: '#/components/schemas/OperationReferenceId'
description: order refund
required: true
responses:
'200':
$ref: '#/components/responses/OrderRefund'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Create a refund
sidebarTitle: Create a refund
/accounts/{aid}/shopping/orders/{order_id}/sessions/{session_id}:
get:
operationId: aid_orders_id_sessions_id_get
x-scopes:
- admin:shopping
- read:shopping
tags:
- order.sessions
summary: aid_orders_id_sessions_id_get
description: |
Retrieve details about a session
scopes:
- admin:shopping
- read:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
- $ref: '#/components/parameters/SessionId'
responses:
'200':
$ref: '#/components/responses/OrderSession'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Get Session details
sidebarTitle: Get Session details
/accounts/{aid}/shopping/orders/{order_id}/sessions:
get:
operationId: aid_orders_id_sessions_get
x-scopes:
- admin:shopping
- read:shopping
tags:
- order.list
summary: aid_orders_id_sessions_get
description: |
Retrieve list of sessions for an order
scopes:
- admin:shopping
- read:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
responses:
'200':
$ref: '#/components/responses/OrderSessionCollection'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Get Session Collection
sidebarTitle: Get Session Collection
post:
operationId: aid_orders_id_session_post
x-scopes:
- admin:shopping
- write:shopping
tags:
- order.sessions
summary: aid_orders_id_session_post
description: |
Initiate a payment session for the order.
scopes:
- admin:shopping
- write:shopping
> A session event will be added to the order
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OrderSession'
- $ref: '#/components/schemas/SessionExpress'
- required:
- url
- profile_id
properties:
profile_id:
type: string
description: |
Configuration profile for the session to create
url:
$ref: '#/components/schemas/SessionUrls'
merchant_reference:
type: string
shipping_option:
$ref: '#/components/schemas/ShippingOption'
description: order session
required: true
responses:
'200':
$ref: '#/components/responses/OrderSession'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Create a session
sidebarTitle: Create a session
/accounts/{aid}/shopping/orders/{order_id}:
get:
operationId: aid_orders_id_get
x-scopes:
- admin:shopping
- read:shopping
tags:
- order
summary: aid_orders_id_get
description: |
Retrieve Order details
scopes:
- admin:shopping
- read:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
- $ref: '#/components/parameters/IncludeEvents'
responses:
'200':
$ref: '#/components/responses/Order'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Get Order
sidebarTitle: Get Order
put:
operationId: aid_orders_id_put
x-scopes:
- admin:shopping
- write:shopping
tags:
- order
summary: aid_orders_id_put
description: |
Update an order
scopes:
- admin:shopping
- read:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
- $ref: '#/components/parameters/IncludeEvents'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OrderUpdate'
- properties:
items:
type: array
items:
type: object
required:
- line_id
properties:
line_id:
type: integer
description: >
The number of the line (or id), must be unique
between all items.
example: 1
external_links:
type: array
items:
$ref: '#/components/schemas/OrderExternalLink'
description: order update resource
required: true
responses:
'200':
$ref: '#/components/responses/Order'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Put Order
sidebarTitle: Put Order
/accounts/{aid}/shopping/orders:
get:
operationId: aid_orders_get
x-scopes:
- admin:shopping
- read:shopping
tags:
- order.list
summary: aid_orders_get
description: |
Retrieve a list of orders
scopes:
- admin:shopping
- read:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/StartingAfter'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/OrderStatus'
- $ref: '#/components/parameters/OrderPaymentStatus'
- $ref: '#/components/parameters/CreatedAtGte'
- $ref: '#/components/parameters/CreatedAtLte'
- $ref: '#/components/parameters/IncludeEvents'
- $ref: '#/components/parameters/OrderPaymentCardBrands'
- $ref: '#/components/parameters/OrderPaymentCardNumbers'
- $ref: '#/components/parameters/OrderPaymentPsp'
- $ref: '#/components/parameters/OrderPaymentProduct'
- $ref: '#/components/parameters/OrderPaymentProductType'
- $ref: '#/components/parameters/OrderNetAmountGte'
- $ref: '#/components/parameters/OrderNetAmountLte'
- $ref: '#/components/parameters/OrderCurrency'
- $ref: '#/components/parameters/OrderSearch'
- $ref: '#/components/parameters/OrderItineraryTravelMode'
- $ref: '#/components/parameters/OrderItineraryArrivalAddress'
- $ref: '#/components/parameters/OrderItineraryDepartureAddress'
- $ref: '#/components/parameters/OrderItemsDiscountLinesDiscountType'
responses:
'200':
$ref: '#/components/responses/ExtendedOrderCollection'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Orders collection
sidebarTitle: Orders collection
/accounts/{aid}/shopping/stores/{store_id}/orders/{order_id}:
get:
operationId: aid_stores_sid_orders_id_get
x-scopes:
- admin:shopping
- read:shopping
tags:
- store.order
summary: aid_stores_sid_orders_id_get
description: |
Retrieve Order details belonging to a store
scopes:
- admin:shopping
- read:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/StoreIdPath'
- $ref: '#/components/parameters/OrderId'
- $ref: '#/components/parameters/IncludeEventsLimited'
responses:
'200':
$ref: '#/components/responses/Order'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Get Order
sidebarTitle: Get Order
/accounts/{aid}/shopping/stores/{store_id}/orders:
get:
operationId: aid_stores_sid_orders_get
x-scopes:
- admin:shopping
- read:shopping
tags:
- store.order
summary: aid_stores_sid_orders_get
description: |
Retrieve a list of orders belonging to a store
scopes:
- admin:shopping
- read:shopping
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/StoreIdPath'
- $ref: '#/components/parameters/StartingAfter'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/OrderStatus'
- $ref: '#/components/parameters/OrderPaymentStatus'
- $ref: '#/components/parameters/CreatedAtGte'
- $ref: '#/components/parameters/CreatedAtLte'
- $ref: '#/components/parameters/IncludeEventsLimited'
responses:
'200':
$ref: '#/components/responses/ExtendedOrderCollection'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/ServerError'
x-mint:
metadata:
title: Orders collection
sidebarTitle: Orders collection
x-tagGroups:
- name: Basket
tags:
- draft
- draft.items
- name: Order
tags:
- order
- order.events
- order.comments
- order.status
- name: Payment management
tags:
- order.sessions
- order.authorizations
- order.captures
- order.refunds
- order.cancellations
- name: Resources
tags:
- order.list
- customer.order
- store.order
servers:
- url: https://api.dintero.com/v1
- url: https://test.dintero.com/v1
components:
parameters:
accountId:
name: aid
description: |
An id that uniquely identifies the account.
in: path
required: true
schema:
type: string
format: ^[PT]{1}\d{8}$
minLength: 9
maxLength: 9
CustomerIdPath:
name: customer_id
in: path
description: The resource identifier string
required: true
schema:
type: string
OrderId:
name: order_id
in: path
description: The resource identifier string
required: true
schema:
type: string
IncludeEventsLimited:
name: include_events
in: query
description: |
include order events in response
required: false
explode: true
schema:
type: array
items:
type: string
enum:
- 'false'
- 'true'
- service-event
default:
- 'false'
StartingAfter:
name: starting_after
in: query
description: |
cursor for use in pagination. starting_after is an object ID
that defines your place in the list. For instance, if you make
a list request and receive 100 objects, ending with `obj_foo`,
your subsequent call can include `starting_after=obj_foo`
in order to fetch the next page of the list.
required: false
schema:
type: string
format: uuid
Limit:
name: limit
in: query
description: |
A limit on the number of objects to be returned. Limit can range
between 1 and 100 items, and the default is 10 items.
schema:
type: integer
minimum: 1
maximum: 100
default: 10
OrderStatus:
name: status
in: query
description: |
filter by order status
explode: true
schema:
type: array
items:
type: string
enum:
- open
- closed
- cancelled
OrderPaymentStatus:
name: payment_status
in: query
description: |
filter by payment status
explode: true
schema:
type: array
items:
type: string
enum:
- pending
- partially_paid
- paid
- partially_refunded
- refunded
CreatedAtGte:
name: created_at.gte
in: query
description: |
filter by created_at, greater than or equal (after)
schema:
type: string
format: date
CreatedAtLte:
name: created_at.lte
in: query
description: |
filter by created_at, less than or equal (before)
schema:
type: string
format: date
ResourceId:
name: id
in: path
description: The resource identifier string
required: true
schema:
type: string
format: uuid
LineId:
name: line_id
in: path
description: The resource identifier string
required: true
schema:
type: integer
ApplyDiscounts:
name: apply_discounts
in: query
description: |
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`.
schema:
type: boolean
default: false
CustomerId:
name: customer_id
in: query
description: The resource identifier string
schema:
type: string
DraftOrderStatus:
name: status
in: query
description: |
filter by draft order status
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- open
- completed
- deleted
OrderNetAmountGte:
name: net_amount.gte
in: query
description: Lower limit for filtering on order net_amount.
schema:
type: integer
minimum: 0
OrderNetAmountLte:
name: net_amount.lte
in: query
description: Upper limit for filtering on order net_amount.
schema:
type: integer
minimum: 0
OrderCurrency:
in: query
name: currency
description: |
Filter on order currency (3-letter currency code)
explode: true
schema:
type: array
items:
type: string
format: iso-4217
OrderSearch:
in: query
name: search
description: |
Will try to match the search to either order_id, external_ids or
customer phone_number, email, name or customer_id.
schema:
type: string
AuthorizationId:
name: authorization_id
in: path
description: The resource identifier string
required: true
schema:
type: string
format: uuid
CancellationId:
name: cancellation_id
in: path
description: The resource identifier string
required: true
schema:
type: string
format: uuid
CaptureId:
name: capture_id
in: path
description: The resource identifier string
required: true
schema:
type: string
format: uuid
IncludeEvents:
name: include_events
in: query
description: |
include order events in response
required: false
explode: true
schema:
type: array
items:
type: string
enum:
- 'false'
- 'true'
- api-event
- service-event
default:
- 'false'
CommentId:
name: comment_id
in: path
description: The resource identifier string
required: true
schema:
type: string
RefundId:
name: refund_id
in: path
description: The resource identifier string
required: true
schema:
type: string
format: uuid
SessionId:
name: session_id
in: path
description: The resource identifier string
required: true
schema:
type: string
OrderPaymentCardBrands:
name: card_brand
in: query
description: Filter on payment details, the card brand for payment
explode: true
schema:
type: array
items:
type: string
OrderPaymentCardNumbers:
name: card_number
in: query
description: Filter on payment details, the last 4 numbers for the card
explode: true
schema:
type: array
items:
type: string
format: \s{4}
OrderPaymentPsp:
name: psp
in: query
description: Filter on payment details, psp
explode: true
schema:
type: array
items:
type: string
OrderPaymentProduct:
name: payment_product
in: query
description: Filter on payment details, payment product
explode: true
schema:
type: array
items:
type: string
OrderPaymentProductType:
name: payment_product_type
in: query
description: Filter on payment details, payment product type
explode: true
schema:
type: array
items:
type: string
OrderItineraryTravelMode:
in: query
name: itinerary_travel_mode
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- BUS
- CAR
- FERRY
- METRO
- TAXI
- TRAIN
- TRAM
- WALK
- WAIT
- CUSTOM
OrderItineraryArrivalAddress:
in: query
name: itinerary_arrival_address
schema:
type: string
OrderItineraryDepartureAddress:
in: query
name: itinerary_departure_address
schema:
type: string
OrderItemsDiscountLinesDiscountType:
in: query
name: items_discount_lines_discount_type
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- customer
- periodic
- manual
- loyalty
- total
- employee
- external
StoreIdPath:
name: store_id
in: path
description: The resource identifier string
required: true
schema:
type: string
responses:
Order:
description: order
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Order'
- $ref: '#/components/schemas/OrderEvents'
AccessForbidden:
description: Access forbidden, invalid JWT token was used
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ServerError:
description: Unexpected Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ExtendedOrderCollection:
description: order collection
content:
application/json:
schema:
type: object
required:
- orders
properties:
orders:
type: array
items:
allOf:
- $ref: '#/components/schemas/Order'
- $ref: '#/components/schemas/OrderEvents'
BadRequest:
description: Bad / Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
DraftOrderComplete:
description: Draft completed
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BasicDraft'
- required:
- orders
properties:
orders:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Order'
DraftOrderUpdated:
description: draft order was updated
content:
application/json:
schema:
$ref: '#/components/schemas/DraftOrder'
DraftOrder:
description: draft order
content:
application/json:
schema:
$ref: '#/components/schemas/DraftOrder'
DraftOrderCollection:
description: draft order collection
content:
application/json:
schema:
type: object
required:
- draft_orders
properties:
draft_orders:
type: array
items:
$ref: '#/components/schemas/DraftOrder'
OrderAuthorization:
description: authorization
content:
application/json:
schema:
$ref: '#/components/schemas/OrderAuthorization'
OrderAuthorizationCollection:
description: authorization collection
content:
application/json:
schema:
type: object
required:
- authorizations
properties:
authorizations:
type: array
items:
$ref: '#/components/schemas/OrderAuthorization'
Conflict:
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
OrderCancellation:
description: cancellation
content:
application/json:
schema:
$ref: '#/components/schemas/OrderCancellation'
OrderCancellationCollection:
description: cancellation collection
content:
application/json:
schema:
type: object
required:
- cancellations
properties:
cancellations:
type: array
items:
$ref: '#/components/schemas/OrderCancellation'
OrderCapture:
description: capture
content:
application/json:
schema:
$ref: '#/components/schemas/OrderCapture'
OrderCaptureCollection:
description: capture collection
content:
application/json:
schema:
type: object
required:
- captures
properties:
captures:
type: array
items:
$ref: '#/components/schemas/OrderCapture'
OrderEvents:
description: order events
content:
application/json:
schema:
$ref: '#/components/schemas/OrderEvents'
OrderEvent:
description: event
content:
application/json:
schema:
$ref: '#/components/schemas/OrderStatusEvent'
OrderRefund:
description: refund
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRefund'
OrderRefundCollection:
description: refund collection
content:
application/json:
schema:
type: object
required:
- refunds
properties:
refunds:
type: array
items:
$ref: '#/components/schemas/OrderRefund'
OrderSession:
description: session
content:
application/json:
schema:
$ref: '#/components/schemas/OrderSession'
OrderSessionCollection:
description: session collection
content:
application/json:
schema:
type: object
required:
- sessions
properties:
sessions:
type: array
items:
$ref: '#/components/schemas/OrderSession'
requestBodies:
aid_draft_orders_id_items_line_id_putData:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/LineItem'
- $ref: '#/components/schemas/CurrencyConversion'
description: draft line item resource
required: true
DraftOrder:
content:
application/json:
schema:
$ref: '#/components/schemas/DraftOrder'
description: draft order resource
required: true
securitySchemes:
JWT:
type: http
description: >
Bearer authentication (token authentication) should be used for
accessing the API.
Use [Get Token](/api-reference/authenticate/aid_auths_oauth_token_post)
to get an access token for client credentials.
Pass the token in the request header:
Authorization: Bearer {access_token}
where the **access_token** is JSON Web Tokens (JWT).
scheme: bearer
bearerFormat: JWT
schemas:
ApiEvent:
type: object
x-discriminator-value: api-event
allOf:
- $ref: '#/components/schemas/OrderEventBase'
- $ref: '#/components/schemas/RequestEvent'
- properties:
draft_id:
type: string
readOnly: true
description: |
Included in audit events where the order was created or updated
by a draft.
event_type:
type: string
enum:
- api-event
title: api-event
OrderStatusEvent:
type: object
x-discriminator-value: service-event
allOf:
- $ref: '#/components/schemas/OrderEventBase'
- $ref: '#/components/schemas/Object'
- $ref: '#/components/schemas/ServiceEvent'
- properties:
event_type:
type: string
enum:
- service-event
title: service-event
Entity:
type: object
properties:
id:
type: string
format: uuid
description: |
An UUID that uniquely identifies the resource
readOnly: true
created_at:
type: string
format: date-time
description: |
The date-time when the resource was created
readOnly: true
created_by:
type: string
example: 1c92f7e1-2897-4d46-bdcc-c127a914fb4e
description: |
The ID of the user/client created the resource
readOnly: true
updated_at:
type: string
format: date-time
description: |
The date-time when the resource was last updated
readOnly: true
deleted_by:
type: string
example: 1c92f7e1-2897-4d46-bdcc-c127a914fb4e
description: |
The ID of the user/client created the resource
readOnly: true
deleted_at:
type: string
format: date-time
readOnly: true
ResourceId:
type: string
description: The resource ID. Defaults to UUID v4
maxLength: 40
example: bd04c959-d159-49b4-a096-2d84e014a8da
ServerTimestamp:
type: string
description: Read-only timestamp, automatically assigned on back-end.
format: date-time
readOnly: true
OrderCancelledState:
type: object
properties:
cancelled_reason:
description: |
The reason why the order was canceled.
- **customer**: The customer cancelled the order
- **declined**: The payment was declined
- **other**: Any reson
example: customer
cancelled_by:
description: |
The ID of the user/client that cancelled the order
readOnly: true
allOf:
- $ref: '#/components/schemas/ResourceId'
cancelled_at:
description: |
The date and time ( ISO 8601 format) when the order was canceled.
readOnly: true
allOf:
- $ref: '#/components/schemas/ServerTimestamp'
OrderCloseState:
type: object
properties:
closed_by:
description: |
The ID of the user/client that cancelled the order
readOnly: true
allOf:
- $ref: '#/components/schemas/ResourceId'
closed_at:
description: |
The date and time ( ISO 8601 format) when the order was canceled.
allOf:
- $ref: '#/components/schemas/ServerTimestamp'
OrderStatusState:
type: object
properties:
status:
description: |
Order status
readOnly: true
default: open
type: string
enum:
- open
- closed
- cancelled
payment_status:
description: |
The status of payments associated with the order
- **pending**: The payments are pending
- **paid**: The payments has been paid
- **partially_refunded**: The payments has been partially refunded
- **refunded**: The payments has been partially refunded
type: string
readOnly: true
default: pending
enum:
- pending
- partially_paid
- paid
- partially_refunded
- refunded
Person:
type: object
properties:
first_name:
type: string
example: John
last_name:
type: string
example: Doe
Address:
type: object
required:
- address_line
- postal_place
- country
properties:
address_line:
type: string
example: Sommerkroveien 34
address_line_2:
type: string
example: PB 123
postal_code:
type: string
example: '0349'
postal_place:
type: string
example: Oslo
latitude:
type: number
example: 59.942112
longitude:
type: number
example: 10.716991
country:
type: string
format: iso3166-alpha2
description: |
ISO 3166-1 country code
example: 'NO'
Customer:
type: object
allOf:
- $ref: '#/components/schemas/Person'
- properties:
id:
type: string
maxLength: 255
description: |
The customer id identifying the customer.
(must not have trailing or leading spaces)
gender:
type: string
example: male
email:
type: string
example: customer@example.com
metadata:
type: object
description: |
A set of key/value pairs that you can attach to a
customer object. It can be useful for storing additional
information about the customer in a structured format.
example:
dob_year: 1985
phone_number:
type: string
description: |
A phone number in E.164 number formatting.
format: ^\+?[1-9]\d{1,14}$
example: '+4799999999'
addresses:
type: array
items:
allOf:
- $ref: '#/components/schemas/Address'
- properties:
type:
type: string
custom_type:
type: string
pays_tax:
type: boolean
description: |
Is customer required to pay tax
example: false
date_of_birth:
format: date
example: '1990-09-20'
nullable: true
type: string
enrolled_by:
type: object
required:
- value
description: The source that recruited the customer
properties:
type:
type: string
description: |
Enrollment type, e.g. `url`, `store`, `qr_code`, any string
example: url
value:
example: https://facebook.com
nullable: true
type: string
favorite_store:
description: customer favorite store
nullable: true
type: string
company:
type: object
required:
- bussiness_name
description: |
Company details, supported when type is Company
properties:
organization_number:
type: string
description: Companys identification number
example: 123456789MVA
bussiness_name:
type: string
example: TKP tech AS
department:
type: string
description: companys department
example: sales department
industry:
type: string
example: computer industry
website:
type: string
number_of_employees:
type: string
marketing_consent:
type: object
description: Customers consent for marketing in different channels
properties:
sms:
type: object
properties:
consent:
type: boolean
example: true
updated_at:
readOnly: true
type: string
format: date-time
example: '2018-01-12T13:42:00Z'
description: |
The date-time when the resource was last updated:
email:
type: object
properties:
consent:
type: boolean
example: true
updated_at:
readOnly: true
type: string
format: date-time
example: '2018-01-12T13:42:00Z'
description: |
The date-time when the resource was last updated:
status:
type: string
description: |
Status of the customer
term:
description: The term and condition accepted by the customer
properties:
id:
type: string
type:
type: string
enum:
- customer
- company
- contact
- employee
- other
description: |
Describe type of an customer.
Company only allowed to be set when the type is "Company"
GrossAmount:
type: integer
example: 39800
description: |
Monetary amount in smallest unit for the currency
before discounts
NetAmount:
type: integer
example: 27840
description: |
Monetary amount in smallest unit for the currency
after discounts
ContactObject:
type: object
allOf:
- $ref: '#/components/schemas/Address'
- $ref: '#/components/schemas/Person'
- properties:
comment:
type: string
description: |
Comment about the address
example: 5th floor, use doorbell.
OrderItineraryAddress:
type: object
properties:
id:
type: string
name:
type: string
address_line:
type: string
example: Sommerkroveien 34
address_line_2:
type: string
example: PB 123
postal_code:
type: string
example: '0349'
postal_place:
type: string
example: Oslo
latitude:
type: number
example: 59.942112
longitude:
type: number
example: 10.716991
country:
type: string
format: iso3166-alpha2
description: |
ISO 3166-1 country code
example: 'NO'
external_ids:
description: |
External IDs related to the address.
items:
type: object
required:
- id
- source
properties:
id:
type: string
source:
type: string
description:
type: string
ItineraryTravelMode:
type: string
enum:
- BUS
- CAR
- FERRY
- METRO
- TAXI
- TRAIN
- TRAM
- WALK
- WAIT
- CUSTOM
OrderTravelItinerary:
type: object
description: |
Travel itinerary leg
properties:
id:
type: string
operator:
type: string
arrival_address:
$ref: '#/components/schemas/OrderItineraryAddress'
arrival_at:
type: string
format: datetime
departure_address:
$ref: '#/components/schemas/OrderItineraryAddress'
departure_at:
type: string
format: datetime
travel_mode:
$ref: '#/components/schemas/ItineraryTravelMode'
route_id:
type: string
vehicle_id:
type: string
summary:
type: string
distance:
required:
- value
properties:
value:
type: integer
format: meter
duration:
type: object
required:
- value
properties:
value:
type: integer
format: minute
tickets:
type: array
minItems: 1
items:
properties:
class:
type: string
line:
type: string
seat:
type: string
zone:
type: string
passenger_id:
type: array
minItems: 1
items:
type: string
line_ids:
type: array
description: |
related order items
minItems: 1
items:
type: integer
waypoints:
type: array
items:
type: object
required:
- latitude
- longitude
properties:
display_name:
type: string
latitude:
type: number
longitude:
type: number
arrival_schedule_at:
type: string
format: datetime
departure_schedule_at:
type: string
format: datetime
OrderExternalId:
description: >-
External IDs related to the order. Search on all external ids are
supported
type: object
required:
- id
- source
properties:
id:
type: string
source:
type: string
description:
type: string
OrderUpdate:
type: object
properties:
customer:
$ref: '#/components/schemas/Customer'
gross_amount:
allOf:
- $ref: '#/components/schemas/GrossAmount'
readOnly: true
example: 59800
net_amount:
allOf:
- $ref: '#/components/schemas/NetAmount'
example: 47840
readOnly: true
total_discount:
type: integer
example: 23130
minimum: 0
readOnly: true
description: |
Monetary amount in smallest unit for the currency
total_manual_discount_amount:
type: integer
example: 0
minimum: 0
readOnly: true
description: Monetary amount in smallest unit for the currency
shipping_address:
$ref: '#/components/schemas/ContactObject'
billing_address:
$ref: '#/components/schemas/ContactObject'
metadata:
type: object
description: |
Additional data related to the order
comment:
type: string
maxLength: 255
description: |
Comment on the order
salesperson_id:
type: string
description: |
Id of the sales person if other then the operator
salesperson_name:
type: string
description: |
Name of the sales person
delivery_at:
type: string
format: date-time
description: >
Requested delivery time by the customer, default value is ASAP
relative to
when the order was created.
pickup_at:
type: string
format: date-time
description: |
Requested pickup time for the courier
courier_id:
type: string
description: |
Id of the courier responsible for the delivery
pre_order:
type: boolean
description: >
Customer requested the delivery to be later, i.e not ASAP, see
delivery_at
for when the delivery should be completed.
time_to_live:
type: integer
example: 94672800
minimum: 86400
description: |
Time-To-Live (TTL) for the order created in seconds.
The value is interpreted as a delta from the time that an
order was last modified (update_at).
All drafts related to an order will be deleted when the TTL
expires and the order will be emptied for all data except
- order_number
- order_id
- external_ids
- created_at
- updated_at
- deleted_at
itinerary:
type: array
items:
$ref: '#/components/schemas/OrderTravelItinerary'
external_ids:
type: array
items:
$ref: '#/components/schemas/OrderExternalId'
items:
type: array
description: |
Update status on order items
items:
type: object
properties:
status:
type: string
TaxItem:
type: object
properties:
amount:
type: integer
example: 5584
description: |
Monetary amount in smallest unit for the currency
amount_dwh:
type: string
example: '5584.0440'
description: Monetary value with decimal
exempt:
type: boolean
example: false
included_in_price:
type: boolean
example: true
percentage:
type: number
example: 25
tax_basis:
type: integer
example: 27920
description: Total monetary value without tax
tax_basis_dwh:
type: string
example: '27920.22'
description: Total monetary value without tax in decimal
tax_code:
type: string
example: '3'
tax_group:
type: string
example: Vmva-høy
Dimension:
type: object
description: |
Identify item attributes, such as size and color
properties:
color:
type: string
size:
type: string
style:
type: string
config:
type: string
variant:
type: string
DiscountItem:
type: object
required:
- amount
properties:
amount:
type: integer
example: 23130
description: |
Monetary amount in smallest unit for the currency
percentage:
type: number
description: |
Optional, set if the amount given was from a percentage discount
example: 10
discount_type:
type: string
enum:
- customer
- periodic
- manual
- loyalty
- total
- employee
- external
discount_subtype:
type: string
description: |
Custom subtype details
maxLength: 120
example: campaign-periode-q3
discount_id:
type: string
example: 766da0ef-9283-42bd-b012-0582344ec53c
description:
type: string
line_id:
type: integer
example: 1
Amount:
type: integer
example: 27840
description: |
Monetary amount in smallest unit for the currency
SalesLocation:
type: object
required:
- id
properties:
id:
type: string
example: SL02
organization_number:
type: string
example: 123456789MVA
name:
type: string
description: |
name of the store, aka trade name of the store
example: SC Oslo
business_name:
type: string
description: |
Official name of the person or entity that owns the store.
example: SC Oslo AS
BillingPayoutRuleDestinationNested:
type: object
description: |
Destination for a split.
- A destination must have `destination` or `destinations` set, not both.
required:
- type
properties:
type:
type: string
enum:
- percentage
- flat_amount
- remaining_amount
value:
description: >
The value that will be used for the payout to the destination or
destinations.
type: string
format: numeric
destination:
type: string
example: account-123
destinations:
type: array
description: |
Array of sub destinations.
minItems: 1
items:
type: object
amount:
readOnly: true
description: >
The split payout calculated for this destination or list of
destinations.
type: integer
BillingPayoutRuleDestination:
type: object
description: |
Destination for a split.
- A destination must have `destination` or `destinations` set, not both.
required:
- type
properties:
type:
type: string
enum:
- percentage
- flat_amount
- remaining_amount
value:
description: >
The value that will be used for the payout to the destination or
destinations.
type: string
format: numeric
destination:
type: string
example: account-123
destinations:
type: array
description: |
Array of sub destinations.
minItems: 1
items:
$ref: '#/components/schemas/BillingPayoutRuleDestinationNested'
amount:
readOnly: true
type: integer
BillingPayoutRule:
type: object
description: |
A Payout rule describes how a payout should be
splitted between multiple destinations.
required:
- rule_id
- rule_type
- destinations
properties:
account_id:
type: string
description: |
An id that uniquely identifies the account.
format: ^[PT]{1}\d{8}$
readOnly: true
rule_type:
type: string
example: order.items.store.id
rule_id:
type: string
description: |
Unique ID given the rule type.
example: sc029
rule_version:
readOnly: true
type: number
format: integer
example: 1
destinations:
description: >
Destinations for the payout splits tree. The splitting is done
in the order of the destinations.
- A destination must include a `destination` or `destinations`.
- The destination `value` is required for destinations with type
`percentage` and `flat_amount`
type: array
items:
$ref: '#/components/schemas/BillingPayoutRuleDestination'
example:
- type: percentage
value: 10
destinations:
- type: flat_amount
value: '500'
destination: account-a
- type: remaining_amount
destinations:
- type: percentage
value: '5.0'
destination: account-b
- type: flat_amount
value: '500'
destination: account-a
- type: remaining_amount
destinations:
- type: percentage
value: '5'
destination: account-b
- type: percentage
value: '95.0'
destination: account-c
metadata:
type: object
maxProperties: 10
description: |
Additional metadata about the payout rule
SplitPayout:
description: |
The payout split calculated for the item
allOf:
- $ref: '#/components/schemas/BillingPayoutRule'
- example:
destinations:
- type: percentage
value: '10'
amount: 4000
destinations:
- amount: 500
- destinations:
- amount: 3500
- amount: 500
- destinations:
- amount: 192
- amount: 38308
LineItem:
type: object
required:
- gross_amount
- tax_lines
properties:
id:
type: string
description: |
The ID or SKU of the product on the line
example: '175938'
status:
type: string
description: The item status
metadata:
type: object
description: |
Additional details about the item, key values will be included
as `extra_info` in the receipt.
groups:
type: array
description: |
The groups the product on the line belongs to
example:
- id: B234
name: Stol
- id: B1
name: Møbel
items:
type: object
required:
- id
properties:
id:
type: string
description: group id
name:
type: string
description: group name
line_id:
type: integer
description: |
The number of the line (or id), must be unique between all items.
example: 1
quantity:
type: number
description: |
The quantity of the product in the item line.
example: 2
default: 1
gross_amount:
allOf:
- $ref: '#/components/schemas/GrossAmount'
net_amount:
allOf:
- $ref: '#/components/schemas/NetAmount'
readOnly: true
tax_lines:
type: array
minItems: 1
items:
$ref: '#/components/schemas/TaxItem'
description:
type: string
example: Stablestol for utendørsbruk
description_alias:
type: string
description: |
Short description / title of the product
example: Staplestol
is_changed:
type: boolean
default: false
description: |
Discount applied to gross amount
readOnly: true
eligible_for_discount:
type: boolean
example: true
dimension:
$ref: '#/components/schemas/Dimension'
discount_lines:
type: array
items:
$ref: '#/components/schemas/DiscountItem'
additions:
type: array
description: |
Additions, customization of the item. The gross_amount
for an `addition` should be included in the item `gross_amount` and
included in the `tax_lines` if applicable.
items:
type: object
properties:
id:
example: C1203
type: string
description:
type: string
example: Extra Cheese
quantity:
type: number
description: |
The quantity of the addition
default: 1
gross_amount:
example: 1000
allOf:
- $ref: '#/components/schemas/Amount'
groups:
type: array
description: |
The groups the product on the line belongs to
example:
- id: B234
name: Stol
- id: B1
name: Møbel
items:
type: object
required:
- id
properties:
id:
type: string
description: group id
name:
type: string
description: group name
store:
allOf:
- $ref: '#/components/schemas/SalesLocation'
- properties:
comment:
type: string
description: |
Comment to the sales location
maxLength: 255
external_id:
type: string
example: SL02-94821948
description: External ID related to the item.
related_item:
type: object
description: >
Relationship with another line item.
An item with a `required` relationship with another line item
will be removed from the order if the related item is removed
An item with `optional` relationship will remain in the order if
the related line is removed, the `related_item` will be cleared as
the
line it relates to does not exist anymore
An item with `reversed` relationship is an item that is reversing
another item. An item with the `reversed` relationship we be
removed from the order if the related item is removed
required:
- line_id
- type
properties:
line_id:
type: integer
type:
type: string
enum:
- required
- optional
- reversed
salesperson_id:
type: string
description: |
Id of the sales person if other then the operator
salesperson_name:
type: string
description: |
Name of the sales person
comment:
type: string
maxLength: 255
description: |
comment on the item
version:
type: number
readOnly: true
reversed_reason:
type: string
description: |
Reverse the item from an order
Applicable only if the draft is created to update an
existing order
dynamic_payout:
description: |
Specify the payout rule that should be used when calculating the
payout split for this item.
required:
- rule_type
- rule_id
properties:
rule_type:
type: string
rule_id:
type: string
payout:
readOnly: true
allOf:
- $ref: '#/components/schemas/SplitPayout'
CurrencyConversion:
type: object
properties:
original_currency:
type: string
format: iso-4217
example: SEK
maxLength: 3
description: |
Representing the currency in which the item was originally priced
original_gross_amount:
type: integer
example: 39800
description: |
Monetary amount in smallest unit for the original currency
conversion_rate_ppm:
type: integer
example: 1099000
description: |
Scaled integer (parts per million) representing the conversion rate
used to translate `original_currency` gross amount into the orders
`currency`.
Example: If 1 SEK = 1.099 NOK, then `conversion_rate_ppm = 1099000`
conversion_rate_timestamp:
type: string
format: date-time
description: |
The timestamp indicating when the exchange rate was determined.
conversion_rate_source:
type: string
description: Identifier of the source of the exchange rate
example: ecb
OrderObject:
allOf:
- $ref: '#/components/schemas/OrderUpdate'
- required:
- currency
properties:
version:
type: integer
readOnly: true
description: |
The version of the order. Incremented when the order
is updated.
type:
type: string
description: |
Describe the type of an order.
example: delivery
order_number:
type: string
example: order123456
currency:
type: string
format: iso-4217
example: NOK
maxLength: 3
description: |
The tree-character ISO-4217 currency
order_id:
type: string
description: |
The order id, defaults to the resource id, UUID.
> Requires split_draft option to be disabled.
maxLength: 255
minLength: 1
items:
type: array
minItems: 1
items:
allOf:
- $ref: '#/components/schemas/LineItem'
- $ref: '#/components/schemas/CurrencyConversion'
time_to_live_expires_at:
type: string
format: data-time
description: |
The date-time when the resource expires.
multiple_authorizations:
type: boolean
description: |
Allow multiple authorizations per order item
OrderPaymentDetails:
type: object
readOnly: true
properties:
remaining_capture_amount:
$ref: '#/components/schemas/Amount'
remaining_refund_amount:
$ref: '#/components/schemas/Amount'
remaining_cancellation_amount:
$ref: '#/components/schemas/Amount'
Link:
type: object
properties:
href:
description: The link URL
type: string
rel:
description: The link type
type: string
enum:
- draft
- events
- order
- receipt
- self
- session
- session-checkout
- transaction
required:
- href
- rel
OrderSession:
type: object
required:
- items
properties:
id:
readOnly: true
allOf:
- $ref: '#/components/schemas/ResourceId'
created_at:
readOnly: true
description: |
The date-time when the resource was created
allOf:
- $ref: '#/components/schemas/ServerTimestamp'
created_by:
readOnly: true
description: |
The ID of the user/client created the resource
allOf:
- $ref: '#/components/schemas/ResourceId'
amount:
readOnly: true
type: integer
example: 27840
description: |
Monetary amount in smallest unit for the currency success:
description: |
The result from the operation.
type: boolean
items:
description: |
Selected items from the order
type: array
items:
allOf:
- required:
- line_id
properties:
amount:
readOnly: true
type: integer
example: 27840
description: |
Monetary amount in smallest unit for the currency
line_id:
type: string
description: |
Selected order items to include in the session
processed_at:
type: string
format: date-time
description: |
The date and time when the capture was processed by payment
gateway
metadata:
type: object
description: |
Additional details about the operation
_links:
type: array
description: The links related to resource
readOnly: true
items:
$ref: '#/components/schemas/Link'
OrderOperationCard:
type: object
properties:
masked_pan:
type: string
example: 4444 **** **** 4448
type:
type: string
example: Credit
brand:
type: string
example: Visa
metadata:
type: object
description: |
Additional details about the payment
OrderOperationItems:
type: object
required:
- items
properties:
items:
description: |
Selected items from the order
type: array
items:
allOf:
- $ref: '#/components/schemas/CurrencyConversion'
- type: object
required:
- amount
- line_id
properties:
amount:
$ref: '#/components/schemas/Amount'
line_id:
type: integer
processed_at:
type: string
format: date-time
description: >
The date and time when the payment operation was processed by
payment
gateway
processed_by:
type: string
description: |
The gateway the processed the payment operation
example: dintero-checkout
payment_details:
type: object
properties:
psp:
type: string
example: Bambora
payment_id:
type: string
payment_product:
type: string
example: bambora
payment_product_type:
type: string
example: bambora.creditcard
card:
$ref: '#/components/schemas/OrderOperationCard'
metadata:
type: object
description: |
Additional details about the operation
OrderOperationRead:
type: object
properties:
id:
readOnly: true
allOf:
- $ref: '#/components/schemas/ResourceId'
created_at:
readOnly: true
description: |
The date-time when the resource was created
allOf:
- $ref: '#/components/schemas/ServerTimestamp'
created_by:
readOnly: true
description: |
The ID of the user/client created the resource
allOf:
- $ref: '#/components/schemas/ResourceId'
amount:
readOnly: true
type: integer
example: 27840
description: >
Total monetary amount for the operation in smallest unit for the
currency
success:
description: |
The result from the operation.
type: boolean
_links:
type: array
description: The links related to resource
readOnly: true
items:
$ref: '#/components/schemas/Link'
items:
type: array
items:
type: object
properties:
payout:
type: object
readOnly: true
description: |
Describe the payout for the operation item
required:
- rule_id
- rule_type
- destinations
properties:
rule_id:
type: string
rule_type:
type: string
destinations:
type: array
readOnly: true
minItems: 1
description: |
How the operation monetary amount should be split given
the payout rule. The items are aggregated by destination
items:
type: object
required:
- destination
- amount
properties:
destination:
type: string
description: |
The destination reciving the payout
amount:
type: integer
description: |
The monetary amount reserved for the destination
authorization_id:
description: |
The authorization for this operation. Only included if the order
was created with `multiple_authorizations` option enabled
allOf:
- $ref: '#/components/schemas/ResourceId'
OrderAuthorization:
allOf:
- $ref: '#/components/schemas/OrderOperationItems'
- $ref: '#/components/schemas/OrderOperationRead'
OrderCapture:
allOf:
- $ref: '#/components/schemas/OrderOperationItems'
- $ref: '#/components/schemas/OrderOperationRead'
OrderRefund:
allOf:
- $ref: '#/components/schemas/OrderOperationItems'
- $ref: '#/components/schemas/OrderOperationRead'
OrderCancellation:
allOf:
- $ref: '#/components/schemas/OrderOperationItems'
- $ref: '#/components/schemas/OrderOperationRead'
OrderOperations:
type: object
properties:
payment_details:
allOf:
- $ref: '#/components/schemas/OrderPaymentDetails'
- properties:
amount_due:
type: integer
example: 27840
description: |
The amount due. The value will be negative if a refund
is required to close the order.
Monetary amount in smallest unit for the currency
remaining_authorization_amount:
$ref: '#/components/schemas/Amount'
sessions:
readOnly: true
type: array
items:
$ref: '#/components/schemas/OrderSession'
description: |
A list of sessions for this order
authorizations:
readOnly: true
type: array
items:
$ref: '#/components/schemas/OrderAuthorization'
description: |
A list of authorizations for this order
captures:
readOnly: true
type: array
items:
$ref: '#/components/schemas/OrderCapture'
description: |
A list of captures for this order
refunds:
readOnly: true
type: array
items:
$ref: '#/components/schemas/OrderRefund'
description: |
A list of refunds for this order
cancellations:
readOnly: true
type: array
items:
$ref: '#/components/schemas/OrderCancellation'
description: |
A list of cancellations for this order
OrderDiscounts:
type: object
properties:
discounts:
type: array
readOnly: true
items:
type: object
properties:
id:
type: string
refs:
type: array
items:
type: object
properties:
id:
type: string
amount:
type: number
statistics:
type: object
properties:
amount:
type: number
stamp:
type: number
usage:
type: number
stamp:
type: number
usages:
type: number
items:
type: array
items:
type: object
properties:
line_id:
type: number
amount:
type: number
OrderStore:
type: object
properties:
store:
allOf:
- $ref: '#/components/schemas/SalesLocation'
- properties:
comments:
type: array
description: |
List of all sales location comments
items:
type: string
maxLength: 255
maximum: 1000
OrderExternalLink:
description: Link to external resources
type: object
required:
- text
- href
properties:
text:
type: string
example: Order Receipt
description: |
The Link text that will be visible to the reader
href:
description: |
The URL to the external resource
type: string
format: uri
example: >-
https://example.dintero.com/receipts/234CC019-8BA9-4DDB-9A40-8C9EE0BB943C?type=pdf
public:
description: |
The external resources is public and requires no
aditional authorization.
type: boolean
LineItemIsuranceAttachment:
type: object
description: Insurance data
properties:
insurance_company:
type: string
insurance_type:
type: string
LineItemReservationAttachment:
type: object
properties:
booking_id:
type: string
description: |
Trip booking number
example: NE 138 47794
line_ids:
type: array
description: |
related order items
minItems: 1
items:
type: integer
passengers:
type: array
minItems: 1
items:
type: object
properties:
id:
type: string
title:
type: string
first_name:
type: string
last_name:
type: string
itinerary:
type: array
description: Itineray data, one item per segment
minItems: 1
items:
type: object
properties:
departure_address:
$ref: '#/components/schemas/Address'
departure_at:
type: string
format: date-time
arrival_address:
$ref: '#/components/schemas/Address'
arrival_at:
type: string
format: date-time
operator:
type: string
example: SAS
class:
type: string
line:
type: string
seat:
type: string
zone:
type: string
expires_at:
type: string
format: date-time
activates_at:
type: string
format: date-time
passenger_id:
type: array
minItems: 1
items:
type: string
insurance:
type: array
description: Insurance data
minItems: 1
items:
$ref: '#/components/schemas/LineItemIsuranceAttachment'
LineItemReservationCarAttachment:
type: object
properties:
booking_id:
type: string
description: |
Trip booking number
example: TV 347794
line_ids:
type: array
description: |
related order items
minItems: 1
items:
type: integer
itinerary:
type: array
minItems: 1
description: Car itineray data
items:
type: object
properties:
rental_company:
type: string
example: Avis
drivers_id:
type: array
items:
type: string
pick_up_address:
$ref: '#/components/schemas/Address'
pick_up_at:
type: string
format: date-time
drop_off_address:
$ref: '#/components/schemas/Address'
drop_off_at:
type: string
format: date-time
class:
type: string
drivers:
type: array
minItems: 1
items:
type: string
insurance:
type: array
description: Insurance data
minItems: 1
items:
$ref: '#/components/schemas/LineItemIsuranceAttachment'
OrderAttachments:
type: object
properties:
external_ids:
type: array
items:
$ref: '#/components/schemas/OrderExternalId'
external_links:
type: array
items:
$ref: '#/components/schemas/OrderExternalLink'
itinerary:
type: array
items:
$ref: '#/components/schemas/OrderTravelItinerary'
attachments:
type: array
items:
type: object
properties:
id:
type: string
bus_reservation:
$ref: '#/components/schemas/LineItemReservationAttachment'
car_reservation:
$ref: '#/components/schemas/LineItemReservationCarAttachment'
ferry_reservation:
$ref: '#/components/schemas/LineItemReservationAttachment'
metro_reservation:
$ref: '#/components/schemas/LineItemReservationAttachment'
taxi_reservation:
$ref: '#/components/schemas/LineItemReservationAttachment'
train_reservation:
$ref: '#/components/schemas/LineItemReservationAttachment'
tram_reservation:
$ref: '#/components/schemas/LineItemReservationAttachment'
OrderComment:
type: object
required:
- body
properties:
id:
type: string
description: |
An id that uniquely identifies the resource
readOnly: true
created_at:
type: string
format: date-time
description: |
The date-time when the resource was created
readOnly: true
created_by:
type: string
description: |
The ID of the user/client created the resource
readOnly: true
deleted_by:
type: string
example: 1c92f7e1-2897-4d46-bdcc-c127a914fb4e
description: |
The ID of the user/client created the resource
readOnly: true
deleted_at:
type: string
format: date-time
readOnly: true
body:
type: string
visibility:
type: string
enum:
- private
- public
default: private
description: >
The comment is private, hidden from the
[customer](#tag/customer.order)
OrderComments:
type: object
properties:
comments:
type: array
readOnly: true
items:
$ref: '#/components/schemas/OrderComment'
Order:
type: object
allOf:
- $ref: '#/components/schemas/Entity'
- $ref: '#/components/schemas/OrderCancelledState'
- $ref: '#/components/schemas/OrderCloseState'
- $ref: '#/components/schemas/OrderStatusState'
- $ref: '#/components/schemas/OrderObject'
- $ref: '#/components/schemas/OrderOperations'
- $ref: '#/components/schemas/OrderDiscounts'
- $ref: '#/components/schemas/OrderStore'
- $ref: '#/components/schemas/OrderAttachments'
- $ref: '#/components/schemas/OrderComments'
- properties:
order_id:
type: string
maxLength: 255
minLength: 1
pickup_at:
type: string
format: date-time
description: |
Requested pickup time for the courier
courier_id:
type: string
description: |
Id of the courier responsible for the delivery
delivery_id:
type: string
_links:
type: array
description: The links related to resource
readOnly: true
items:
$ref: '#/components/schemas/Link'
OrderEvent:
discriminator:
propertyName: event_type
mapping:
api-event: '#/components/schemas/ApiEvent'
service-event: '#/components/schemas/OrderStatusEvent'
oneOf:
- $ref: '#/components/schemas/ApiEvent'
- $ref: '#/components/schemas/OrderStatusEvent'
OrderEvents:
type: object
required:
- events
properties:
state:
type: string
description: |
The combined state of all events
- **failure** if any of the events reports as `error` or `failure`
- **pending** if there is no events or if the latest status for
any service is `pending`
- **success** if the latest status for all services is `success`
events:
type: array
items:
$ref: '#/components/schemas/OrderEvent'
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- message
properties:
code:
type: string
description: The code used to identify the error/warning
errors:
type: array
description: The nested error(s) encountered during validation
items:
type: object
message:
type: string
description: The human readable description of the error/warning
BasicDraft:
type: object
properties:
id:
readOnly: true
allOf:
- $ref: '#/components/schemas/ResourceId'
created_at:
description: |
The date-time when the resource was created
readOnly: true
allOf:
- $ref: '#/components/schemas/ServerTimestamp'
created_by:
description: |
The ID of the user/client created the resource
allOf:
- $ref: '#/components/schemas/ResourceId'
readOnly: true
updated_at:
readOnly: true
allOf:
- $ref: '#/components/schemas/ServerTimestamp'
description: |
The date-time when the resource was last updated
deleted_by:
description: |
The ID of the user/client created the resource
readOnly: true
allOf:
- $ref: '#/components/schemas/ResourceId'
deleted_at:
allOf:
- $ref: '#/components/schemas/ServerTimestamp'
readOnly: true
status:
type: string
readOnly: true
description: >
The status of the DraftOrder as it transitions into an Order.
Status is set to `completed` when the DraftOrder is completed and an
Order is created
After a DraftOrder is set to `completed` the only further
modification
that can be made are adding notes or metadata fields
default: open
enum:
- open
- completed
- deleted
_links:
type: array
description: The links related to resource
readOnly: true
minItems: 1
items:
$ref: '#/components/schemas/Link'
Object:
type: object
properties:
id:
readOnly: true
allOf:
- $ref: '#/components/schemas/ResourceId'
created_at:
description: |
The date-time when the resource was created
readOnly: true
allOf:
- $ref: '#/components/schemas/ServerTimestamp'
created_by:
description: |
The ID of the user/client created the resource
allOf:
- $ref: '#/components/schemas/ResourceId'
readOnly: true
RequestEvent:
allOf:
- $ref: '#/components/schemas/Object'
- properties:
version:
type: number
readOnly: true
description: |
The version of the resource when the request was
done.
request:
type: object
readOnly: true
description: |
Included in events that was created when the resource
was updated.
properties:
path:
type: string
method:
type: string
body:
type: string
DraftOrder:
allOf:
- $ref: '#/components/schemas/BasicDraft'
- required:
- order
properties:
version:
type: integer
readOnly: true
description: |
The version of the draft. Incremented when the draft
is updated.
events:
readOnly: true
type: array
items:
$ref: '#/components/schemas/ApiEvent'
options:
type: object
properties:
order_time_to_live:
type: integer
example: 94672800
minimum: 86400
description: |
Time-To-Live (TTL) for the order created in seconds.
The value is interpreted as a delta from the time that an
order was last modified (update_at).
All drafts related to an order will be deleted when the TTL
expires and the order will be emptied for all data except
- order_number
- order_id
- external_ids
- created_at
- updated_at
- deleted_at
generate_order_id:
type: string
description: |
ID format to use when generating the order_id.
- The option cannot be combined with `order.order_id`.
- The option cannot be combined with `options.order_id`
#### Formats
- **UUID**: `########-####-####-####-############`
- **ALPHANUMERIC_9**: `###-###-###`
- **ALPHANUMERIC_9_RESERVE**: `###-###-###`
Generate and reserve the order_id when the draft is created
The draft `order.order_id` will be set with generated order_id.
default: UUID
enum:
- UUID
- ALPHANUMERIC_9
- ALPHANUMERIC_9_RESERVE
order_id:
type: string
description: >
Create a draft for an existing order. The draft items will
be added to the order when the draft is completed.
Use `line_id` to update existing items on the order. Update
of existing items is only allowed if no payments has been
initiated on the order item.
Use `reversed_reason` to reverse an existing item. No
changes
to the quantity or amount is allowed when reversing an order
item.
replace:
type: string
description: >
Create a draft that will replace existing order details. The
option
is only valid for order that has no payment operation
registered
when completing the draft.
- Replacing an order with a draft will not remove existing
api-events
- The option requires `options.order_id` to be set
- The option cannot be combined with `options.split_draft`.
enum:
- order
payout:
type: object
description: |
Enable payout calculation of the order items.
required:
- resolve_rule_id
- resolve_rule_type
properties:
rules:
description: >
Provide dynamic payout rules, overrides existing payout
rules
for the given rule_id.
The list will also be used if items includes
`manual_payout` to
allow any rule_type/rule_id to be used to resolve the
payout rule
for the item.
type: array
minItems: 1
items:
$ref: '#/components/schemas/BillingPayoutRule'
resolve_rule_id:
type: string
description: >
Specify how rule_id should be resolved for each order
item.
- `order.items.store.id`: The rule id will be resolved
using the
item store id. `Requires` that all items has store set, or that
items includes `manual_payout` that specifies the `rule_type` and
`rule_id` that should be used when calculation the payout.
enum:
- order.items.store.id
resolve_rule_type:
type: string
description: >
Specifies the `rule_type` to use when resolving payout
rules for the
order items.
See [Billing
API](/billing-api/payoutrules/aid_billing_payout_rules_get)
split_draft:
type: boolean
default: false
description: |
An draft that contains multiple items with different
stores will be splitted into one order per store.
This option can not be combined with creating a draft
where a store is specified.
serial_order_number_suffix:
type: boolean
default: false
description: |
A serial suffix is added to the order_number
in case where a draft result in multiple orders
No suffix is added in case where only one order
is created when the draft is completed.
Example: `draft.order.order_number=order123`
will result in `order_number=order123-1` and
`order_number=order123-2` if the draft creates
two orders
multiple_authorizations:
type: boolean
default: false
description: |
Allow multiple authorizations per order item
order:
allOf:
- $ref: '#/components/schemas/OrderObject'
- $ref: '#/components/schemas/OrderDiscounts'
- $ref: '#/components/schemas/OrderStore'
- $ref: '#/components/schemas/OrderAttachments'
- properties:
stores:
readOnly: true
description: |
List of all stores involved in the order
type: array
items:
allOf:
- $ref: '#/components/schemas/SalesLocation'
- properties:
comments:
type: array
description: |
List of all sales location comments
items:
type: string
maxLength: 255
maximum: 1000
OperationReferenceId:
type: object
properties:
authorization_id:
description: |
The authorization for this operation. **Required** if the order was
created with `multiple_authorizations` option enabled
allOf:
- $ref: '#/components/schemas/ResourceId'
ServiceEvent:
type: object
required:
- state
- service
- service_status
properties:
state:
type: string
description: |
The state of the event
default: success
enum:
- error
- failure
- success
- pending
description:
type: string
description: |
A short description of the reason for the status
example: food prepared
service:
type: string
description: |
The type of service used, used to differentiate this status from
other services
service_status:
type: string
description: |
The status reported by the service
example: ready_for_pickup
metadata:
type: object
description: |
Additional service data related to the event
example:
pickup_location:
latitude: 37.42242
longitude: -122.08585
postal_code: '0342'
address: Smallwei
_links:
type: array
description: The links related to resource
readOnly: true
minItems: 1
items:
$ref: '#/components/schemas/Link'
RelativeTime:
description: Relative time for delivery or pick-up
type: object
properties:
working_days:
type: array
description: >
The expected range of days until the relative time is reached.
A range of `[0,0]` means the relative time is today. `[0,3]` means
the relative time is within the next 3 days.
example:
- 1
- 2
minItems: 2
maxItems: 2
items:
type: number
minimum: 0
shipping_day_of_week:
type: number
description: |
The day of the week the relative time for shipping is on.
1 is Monday, 2 is Tuesday, ..., 7 is Sunday.
example: 3
minimum: 1
maximum: 7
arrival_day_of_week:
type: number
description: |
The day of the week the relative time for arrival is on.
1 is Monday, 2 is Tuesday, ..., 7 is Sunday.
example: 3
minimum: 1
maximum: 7
OrderAddress:
type: object
description: Address
properties:
first_name:
type: string
example: John
last_name:
type: string
example: Doe
address_line:
type: string
description: Gaustadalleen 21
address_line_2:
type: string
description: PB 123
co_address:
type: string
example: Land Lord
business_name:
type: string
description: Name of the company
postal_code:
type: string
description: The zip code / postal code of the address.
example: '0349'
postal_place:
type: string
description: The name of the postal code
example: Oslo
country:
type: string
format: iso3166-alpha2
description: Country of the location
example: 'NO'
phone_number:
type: string
pattern: ^\+?\d{5,15}$
description: |
mobile number of a person / company, ITU/E.123 format with
international prefix (+PPNNNNNNNNN...)
email:
type: string
description: |
The email address of a person or an organization
latitude:
type: number
longitude:
type: number
comment:
type: string
description: |
Comment about the address
organization_number:
type: string
description: |
The organization number of the customer.
organization_type:
type: string
description: |
Type indicating what kind of organization it is.
customer_reference:
type: string
description: The customer's reference
cost_center:
type: string
description: For companies that needs to specify a cost center.
OpeningHours:
type: object
properties:
open_now:
type: boolean
description: |
Indicates if the location is open now.
example: true
periods:
type: array
items:
type: object
description: |
A period of time when the opening hours are valid.
properties:
opens_at:
type: string
format: time
example: '08:00'
closes_at:
type: string
format: time
example: '16:00'
day_of_week:
type: number
description: |
The day of the week when the opening hours are valid.
example: 1
timezone:
type: string
description: |
The timezone of the location.
example: Europe/Oslo
ShippingAddressDetails:
type: object
description: Additional information about the shipping address
properties:
website_url:
type: string
description: |
The website URL of the customer.
opening_hours:
$ref: '#/components/schemas/OpeningHours'
ShippingOption:
type: object
description: |
A shipping option
required:
- id
- line_id
- amount
- operator
- title
properties:
id:
type: string
description: >
Id of this shipping option product.
The express checkout will group all products with the same id. Used
for
grouping delivery to the same address at different time slots, or
for
grouping deliveries to different pick up points.
example: bring-pick-up-00001
line_id:
type: string
description: |
Unique id of the specific configuration of this shipping product
example: bring-pick-up-00001-location-0a1f6b
countries:
description: Countries where this shipping option can be used
type: array
items:
type: string
format: iso3166-alpha2
example: 'NO'
amount:
type: integer
description: >
The monetary amount of the shipping option, including VAT and
discounts.
In smallest unit for the currency, e.g. cents
example: 3900
vat_amount:
type: integer
description: |
The VAT of the `amount` parameter. Only
used for display purposes.
example: 975
vat:
type: number
description: >
The VAT percentage. Supports up to 2 decimal places. If the vat is
20% the number should be 20, not 0.2.
example: 25
title:
type: string
description: |
A shipping option title. Eg. "Standard"
example: Standard
description:
type: string
description: |
A short description of the shipping option product
example: Pick up at your nearest postal office
delivery_method:
type: string
enum:
- delivery
- pick_up
- unspecified
- none
example: pick_up
operator:
type: string
description: |
Name of company that provides shipping service
example: Bring
operator_product_id:
type: string
description: |
The operators own id for this shipping product
example: pick-up-00001-location-0a1f6b
eta:
description: Estimated time of arrival
type: object
allOf:
- $ref: '#/components/schemas/RelativeTime'
- properties:
starts_at:
type: string
format: date-time
example: '2020-10-14T19:00:00Z'
ends_at:
type: string
format: date-time
example: '2020-10-14T20:00:00Z'
time_slot:
description: A specified time for delivery to customer
type: object
properties:
starts_at:
type: string
format: date-time
example: '2020-10-14T19:00:00Z'
ends_at:
type: string
format: date-time
example: '2020-10-14T20:00:00Z'
pick_up_address:
type: object
allOf:
- $ref: '#/components/schemas/OrderAddress'
- $ref: '#/components/schemas/ShippingAddressDetails'
- properties:
distance:
type: number
description: |
Distance in kilometers from the shipping_address.
metadata:
type: object
description: Additional metadata about the shipping_option
maxProperties: 20
additionalProperties:
oneOf:
- type: string
- type: number
example:
operator_dest: XAB1239
number_x: 1921
environmental_data:
type: object
description: |
Environmental data about the shipping option
required:
- description
properties:
description:
type: string
description: |
A short description of the environmental data, something like
- "Fossil free",
- "Carbon neutral"
- "Low emissions"
- "Renewable Energy Sourced"
- "Eco-certified Fleet"
example: Fossil free
details:
type: array
items:
type: object
required:
- label
- value
properties:
label:
description: |
Give context to the value field. Example:
- "CO2 emissions"
- "Energy consumption"
- "Carbon footprint"
- "Carbon offset"
- "Trees planted"
- "Renewable energy percentage"
type: string
example: Carbon offset
maxLength: 50
value:
type: string
example: 1KG CO2
maxLength: 50
thumbnail_url:
type: string
description: |
URL to a thumbnail of the shipping option. Will be displayed when
redirecting to the session.
Recommended limitations for the image:
- all images should preferrably have the same dimensions
- max file size should be less than 2MB
format: uri
SessionExpressUpdate:
type: object
required:
- shipping_options
properties:
shipping_options:
type: array
description: >
Shipping options that will be presented to the end user after the
end user has submitted a shipping address.
To dynamically update the shipping_options when the
_`order.shipping_address`_ is
changed by the end user in the checkout, use the
_`url.shipping_address_callback_url`_.
If the merchant is not able to ship the order to the end users shipping address, use an empty array.
If there is only one option, a free delivery, the order still has to contain one option with a _`price.amount`_ of 0.
items:
$ref: '#/components/schemas/ShippingOption'
shipping_mode:
type: string
enum:
- shipping_required
- shipping_not_required
default: shipping_required
SessionExpress:
type: object
properties:
express:
description: >
### Present only for _Express Checkout_ sessions.
An _Express Checkout_ session is a session where the end user will
submit a
shipping address and then select a shipping option before the before
a
payment method is selected and the payment is initiated.
Endpoints used in the _Express Checkout_ flow.
1. [Set shipping
address](/checkout-api/view/checkout_sid_json_order_shipping_address_put)
2. [Set shipping
option](/checkout-api/view/checkout_sid_json_order_items_shipping_option_put)
type: object
allOf:
- $ref: '#/components/schemas/SessionExpressUpdate'
- properties:
discount_codes:
description: |
Enable discount codes for Express Checkout
properties:
max_count:
type: number
description: >
Limit how many discount codes can be added by the
customer
callback_url:
type: string
format: uri
pattern: https?://*
example: >-
https://example.com/order/00128110/discount_codes_updated
description: >
URL that Checkout will POST to when the user has
submitted/changed
the discount codes for an express session.
Dintero will not attempt a retry after a failed delivery
attempt.
Following situations is considered as failed delivery
- HTTP status codes that are not 200.
- A request timeout (60 seconds)
- Any connection error such as connection timeout, bad
certificate, etc
The response from the callback will be used to update
the order amount,
items discount_lines and shipping options.
See [POST
example/discount_codes_callback_url](/api-reference/example-session-callbacks/example_discount_codes_callback_url)
for details about the request and response.
shipping_address_callback_url:
type: string
format: uri
pattern: https?://*
example: https://example.com/order/00128110/address_updated
description: >
URL that Checkout will POST to when the end user has
submitted/changed
a shipping address for an express-session.
Dintero will not attempt a retry after a failed delivery
attempt.
Following situations is considered as failed delivery
- HTTP status codes that are not 200.
- A request timeout (60 seconds)
- Any connection error such as connection timeout, bad
certificate, etc
The response from the callback will be used to update the
shipping options.
See [POST
example/shipping_address_callback_url](/api-reference/example-session-callbacks/example_shipping_address_callback_url)
for details about the request and response.
customer_types:
type: array
description: >
Limit the lind of customers that can be submitted via the
address form in the express checkout.
default:
- b2c
- b2b
items:
type: string
enum:
- b2c
- b2b
default_different_billing_shipping_address:
description: >
Configure the default behavior for how Checkout presents the
shipping and billing addresses.
If `[]`, Checkout defaults to assuming the shipping and
billing addresses are the same.
If `["b2b"]`, Checkout defaults to assuming different
addresses for B2B only.
If `["b2c"]`, Checkout defaults to assuming different
addresses for B2C only.
If `["b2b", "b2c"]`, Checkout defaults to assuming different
addresses for all customer types.
If omitted, Checkout defaults to the same behaviour as
setting `[]`.
This will only have an effect if
`allow_different_billing_shipping_address` is set.
type: array
default: []
items:
type: string
enum:
- b2c
- b2b
CallbackUrl:
type: string
format: uri
pattern: https?://*
example: https://example.com/callback?method=GET
description: >
URL that Checkout will call when the session
payment is complete and the transaction has been authorized.
> **Callback is only delivered to HTTPS URLs**
> A callback done with a transaction with status `ON_HOLD` will receive
> an aditional callback (later) when the transaction state changes
status
> from `ON_HOLD`.
> The callback may be received after the transaction is `CAPTURED`
> in case when the transaction was created from a session where
> `auto_capture` was enabled.
Unlike the `return_url` the `callback_url` is system-to-system
which means delivery is guaranteed.
Once a session payment is complete the callback_url is invoked as a
`GET` request to notify your system that the payment has been approved.
- A callback_url with `method=POST` query parameter will be invoked as a
`POST` request with the transaction included in the request body.
- A callback_url with `report_error=true` will enable the callback_url
to be called if the payment failed with error `cancelled`, `authorization`
or `failed`.
- A callback_url with `delay_callback=` will delay the callback
before trying to deliver the callback. The **maximum** delay is 60 seconds.
- A callback_url with `report_event={EVENT}` will enable the
callback_url
to be called if a payment event has been applied to the transaction. Valid
values are `CAPTURE`, `REFUND` and `VOID`. The callback_url can contain
multiple `report_event` query parameters. An `event` query parameter will be
included in the request sent to the callback_url.
- A callback_url with `includes=session` will enable the callback_url
to include the session data in the body.
- A callback_url with `sid_parameter_name=sid` will change the query
param `session_id`
to `sid` to avoid false session fixation alarms in firewalls. Possible values: `sid`, `session_id`
A successful delivery to an HTTPS callback_url sometimes requires
more than one attempt. This can be the case, for example, if the server
hosting the callback_url is down for maintenance or is experiencing
heavy traffic.
Dintero attempts a retry only after a failed delivery attempt, following
situations is considered as failed delivery
- HTTP status code 100 to 101 and 500 to 599 (inclusive)
(HTTP status code 400 to 499 is considered as permanent failure)
- A request timeout (10 seconds)
- Any connection error such as connection timeout, bad certificate, etc
Failed delivery will be retried 20 times.
query name | type | description | required
------------------ | :-----------: | :--------------------------- |
:-----------
transaction_id | string | Transaction Id | true
session_id | string | Session Id | true
sid | string | Session Id when
sid_parameter_name=sid | true
merchant_reference | string | The merchants reference | true
time | string | ISO 8601 format | true
error | string | Error code |
false
event | string | event applied |
false
event_id | string | event id for callback |
false
includes | string array | include additional data |
false
> The transaction_id is optional when callback_url enables
`report_error`
> where error query will be included in case where the payment was
completed
> without creating an authorized transaction.
> It is not possible to use `https://localhost` or `http://127.0.0.1`
for
> the callback URL as Checkout backend would then call itself.
See [validating
callbacks](https://docs.dintero.com/docs/checkout/validating-callbacks)
to see how you can verify the integrity of the callbacks,
SessionUrls:
type: object
required:
- return_url
properties:
return_url:
type: string
format: uri
example: https://example.com/accept
description: >
URL to page where Checkout will redirect the
customer to after the Checkout process has ended.
If a transaction was completed successfully, a `transaction_id`
will be appended to the URL as a `query` string parameter
> A `transaction_id` will be appended to the URL if the
> Checkout failed with `error=capture`
> A transaction with status `ON_HOLD` must be handled as a payment
> that is pending approval, where the transaction will later be
updated
> with a final payment staus `AUTHORIZED` or `FAILED`.
> We recommend that `callback_url` is used to receive the callback
when
> the transaction changes status from `ON_HOLD` to `AUTHORIZED` or
`FAILED`.
> Alternative is to do an hourly/daily poll on the transaction to
check
> if the status has changed.
*Example*:
```
https://example.com/accept?transaction_id=T00000000.3YkJXSdSnUBXcmQSzn7uJj
```
query name | type | description | required
------------------ | :----------: | ------------------------------ |
:-----------:
transaction_id | string | Transaction Id |
false
error | string | Error code identifying cause |
false
merchant_reference | string | The merchants reference |
true
In case of that something went wrong with the payment flow, an
`error` query parameter will be appended to the URL. The value
of the error is a code identifying the cause.
error | Description
------------- | ------------
cancelled | Customer cancelled the checkout payment
authorization | Customer failed to authorize the payment
failed | The transaction has been rejected by us, or an error
has occurred during transaction processing
### configuration.channel=in_app
The `in_app` channel is intended for payments done from mobile
devices
where `url.return_url` can be set to the application's appswitch
URL.
#### initial_recipient=merchant
If the query-param `initial_recipient=merchant` is appended to the
appswitch URL, the payment app will switch directly to the app,
i.e. without doing a redirect.
**The option is not supported for:**
- payex.vipps
- payex.swish
- bambora.mobilepay
Following query parameters will be added to the `return_url`
query name | type | description | required
------------------------- | :----------: |
------------------------------ | :-----------:
transaction_id | string | Transaction
Id | false
session_id | string | Session
Id | false
error | string | Error code identifying
cause | false
payment_return_url | string | Redirect URL to Dintero
API | false
merchant_reference | string | The merchants
reference | true
If the `payment_return_url` is present, you can use it to get a url
containing the `session_id`
or `transaction_id`. `payment_return_url` will only be present when
`configuration.channel=in_app`
and `initial_recipient=merchant` is appended on the appswitch URL.
> The `payment_return_url` may initially return `202 Accepted` if
the
> payment confirmation is not ready yet.
> Once ready, a `302 Found` redirect is returned to the `return_url`
You will in this case be required to poll for status on the payment
by using the
`session_id` or `transaction_id` to poll from the endpoints:
- [GET
/v1/sessions/{session_id}](/api-reference/session/checkout_session_get)
- [GET
/v1/transactions/{transaction_id}](/api-reference/transactions/transactions_id_get)
Poll the transaction until it has been updated with one of these
statuses:
- AUTHORIZED
- CAPTURED
- FAILED
In case no `transaction_id` is included in the return url, poll the
session to get the `transaction_id`
Example url:
`myapp://?initial_recipient=merchant&transaction_id=T12345678.abc&merchant_reference=mref123&session_id=T12345678.abd`
callback_url:
$ref: '#/components/schemas/CallbackUrl'
merchant_terms_url:
type: string
format: uri
pattern: https?://*
example: https://example.com/terms.html
description: >
URL to a webpage with the merchant's Terms of Service. Will be
linked to from the checkout.
OrderEventBase:
type: object
properties:
event_type:
type: string
description: |
The type corresponding to this event
enum:
- api-event
- service-event
required:
- event_type