{

Items

Create and list 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) M 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) M 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
            }
    ]'