Order objects contain information about a customer’s transaction. Usually, Order objects will be given to you by the AppThemes Product you are working with. However, you can also create new orders, and even process them if you so desire.

Basic Order Information

The Order object contains information about the order you are processing. There are several helper functions available that can give you what you need to know. These methods are available on all orders, regardless of type.

// General Information
$order->get_id();
$order->get_description();
$order->get_author();
$order->get_ip_address(); // Returns IP address used to create the order
$order->get_currency();
$order->get_gateway();
$order->get_parent(); // Used for recurring orders
 
$order->is_recurring(); // Returns true if the order is recurring
$order->is_escrow(); // Returns true if the order is an escrow order
 
// Payment Gateway helpers
$order->get_return_url(); // URL to redirect after order is completed
$order->get_cancel_url(); // URL to redirect to change gateways
 
// Items
$order->get_item( $index = 0 ); // Returns the nth-item on the order
$order->get_items( $item_type = '' ); // Returns an array of items
$order->get_total();
 
// Event
$order->get_status(); // Returns the current state of the order. See Order States
$order->get_display_status();

If you’re planning on working more extensively with orders, checkout out the complete Order API to be able to write items, data, and set properties of an order.

Order States

An order can be in one of several states. These states keep track of where the buyer/seller is in the transaction process. You can get information is what state an order is in by calling the get_status() method. The below method calls set the order to the defined state.

Instant Order States

For a simple purchase, the following states are available:

$order->pending(); // Waiting for payment
$order->complete(); // Payment is completed
$order->failed(); // Payment has failed.
$order->activate(); // Payment completed, Moderation is finished

A recurring order has the same states as an instant order.

Escrow Order States

For an escrow purchase, the following states are available:

$order->pending(); // Waiting for payment
$order->failed(); // Payment has failed.
$order->paid(); // Payment is completed and money is in escrow
$order->refunded(); // Payment has been refunded to buyer.
$order->completed(); // Payment has been transferred to seller.

The easiest way to start working with orders is responding to an event. Every order has an action hook that allows plugins to hook into when their state changes.

Acting on Order state changes

You can easily take action when an order state changes to do things like send emails, update posts/users, etc. Doing this is easy.

Each state change comes with a corresponding action that fires off. For instance, in the below example we use the WordPress Plugin API to respond to an activated() state change.

add_action( 'app_transaction_activated', 'my_emailer' );
function my_emailer( $order ){
 
   // ...  email administrator
 
}

Because instant, recurring, and escrow orders share some state change hooks, make sure that you check what type of order you are processing if it is necessary for your use case.

Order Data API

All orders have a built-in API that allows you to record arbitrary data to the order for later retrieval.

$order->add_data( $key, $value );
 
$order->add_data( 'timestamp', time() );
$timestamp = $order->get_data( 'timestamp' );

All data values are isolated from other meta data assigned to the order. You can get all data stored via the Order Data API by calling get_data() with no arguments.