Items

Create and list order items.

• Create order items
• Return order items

Create order items

Create items for an existing order.

• This is a one-time operation, so the post must contain all order items.
• The sum of the (total) amounts of all order items must be equal to the order amount.
• The order items cannot be added after payments are started.

POST /ps/api/public/v1/merchants/{merchant_key}/orders/{order_key}/items

Identifiers

Name	Type	Description
merchant_key	MerchantKey	The key of the merchant.
order_key	OrderKey	The key of the order.

Parameters

Not applicable.

Request

Array of:

Field	Type	M	Description
number	Number(1, 2^30)	M	A unique line number for the this item.
code	String(1, 50)	M	A code or article number identifying this item.
name	String(1, 50)	M	The human-readable name of this item.
description	String(1, 100)	O	A description of the item.
type	Enum(50)	O	The type of order item: PHYSICAL, DIGITAL, DISCOUNT, GIFT_CARD, STORE_CREDIT, SHIPPING_FEE, SALES_TAX, SURCHARGE
quantity	Number(1, 2^30)	M	Quantity of this item that's being ordered.
currency	Currency	M	The order currency as ISO 4217 Alpha 3, e.g. "EUR".
unit_amount	Amount	M	The unit amount including VAT in minor units, e.g. in cents.
amount	Amount	M	The total amount including VAT in minor units, e.g. in cents.
vat_amount	Amount	M	The total VAT amount in minor units, e.g. in cents.
vat_rate	Number(0.0, 99.9)	M	The VAT rate in percent.

The number of items (lines) that can be stored per order is limited to 512.

Response

Not applicable.

HTTP Status

Status	Meaning
201 (Created	The order is successfully created.
400 (Bad Request)	The request was not valid. The order items can not be added after payments are started, or the order items were already created.
401 (Unauthorized)	Authorization header missing or invalid.
404 (Not Found)	The merchant key or the order key was not found.

Create Items example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders/F1499C097FFA533D46FB05D52680AB9A/items \
    -d '[
            {
                "number"        : 1,
                "code"          : "SDC4/4GB-2ADP",
                "name"          : "Kingston microSD kaart 32GB",
                "type"          : "PHYSICAL",
                "quantity"      : 1,
                "currency"      : "EUR",
                "unit_amount"   : 1210,
                "amount"        : 1210,
                "vat_amount"    : 210,
                "vat_rate"      : 21.0
            },
            {
                "number"        : 2,
                "code"          : "9781741791570",
                "name"          : "Lonely Planet Thailand",
                "description"   : "Tourism and travel information incl. maps, history, ...",
                "type"          : "PHYSICAL",
                "quantity"      : 2,
                "currency"      : "EUR",
                "unit_amount"   : 1060,
                "amount"        : 2120,
                "vat_amount"    : 120,
                "vat_rate"      : 6.0
            }
    ]'

< Http 201 Created

Returns order items

Returns the items of an order.

GET /ps/api/public[/v1/merchants/{merchant_key}/orders/{order_key}/items

Identifiers

Name	Type	Description
merchant_key	MerchantKey	The key of the merchant.
order_key	OrderKey	The key of the order.

Parameters

Not applicable.

Request

Not applicable.

Response

Array of:

Field	Type	M	Description
number	Number(1, 2^30)	M	A unique line number for the this item.
code	String(1, 50)	M	A code or article number identifying this item.
name	String(1, 50)	M	The human-readable name of this item.
description	String(1, 100)	O	A description of the item.
type	Enum(50)	O	The type of order item: PHYSICAL, DIGITAL, DISCOUNT, GIFT_CARD, STORE_CREDIT, SHIPPING_FEE, SALEX_TAX, SURCHARGE
quantity	Number(1, 2^30)	M	Quantity of this item that's being ordered.
currency	Currency	M	The order currency as ISO 4217 Alpha 3, e.g. "EUR".
unit_amount	Amount	M	The unit amount including VAT in minor units, e.g. in cents.
amount	Amount	M	The total amount including VAT in minor units, e.g. in cents.
vat_amount	Amount	M	The total VAT amount in minor units, e.g. in cents.
vat_rate	Number(0.0, 99.9)	M	The VAT rate in percent.

HTTP Status

Status	Meaning
200 (OK)	Success.
401 (Unauthorized)	Authorization header missing or invalid.
403 (Forbidden)	The merchant key is not allowed.

List Orders example

> curl \
    -X GET \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public//v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders/F1499C097FFA533D46FB05D52680AB9A/items

< Http 200 Ok
<    '[
            {
                "number"        : 1,
                "code"          : "SDC4/4GB-2ADP",
                "name"          : "Kingston microSD kaart 32GB",
                "type"          : "PHYSICAL",
                "quantity"      : 1,
                "currency"      : "EUR",
                "unit_amount"   : 1210,
                "amount"        : 1210,
                "vat_amount"    : 210,
                "vat_rate"      : 21.5
            },
            {
                "number"        : 2,
                "code"          : "9781741791570",
                "name"          : "Lonely Planet Thailand",
                "description"   : "Tourism and travel information incl. maps, history, ...",
                "type"          : "PHYSICAL",
                "quantity"      : 2,
                "currency"      : "EUR",
                "unit_amount"   : 1060,
                "amount"        : 2120,
                "vat_amount"    : 120,
                "vat_rate"      : 6.0
            }
    ]'