1.6. M2_Order

1.6. M2_Order
Prev	1. Applications (Apps)	Next

This application can be used to keep track of orders - whether utilizing online payment or not. It will help you send out emails to the customer as the order moves through the various states in its life, create invoices automatically, and to some degree M2_Order integrates with M2_Payment.

M2_Order::create($data)

You use this method to create an order in the system. The order knows nothing about payment and you can choose to move on to M2_Order::getPaymentWizard(), or you can just leave it there if you don't accept online payments.

Orders will appear in the administration where you can perform further actions on them.

$data is an associative array, holding the keys in the table below:

Table 14. Array keys for the first parameter to M2_Order::create()

Key	Description	Required
`customerData`	An array of contact and shipping information holding the following keys: `name` `org_name` `address` `zip` `city` `country` `email` `mobile` (This must use a country code prefix - i.e. "+45" for Denmark)	Yes
`lines`	An array of order lines. Each line is an array itself, holding the following keys: `quantity` `text` `item_price` `item_no` `vat_percent` Please note that the `item_price` must be provided without VAT - the total will then automatically be calculated based on `item_price`, `quantity` and `vat_percent`. If you are dealing with lines without any VAT, just set the `vat_percent` to zero. All amounts should use decimal comma only. For example, use 1024.50 instead of 1.024,50	Yes
`currency`	The currency of the order, according to http://www.xe.com/iso4217.php.	Yes
`shipping_amount`	Shipping fee, specified in the currency for the order.	No
`shipping_vat_percent`	VAT percentage of shipping amount that must be added.	No
`state`	Initial state of the order: `INIT` `CREATED` `PAYMENT_PENDING` `PAID` `SHIPPED` If you use online payment via `M2_Order::getPaymentWizard()`, you should set the initial state to `INIT`. Moski2.net will then automatically update the state to `PAID` when the online payment is processed successfully. The `INIT` state is special in that it is not displayed in the administration. This means that if you create an order in `INIT` state and the customer never finishes the payment flow, the order remains invisible. Important Moski2.net will automatically purge any orders in `INIT` state that are more than 24 hours old - these are considered stale entries, so be careful when setting an order in `INIT` state. The rest of the states are shifted between manually in the administration. If no state is provided, the default is `CREATED`.	No
`files`	You may wish to attach one or more files to an order - say you have a shop where people can upload pictures that you will print on T-shirts and ship to them. This parameter is also an array of files where each file is an array itself, holding the following keys: `filename` - the original name of the file, or how you want to store it. `mimetype` - e.g. "image/jpeg" `binary` - full path to where the file is sitting `identifier` - an optional string to identify the file if you later want to do something with it when calling `M2_Order::getDetails()`.	No
`customData`	Arbitrary data you wish to store with the order - this must be an associative array in only one dimension.	No
`emailNotifications`	An array of emails, each made up of an array with the keys described in the table below.	No
`createInvoiceTrigger`	Determine when to create an invoice for the order. If this parameter is supplied, Moski2.net will attempt to create a PDF invoice when the order moves into the chosen state. Available states: `CREATED` `PAYMENT_PENDING` `PAID` `SHIPPED`	No
`extraInvoiceText`	An optional extra string that will be printed on the PDF invoice.	No

Each email supplied in emailNotification is made up of an array with the following keys:

Table 15. Associative array keys when describing emails sent by M2_Order

Key	Description	Required	Default
`trigger`	The event that will trigger sending this email. Possible values are: `CREATED` - will send the email right after calling `M2_Order::create()`. `PAYMENT_PENDING` - will send the email if the order is created with the state `PAYMENT_PENDING`. `PAID` - will send the email when the order is marked as paid or paid online. `PACKAGED` - will send the email when the order is marked as packaged. `SHIPPED` - will send the email when the order is marked as shipped. `CANCELLED` - will send the email if the order is marked as cancelled.	No	`CREATED`
`emailTo`	The email address to send a notification email to. Can also be an array of addresses.	Yes
`emailCc`	An optional email address to CC. Can also be an array of addresses.	No
`emailBcc`	An optional email address to BCC. Can also be an array of addresses.	No
`emailFrom`	The sender address.	No	`[email protected]`
`emailFromName`	The sender name.	No	`[email protected]`
`emailReplyTo`	Reply-to address.	No
`emailSubject`	The subject of the email. You can use the same placeholders as described in `emailBody` below.	No	'Order @ yourdomain.tld'
`emailBody`	The body of the confirmation email. You can use this placeholder in the text: `%%ORDER_NUMBER%%` will be replaced with the order number. In addition, any keys from your `customData` parameter encapsulated in double percentage signs will be replaced with their values. So, if you have a `customData` array looking like this: array( 'customerName' => 'Bill Hanson', 'shippingAddress' => 'Somewhere' ); You can then set `emailBody` to something like this: $options['emailBody'] = "Hi there, %%customerName%%. We will ship your order number %%ORDER_NUMBER%% to this address: %%shippingAddress%%."; Note If your `emailBody` starts with `<html>` the email will be treated as an HTML mail.	Yes
`attachments`	An array of optional attachments. The names of the attachments must be the values from the `identifier` fields when storing the files with the order.	No
`attachInvoice`	Set to 1 if the email should get a PDF invoice attached. This will only work if an invoice is created before the mail goes out. You determine when to create an invoice with the `createInvoiceTrigger` parameter.	No	`0`

Here is a complete example of creating an order

<?php



?>

M2_Order::getPaymentWizard($orderNumber, [$wizardArgs])

This method returns a payment wizard as known from M2_Payment, but all you need to provide is the order number.

$orderNumber is the order number as returned from M2_Order::create().

$wizardArgs lets you send along any extra arguments to the payment wizard. You can not overwrite the order number, but besides that, you supply any parameter that the payment wizard accepts.

M2_Order::getDetails($orderNumber, [$includeEmailNotifications = FALSE])

Allows you to retrieve the known details about the order.

$orderNumber is the order number as returned from M2_Order::create().

$includeEmailNotifications can be set to TRUE if you want to include the details about email notifications - you will simply get back what you put in when calling M2_Order::create().

M2_Order::getStatistics($start, $end)

M2_Order::setState($orderNumber, $state)

Sets the state of the order.

Important

If you have assigned any email to be triggered by the state you are changing to, these emails will be sent, regardless of whether they have been sent before.

Prev	Up	Next
1.5. M2_Group	Home	1.7. M2_Payment

1.6. M2_Order

Important

Note

Important