API-Documentation - Orders

Orders

This module delivers all savour information

Function overview

add Create new order.
checkout/cancel Cancel specific order.
checkout/finish Finish order.
get Access single order data.
getAll Get all orders.
touch Mark order as read.
add - Create new order.post

Create new order.

Url

/service/orders/add

Parameter

Field Type Description
data Array

Order data.

[data.billing_type] String

Type of billing. One of "client", "address".

( Optional. Default value: client )

data.billing_id int

Billing id. The matching id to data.billing_type.

[data.delivery_type] String

Type of delivery. One of "none", "address", "client".

( Optional. Default value: client )

[data.delivery_id] int

Delivery id. The matching id to data.delivery_type.

( Optional. Default value: data.billing_id )

[data.payment_type] String

Type of payment. One of "paypal", "prepaid", "invoice", "cash", "debit". Default depends on customer and billing client settings (if any).

( Optional. Default value: cash )

[data.source] String

Source where the order originates from.

( Optional. Default value: unknown )

data.items Array

Items of order (see example). This field has no effect, if basket_uuid is set.

[data.basket_uuid] String

Uuid of existing basket where order items will be loaded from. If set, this field takes precedence over ìtems.

( Optional. )

[data.return_url] String

Redirect url after paypal payment is accepted. Required if payment_method is "paypal".

( Optional. )

[data.cancel_url] String

Redirect url in case paypal payment is cancelled. Required if payment_method is "paypal".

( Optional. )

[data.net] Decimal

Order net price. If set, order validation will fail if calculated net price will not match.

( Optional. )

[data.tax] Decimal

Order tax. If set, order validation will fail if calculated tax will not match.

( Optional. )

[data.gross] Decimal

Order gross price. If set, order validation will fail if calculated gross price will not match.

( Optional. )

[data.rebate] int

Order percental rebate.

( Optional. )

[data.rebate_net] Decimal

Order net rebate. If set, order validation will fail if calculated gross price will not match.

( Optional. )

[data.rebate_gross] Decimal

Order gross rebate. If set, order validation will fail if calculated gross price will not match.

( Optional. )

[data.invoice_remark] String

Individual invoice remark.

( Optional. )

[data.delivery_note_remark] String

Individual delivery note remark.

( Optional. )

[data.client_remark] String

Individual client remark.

( Optional. )

Request-Example using existing client and address for billing and delivery and inline defining order items.

{
	"data": {
		"source": "shop",
		"billing_type": "client",
		"billing_id": 15,
		"delivery_type": "address",
		"delivery_id": 8,
		"payment_type": "paypal",
		"items": [
			{
				"item_type": "wine",
				"item_id": 185,
				"quantity": 6
			},
			{
				"item_type": "product",
				"item_id": 186,
				"quantity": 12
			},
			{
				"item_type": "rebate",
				"name": "Pauschaler Rabatt",
				"net": "-4.95",
				"tax": "-0.94",
				"gross": "-5.89",
				"quantity": 1
			}
		],
		"return_url": "https://shop.vinou.de/checkout/finish",
		"cancel_url": "https://shop.vinou.de/checkout/cancel",
		"net": "21.17",
		"tax": "4.02",
		"gross": "25.19"
	}
}

Request-Example providing different information for billing and delivery inline and using order items from existing basket.

{
	"data": {
		"source": "shop",
		"billing": {
			"countrycode": "de",
			"gender": "m",
			"first_name": "Max",
			"last_name": "Mustermann",
			"phone": "0123-456789",
			"mail": "max@musterhost.de",
			"company": "",
			"address": "Musterstraße 1",
			"zip": "12345",
			"city": "Musterhausen"
		},
		"delivery": {
			"countrycode": "de",
			"gender": "m",
			"phone": "0123-456789",
			"mail": "max@musterhost.de",
			"company": "Musterfirma",
			"address": "Sonstige Straße 112",
			"zip": "54321",
			"city": "Sonststadt"
		},
		"invoice_type": "net",
		"payment_type": "paypal",
		"payment_period": 14,
		"basket_uuid": "4ac1e7b2-fb8f-5ae3-9cf6-3292cf140ac5",
		"return_url": "https://shop.vinou.de/checkout/finish",
		"cancel_url": "https://shop.vinou.de/checkout/cancel",
	}
}
checkout/cancel - Cancel specific order.post

Cancel specific order.

Url

/service/orders/checkout/cancel

Parameter

Field Type Description
[id] Integer

Unique order ID.

( Optional. )

[uuid] String

Order UUID.

( Optional. )

Request-Example

{
	"uuid": "fca93b1b-0d49-5c54-b37a-51b6c71843bf"
}
checkout/finish - Finish order.post

Finishing an existing order and its payment is realized with an external payment method like paypal.

Url

/service/orders/checkout/finish

Parameter

Field Type Description
payment_type String

Method for payment for example "paypal".

payment_id String

Uuid of payment is part of the returnUrl.

order_id String

Uuid of the order must be stored in session before.

external_id String

External payment id mostly given in return url.

payer_id String

Id of payer mostly given in return url.

Request-Example

{
	"payment_type": "paypal",
	"payment_id": "d99c6fbf-9de6-54a0-b93e-ddb48d7e890e",
	"order_id": "fca93b1b-0d49-5c54-b37a-51b6c71843bf",
	"external_id": "PAY-7FS80726G4658932TLGZ7JKQ",
	"payer_id": "SPE87Y8U7CGH4"
}
get - Access single order data.post

Access data of single order by id or uuid.

Url

/service/orders/get

Parameter

Field Type Description
[id] Integer

Unique order ID.

( Optional. )

[uuid] String

Order UUID.

( Optional. )

[include] String|String[]

Define which model relations should be included inline in the response. The following values may be given as array or comma separated list. Allowed values are: "client": Include full record of ordering client. "billing": Include either billing client or billing address record denpending on order billing_type value. "delivery": Include either delivery client or delivery address record denpending on order delivery_type value. "items": Include order items. "documents": Include document records for invoices, delivery notes, payments and credit advices. "user": Include record of the order creating user.

( Optional. Default value: client,billing,delivery,documents,items )

Request-Example

{
	"id": 1234,
	"include": ["client", "user", "items"]
}
HTTP/1.1 200 OK

{
	"info": "success",
	"data": {
		"taxrates": {
			"19": {
				"net": "77.01",
				"tax": "14.63",
				"gross": "91.64"
			},
			"7": {
				"net": "2.00",
				"tax": "0.14",
				"gross": "2.14"
			}
		},
		"id": 6931,
		"uuid": "7eb91504-a363-54d3-9fd0-04202a0e36b6",
		"number": "BE0000000142",
		"billing_type": "client",
		"billing_id": 1370,
		"delivery_type": "client",
		"delivery_id": 1370,
		"delivery_note_remark": null,
		"payment_type": "invoice",
		"status": "need_package",
		"net": "79.01",
		"tax": "14.77",
		"gross": "93.78",
		"payment_period": 30,
		"invoice_type": "gross",
		"tax_free": 0,
		"item_net": "79.01",
		"item_tax": "14.77",
		"item_gross": "93.78",
		"rebate": 0,
		"rebate_net": "0.00",
		"rebate_tax": "0.00",
		"rebate_gross": "0.00",
		"cashback": 0,
		"gross_cashback": "93.78",
		"cashback_period": 0,
		"source": "manual",
		"crstamp": "2020-05-04 12:57:45",
		"cruser_id": 303,
		"chstamp": "2020-05-04 12:57:52",
		"customers_id": 289,
		"client_id": 1370,
		"client_remark": null,
		"invoice_remark": null,
		"touched": 1,
		"fixed": true,
		"note": null,
		"client": {
			"id": 1370,
			"company": null,
			"taxid": null,
			"address": "Musterstr. 6",
			"address_supplement": null,
			"zip": "12345",
			"city": "Feld",
			"countrycode": "de",
			"mail": null,
			"www": null,
			"department": null,
			"phone": "0123456789",
			"mobile": null,
			"fax": null,
			"type": "private",
			"active": 1,
			"newsletter": 0,
			"image": null,
			"bank": null,
			"iban": null,
			"bic": null,
			"invoice_type": "net",
			"invoice_remark": null,
			"unique_mandate_reference": null,
			"tax_free": 0,
			"payment_type": null,
			"payment_period": null,
			"cashback_period": null,
			"cashback": null,
			"rebate": null,
			"username": "K0000000001",
			"customers_id": 289,
			"number": "K0000000001",
			"price_range_id": null,
			"delivery_address_id": null,
			"delivery_note_remark": null,
			"title": null,
			"gender": "m",
			"salutation": null,
			"first_name": "Hans",
			"last_name": "Hamster",
			"deleted": 0
		},
		"positions": [
			{
				"id": 26941,
				"sorting": 0,
				"item_type": "wine",
				"name": "Weißburgunder Frühlingserwachen",
				"item_id": 3483,
				"quantity": 1,
				"net": "5.88",
				"tax": "1.12",
				"taxrate": 19,
				"gross": "7.00",
				"order_id": 6931,
				"invoice_id": 2949,
				"delivery_note_id": 2595,
				"crstamp": "2020-05-04 12:57:45",
				"cruser_id": 303,
				"chstamp": "2020-05-04 12:57:52",
				"customers_id": 289,
				"client_id": 1370,
				"credit_advice_id": null,
				"item": {
					"id": 3483,
					"name": "Weißburgunder Frühlingserwachen",
					"articlenumber": "002",
					"taste_id": 4,
					"vintage": 2019,
					"alcohol": "13.0",
					"sweetness": "15.0",
					"acid": "3.0",
					"bottlesize": "0.750",
					"drinktemperature": "9-11",
					"winetypes": null,
					"gross": "7.00",
					"net": "5.88",
					"tax": "1.12",
					"taxrate": 19,
					"place": "",
					"description": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.\n\nDonec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu.\n\nIn enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium. Integer tincidunt. Cras dapibus. Vivamus elementum semper nisi. Aenean vulputate eleifend tellus. Aenean leo ligula, porttitor eu, consequat vitae, eleifend ac, enim. Aliquam lorem ante, dapibus in, viverra quis, feugiat a,",
					"image": "/images/289/Wines/3483/1581503204-bordeauxweiss.png",
					"pdf": "weissburgunder-fruehlingserwachen.pdf",
					"active": 1,
					"type": "white",
					"region": 1009,
					"countrycode": "de",
					"cuvee": 0,
					"nostock": 0,
					"nostocktext": null,
					"quantity": 0,
					"quality": "origin",
					"quality_note": null,
					"bottling_type": null,
					"path_segment": "002-weissburgunder-fruehlingserwachen-k5m3",
					"customers_id": 289,
					"origin_id": null,
					"language": "de",
					"cruser_id": 223,
					"crstamp": "2020-01-23 09:36:50",
					"chstamp": "2020-04-09 13:16:44",
					"winery_id": 463,
					"weight": 100,
					"gtin": null,
					"terroir": null,
					"maturation": null,
					"cap": "screw",
					"bio": 0,
					"vegan": 1,
					"sorting": 0,
					"topseller": 0,
					"network": 0,
					"internal": 1,
					"public": 1,
					"shop": 1,
					"winesearch": 0,
					"expertisePdf": "/PDF/3483/weissburgunder-fruehlingserwachen.pdf",
					"prices": []
				}
			},
			{
				"id": 26944,
				"sorting": 0,
				"item_type": "product",
				"name": "Haribo",
				"item_id": 57,
				"quantity": 1,
				"net": "2.00",
				"tax": "0.14",
				"taxrate": 7,
				"gross": "2.14",
				"order_id": 6931,
				"invoice_id": 2949,
				"delivery_note_id": 2595,
				"crstamp": "2020-05-04 12:57:45",
				"cruser_id": 303,
				"chstamp": "2020-05-04 12:57:52",
				"customers_id": 289,
				"client_id": 1370,
				"credit_advice_id": null,
				"item": {
					"id": 57,
					"name": "Haribo",
					"articlenumber": "H12345",
					"net": "2.00",
					"tax": "0.14",
					"taxrate": 7,
					"gross": "2.14",
					"description": "",
					"image": "/images/289/Products/57/1563866279-top1_goldbaeren.png",
					"pdf": "",
					"active": 1,
					"nostock": 0,
					"nostocktext": "",
					"quantity": 4,
					"customers_id": 289,
					"origin_id": null,
					"language": "de",
					"cruser_id": null,
					"crstamp": "2019-07-23 07:17:26",
					"chstamp": "2020-05-12 15:42:58",
					"network": 1,
					"internal": 1,
					"public": 1,
					"shop": 1,
					"prices": []
				}
			}
		],
		"package": {
			"id": 26945,
			"sorting": 0,
			"item_type": "package",
			"name": "Packaging",
			"item_id": 50,
			"quantity": 1,
			"net": "4.62",
			"tax": "0.88",
			"taxrate": 19,
			"gross": "5.50",
			"order_id": 6931,
			"invoice_id": 2949,
			"delivery_note_id": 2595,
			"crstamp": "2020-05-04 12:57:45",
			"cruser_id": 303,
			"chstamp": "2020-05-04 12:57:52",
			"customers_id": 289,
			"client_id": 1370,
			"credit_advice_id": null,
			"item": {
				"id": 50,
				"type": "bottles",
				"min_bottles": 13,
				"max_bottles": 24,
				"min_weight": null,
				"max_weight": null,
				"gross": "5.50",
				"net": "4.62",
				"tax": "0.88",
				"taxrate": 19,
				"customers_id": 289
			}
		},
		"rebates": [],
		"payed": false,
		"cruser_name": "Muster user",
		"documents": {
			"invoices": [
				{
					"taxrates": {
						"19": {
							"net": "77.01",
							"tax": "14.63",
							"gross": "91.64"
						},
						"7": {
							"net": "2.00",
							"tax": "0.14",
							"gross": "2.14"
						}
					},
					"id": 2949,
					"uuid": "ad16001e-69aa-599e-9e66-4716f685a09c",
					"order_id": 6931,
					"number": "AR0000000132",
					"billing_type": "client",
					"billing_id": 1370,
					"delivery_type": "client",
					"delivery_id": 1370,
					"delivery_note_id": 2595,
					"status": "need_package",
					"remark": null,
					"net": "79.01",
					"tax": "14.77",
					"gross": "93.78",
					"payment_type": "invoice",
					"payment_period": 30,
					"invoice_type": "gross",
					"tax_free": 0,
					"item_net": "79.01",
					"item_tax": "14.77",
					"item_gross": "93.78",
					"rebate": 0,
					"rebate_net": "0.00",
					"rebate_tax": "0.00",
					"rebate_gross": "0.00",
					"cashback": 0,
					"gross_cashback": "93.78",
					"cashback_period": 0,
					"crstamp": "2020-05-04 12:57:45",
					"cruser_id": 303,
					"chstamp": "2020-05-04 12:57:52",
					"customers_id": 289,
					"client_id": 1370
				}
			],
			"deliveryNotes": [
				{
					"id": 2595,
					"uuid": "3b7db5e6-6802-50c1-b67a-55be38d3e42e",
					"order_id": 6931,
					"invoice_id": 2949,
					"number": "LS0000000126",
					"delivery_type": "client",
					"delivery_id": 1370,
					"status": "need_package",
					"remark": null,
					"crstamp": "2020-05-04 12:57:52",
					"cruser_id": 303,
					"chstamp": "2020-05-04 12:57:52",
					"customers_id": 289,
					"client_id": 1370
				}
			],
			"payments": [],
			"creditAdvices": []
		}
	}
}
getAll - Get all orders.post

Get all orders in descending chronological order.

Url

/service/orders/getAll

Parameter

Field Type Description
[include] String|Array

Define which model relations should be included inline in the response. Allowed values are "client", "billing", "delivery", "items", "documents", "user" as array or comma separated string.

( Optional. Default value: billing,delivery )

[page] int

Page number to fetch.

( Optional. Default value: 1 )

[pageSize] int

Number of records per result page. Maximum page size is 100.

( Optional. Default value: 16 )

Request-Example

{
	"include": ["client", "user"],
	"page": 2,
	"pageSize": 100
}
touch - Mark order as read.post

Mark order as read.

Url

/service/orders/touch

Parameter

Field Type Description
[id] Integer

Unique order ID.

( Optional. )

[uuid] String

Order UUID.

( Optional. )

© 2021 Vinou GmbH, Mombacher Straße 68, 55122 Mainz, Germany