E‐Commerce (Order)

The order entry point allows you to control the orders, the items, payments and subscriptions.

List

The list method retrieves a list of all the orders.

use KeapGeek\Keap\Facades\Keap;

Keap::order()->list([
    'contact_id' => ?int,
    'limit' => ?int,
    'offset' => ?int,
    'order' => ?string, // ENUM see below
    'paid' => ?bool,
    'product_id' => ?int,
    'since' => ?string,
    'until' => ?string,
]);

This method accepts different optional parameters, to query on:

• contact_id is the id of the contact.
• limit is the amount of orders to return, it defaults to 1000.
• offset is the first item that starts the set, it defaults to 0.
• order is the attribute to order the items by, only two values are possible: order_date or update_date.
• paid boolean value of the paid status.
• product_id returns the orders containing this product.
• since is the date to start searching from.
• until is the date to end searching from.

It returns an array with all the orders that fullfill the criteria.

You can input any Carbon parsable string in the date fields, since they will automatically be converted into timestamps using Carbon::parse.

Count

The count method retrieves the count of all the orders, using the previously specified parameters.

use KeapGeek\Keap\Facades\Keap;

Keap::order()->list([
    'contact_id' => ?int,
    'paid' => ?bool,
    'product_id' => ?int,
    'since' => ?string,
    'until' => ?string,
]);

Find

It returns the order model, given the id.

use KeapGeek\Keap\Facades\Keap;

Keap::order()->find(int $order_id);

Delete

It deletes the order model given the id.

use KeapGeek\Keap\Facades\Keap;

Keap::order()->delete(int $order_id);

Create

Creates a one time order with order items.

use KeapGeek\Keap\Facades\Keap;

Keap::order()->create([
    'contact_id' => int, //required
    'lead_affiliate_id' => ?int,
    'order_date' => string,
    'order_items' => array, //required see below
    'order_title' => string, //required
    'order_type' => string, //required, ENUM see below
    'promo_codes' => ?array,
    'sales_affiliate_id' => ?int,
    'shipping_address' => object
]);

The contact_id is the id of the contact, that will be associated with the order.

The order_date is any Carbon parsable string representing the date and time of the order.

The order items is an array containing the order items, see the Create Order Item for the details

order_title is a required string, while order_type is a required string that can be only: Offline or Online.

The promo_codes is an array of strings.

The shipping_address is the Address Information Object, an array of strings that define the shipping address. See the Keap documentation here.

Model

The method model retrieves information about the custom fields and properties on the Keap order model.

use KeapGeek\Keap\Facades\Keap;

Keap::order()->model();

This method will return two arrays:

[
    "custom_fields" => [
        ...
    ],
    "optional_properties" => [string],
]

The response includes an array of custom fields, each representing a custom property set in your Keap dashboard. If these custom fields are configured, the response will return an array containing all custom order properties. Each element in this array is itself an array that includes all options and values configured, depending on the type of field selected.

Create Order Item

The createItem method creates a new order item to an existing order.

use KeapGeek\Keap\Facades\Keap;

Keap::order()->createItem(int $order_id, [
    'description' => ?string,
    'price' => ?string,
    'product_id' => int, //required
    'quantity' => int, //required
]);

The product_id and quantity are the only required parameters. While description is a string of the item, the price is an optional string, that will override the price of the product.

It retuns the order model

Delete Order Item

The deleteItem method deletes an item on a specified order.

use KeapGeek\Keap\Facades\Keap;

Keap::order()->deleteItem(int $order_id, int $item_id);

Replace Order Pay Plan

This method replaces the order's payment plan with the given values

use KeapGeek\Keap\Facades\Keap;

Keap::order()->replacePayPlan(int $order_id, [
    'auto_charge' => ?bool,
    'credit_card_id' => ?int,
    'days_between_payments' => int, //required
    'initial_payment_amount' => double,
    'initial_payment_date' => datetime,
    'number_of_payments' => int, //required
    'payment_gateway' => [
        'merchant_account_id' => ?int,
        'use_default' => ?bool
    ],
    'plan_start_date' => datetime, //required
]);

The required items are days_between_payments, number_of_payments and plan_start_date.

All the datetime fields will be automatically parsed via Carbon.

The payment_gateway is not required, if not explicitly provided it will be set to the default merchant account.

The auto_charge setting is set by default to true.

Retrieve Order Payments

This methods retrieves a list of payments made against a given order, including historical or external payments of cash or credit card.

use KeapGeek\Keap\Facades\Keap;

Keap::order()->findPayments(int $order_id);

It returns an array of Payment Objects:

[
    'amount' => double,
    'id' => int,
    'invoice_id' => int,
    'last_updated' => string,
    'note' => string,
    'pay_date' => string,
    'pay_status' => string,
    'payment_id' => int,
    'refund_invoice_payment_id' => int,
    'skip_commission' => bool
]

Create Payment

This method is used to create a payment that can charge a credit card. Or, adds a record of historical or external payment of cash or credit card.

use KeapGeek\Keap\Facades\Keap;

Keap::order()->createPayment(int $order_id, [
    'apply_to_commissions ' => ?bool,
    'charge_now' => ?bool,
    'credit_card_id' => ?int
    'date' => ?datetime
    'notes' => ?string,
    'payment_amount' => ?string,
    'payment_gateway_id' => ?string,
    'payment_method_type' => ?string, // Enum "CREDIT_CARD", "CASH", "CHECK", or "TOKEN"
]);

All the fields are optional.

The date field will be automatically parsed via Carbon. The payment_method_type is one of the following values: CREDIT_CARD, CASH, CHECK, or TOKEN.

The charge_now and apply_to_commissions are by default set to true.

Retrieve Order Transactions

This method finds an array of all transactions on a given order.

use KeapGeek\Keap\Facades\Keap;

Keap::order()->findOrderTransactions(int $order_id, [
    'contact_id' => ?int,
    'limit' => ?int,
    'offset' => ?int,
    'since' => ?datetime,
    'until' => ?datetime,
]);

This method accepts different optional parameters, to query on:

• contact_id is the id of the contact.
• limit is the amount of transactions to return, it defaults to 1000.
• offset is the first item that starts the set, it defaults to 0.
• since is the date to start searching from.
• until is the date to end searching from.

The datetime fields can be inputted by strings and are automatically parsed by Carbon.

List Subscriptions

The list subscriptions method retrieves an array of all subscriptions.

use KeapGeek\Keap\Facades\Keap;

Keap::order()->listSubscriptions([
    'contact_id' => ?int,
    'limit' => ?int,
    'offset' => ?int,
]);

This method accepts different optional parameters, to query on:

• contact_id is the id of the contact.
• limit is the amount of subscriptions to return, it defaults to 1000.
• offset is the first item that starts the set, it defaults to 0.

Create Subscription

The method createSubscription creates a subscription for a specified product.

use KeapGeek\Keap\Facades\Keap;

Keap::order()->createSubscription([
    'allow_duplicate' => ?bool,
    'allow_tax' => ?bool,
    'auto_charge' => ?bool,
    'billing_amount' => ?double,
    'contact_id' => int, //required
    'credit_card_id' => ?int
    'first_bill_date' => ?date,
    'payment_gateway_id' => ?int,
    'quantity' => ?int,
    'sale_affiliate_id' => ?int,
    'subscription_plan_id' => ?int,
]);

• allow_duplicate is a boolean. If true, it will disable the check to see if there is already an identical subscription for the contact. If not explicit the default is false.
• allow_tax is by default set to false, and only works if the product is taxable.
• auto_charge is by default set to true.
• billing_amount is a double, must be 0 or greater. The default value is the product price.
• credit_card_id is by default the most recently used credit card.
• first_bill_date is the first day of subscription. Must not be in the past, the default is today.
• payment_gateway_id if not provided is set to the default merchant.
• quantity must be greater than zero, default is 1.

The required field is contact_id.

The date field will be automatically parsed by Carbon.

Subscription Model

The method model retrieves information about the custom fields and properties on the Keap subscription model.

use KeapGeek\Keap\Facades\Keap;

Keap::order()->subscriptionModel();

This method will return two arrays:

[
    "custom_fields" => [
        ...
    ],
    "optional_properties" => [string],
]

Find Transaction

This method will return a single transaction by its id.

use KeapGeek\Keap\Facades\Keap;

Keap::order()->findTransaction(int $transaction_id);

It returns a transaction object with the following properties:

[
    'amount' => double,
    'collection_method' => string,
    'contact_id' => int,
    'currency' => string,
    'errors' => string,
    'gateway' => string,
    'gateway_account_name' => string,
    'id' => int,
    'order_ids' => string,
    'orders' => object,
    'paymentDate' => string,
    'status' => string,
    'test' => bool,
    'transaction_date' => string,
    'type' => string,
]

List Transactions

This method will return a list of all the transactions for a given contact.

use KeapGeek\Keap\Facades\Keap;

Keap::order()->listTransactions([
    'contact_id' => ?int,
    'limit' => ?int,
    'offset' => ?int,
    'since' => ?datetime,
    'until' => ?datetime,
]);

This method accepts different optional parameters, to query on:

• contact_id is the id of the contact.
• limit is the amount of transactions to return, it defaults to 1000.
• offset is the first item that starts the set, it defaults to 0.
• since is the date to start searching from.
• until is the date to end searching from.

All the datetime fields are automatically parsed by Carbon.

It returns an array of transaction objects.