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.
- Items cannot be added after a payment is 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
}
]'