Índice
Los Pagos recurrentes vienen con una nueva clase EDD para gestionar suscripciones. La clase EDD_Subscription permite a un desarrollador trabajar con suscripciones mediante programación. Este documento enumerará las propiedades, métodos y funcionalidad sugerida de EDD_Subscription.
Propiedades
- $id = 0;
- $customer_id = 0;
- $period = '';
- $initial_amount = '';
- $recurring_amount = '';
- $bill_times = 0;
- $parent_payment_id = 0;
- $product_id = 0;
- $created = '0000-00-00 00:00:00';
- $expiration = '0000-00-00 00:00:00';
- $status = 'pending';
- $profile_id = '';
- $gateway = '';
- $customer;
Métodos
- create( $data = array() )
- update( $args = array() )
- delete()
- get_original_payment_id()
- get_child_payments()
- get_total_payments()
- get_lifetime_value()
- add_payment( $args = array() )
- renew()
- complete()
- expire()
- failing()
- cancel()
- can_cancel()
- get_cancel_url()
- can_update()
- get_update_url()
- is_active()
- is_expired()
- get_expiration()
- get_expiration_time()
- get_status()
- get_status_label()
- payment_exists( $txn_id = ” )
Uso
Instanciación básica
Se puede crear un objeto EDD_Subscription "vacío" con este código:
$subscription = new EDD_Subscription();
Esto devolverá un objeto con esta estructura:
EDD_Subscription Object
(
[subs_db:EDD_Subscription:private] => EDD_Subscriptions_DB Object
(
[table_name] => wp_edd_subscriptions
[version] => 1.0
[primary_key] => id
)
[id] => 0
[customer_id] => 0
[period] =>
[initial_amount] =>
[recurring_amount] =>
[bill_times] => 0
[parent_payment_id] => 0
[product_id] => 0
[created] => 0000-00-00 00:00:00
[expiration] => 0000-00-00 00:00:00
[status] => pending
[profile_id] =>
[gateway] =>
[customer] =>
)
Instanciación de una suscripción existente
El constructor de EDD_Subscription acepta 2 argumentos. El primero es un entero que representa un ID de suscripción o, si el segundo argumento es verdadero, el primero puede ser un profile_id de suscripción.
You can find a subscription ID in the URL while viewing a subscription. 
You can find the profile ID listed when viewing a subscription. 
Estas dos líneas de código devolverán la misma salida porque se refieren a la misma suscripción:
$subscription = new EDD_Subscription( 3 );
$subscription = new EDD_Subscription( 'sub_85YmWtzABSAWN7', true );
Las líneas de código anteriores devolverían cada una un objeto como este:
EDD_Subscription Object
(
[subs_db:EDD_Subscription:private] => EDD_Subscriptions_DB Object
(
[table_name] => wp_edd_subscriptions
[version] => 1.0
[primary_key] => id
)
[id] => 1
[customer_id] => 3
[period] => month
[initial_amount] => 50.00
[recurring_amount] => 50.00
[bill_times] => 0
[parent_payment_id] => 87
[product_id] => 85
[created] => 2016-03-15 15:36:30
[expiration] => 2016-04-15 23:59:59
[status] => pending
[profile_id] => paypal-363e3cc178dab152bb59b958024bce75
[gateway] => paypal
[customer] => EDD_Customer Object
(
[id] => 3
[purchase_count] => 3
[purchase_value] => 110.000000
[email] => [email protected]
[name] => Bob Smith
[date_created] => 2016-03-08 15:01:02
[payment_ids] => 54,63,87,88,91
[user_id] => 2
[notes] => Array
(
[0] => March 16, 2016 14:37:22 - Subscription #3 cancelled admin
)
[db:protected] => EDD_DB_Customers Object
(
[table_name] => wp_edd_customers
[version] => 1.0
[primary_key] => id
)
)
)
Modificación de objeto
Usando los métodos incluidos, se puede hacer casi cualquier cosa con una suscripción.
A menos que se indique lo contrario, cada ejemplo de método proporcionado utilizará este modelo de instanciación:
$subscription = new EDD_Subscription();
Métodos operativos
EDD_Subscription incluye métodos para crear, eliminar, actualizar y renovar suscripciones, así como para añadir pagos.
$subscription->create()
Para crear una suscripción correctamente, debe proporcionar información. Estos elementos son obligatorios:
$data = array(
'customer_id' => 0, // an integer, should be a valid customer_id
'period' => '', // accepts 'day', 'week', 'month', or 'year'; how often the subscription renews
'initial_amount' => '', // accepts a float
'recurring_amount' => '', // accepts a float
'bill_times' => 0, // accepts an integer; the number of times billing should happen, 0 means indefinite
'parent_payment_id' => 0, // accepts an integer; the payment id returned by the initial payment
'product_id' => 0, // accepts an integer; the id of the product
'created' => '', // accepts a date string; formatted like 0000-00-00 00:00:00
'expiration' => '', // accepts a date string; formatted like 0000-00-00 00:00:00
'status' => '', // accepts 'Pending', 'Active', 'Cancelled', 'Expired', 'Failing', 'Completed'
'profile_id' => '', // accepts a string returned by the payment gateway as their subscription ID
);
A continuación, puede llamar al método create() con esa información.
$subscription->create( $data );
El método create() devuelve un objeto con los mismos datos que obtendría al consultar un ID de suscripción específico.
$subscription->update()
La actualización de una suscripción utiliza el método update() con cualquier subconjunto de las opciones de matriz utilizadas para el método create(). El método update() también requiere un ID de suscripción. Algo como esto funcionaría:
$data = array(
'expiration' => '2019-07-17 23:59:59',
);
$subscription->update( $data );
$subscription->delete()
El método delete() acepta un ID de suscripción y elimina permanentemente la suscripción de la tienda EDD. Tenga en cuenta que esto no afecta a las suscripciones registradas en las pasarelas de pago. Esas deben gestionarse individualmente.
$subscription->renew()
Este método renueva una suscripción, extendiéndola un período más allá de la fecha de caducidad actual.
$subscription->add_payment( $args = array() )
Este método le permite realizar un pago. Acepta una matriz y requiere estos tres elementos de matriz:
- amount: la cantidad de dinero que se paga
- transaction_id: el ID de transacción de la suscripción de la pasarela de pago. Ejemplo: ‘ch_17q04L4NqFpaKRwY8ucZjW3t’
- gateway: la pasarela de pago utilizada para la suscripción. Ejemplo: ‘stripe’
Tras el éxito, add_payment() devuelve true.
Obtener información de la suscripción
EDD_Subscription proporciona una serie de métodos para obtener información sobre una suscripción.
$subscription->get_original_payment_id()
Este método devuelve un entero que es el ID del pago original. En la interfaz de usuario, este pago se puede encontrar en Descargas → Historial de pagos.
$subscription->get_child_payments()
El método devuelve una matriz de objetos EDD_Payment donde cada objeto es un pago secundario. Los objetos se parecerán a esto:
Array
(
[0] => EDD_Payment Object
(
[ID] => 1111111
[_ID:protected] => 1111111
[new:protected] =>
[number:protected] => 1111111
[mode:protected] => live
[key:protected] => 8d6f842jkf66cb6312117b9ad417dc6be
[total:protected] => 57.4
[subtotal:protected] => 57.4
[tax:protected] => 0
[discounted_amount:protected] => 0
[tax_rate:protected] =>
[fees:protected] => Array
(
)
[fees_total:protected] => 0
[discounts:protected] => samplediscount
[date:protected] => 2018-05-17 06:40:29
[completed_date:protected] =>
[status:protected] => edd_subscription
[post_status:protected] => edd_subscription
[old_status:protected] =>
[status_nicename:protected] => Renewal
[customer_id:protected] => 111111
[user_id:protected] => 1nan1
[first_name:protected] => Bob Smith
[last_name:protected] => Smith
[email:protected] => [email protected]
[user_info:EDD_Payment:private] => Array
(
[first_name] => Bob Smith
[last_name] => Smith
[discount] => samplediscount
[id] => 1nan1
[email] => [email protected]
[address] => Array
(
[line1] =>
[line2] =>
[city] =>
[country] =>
[state] =>
[zip] =>
[vat] =>
[notes] =>
)
)
[payment_meta:EDD_Payment:private] => Array
(
[key] => 8d6f842jkf66cb6312117b9ad417dc6be
[email] => [email protected]
[date] => 2018-05-17 06:40:29
[user_info] => Array
(
[first_name] => Bob Smith
[discount] => samplediscount
[id] => 1nan1
[email] => [email protected]
[address] => Array
(
[line1] =>
[line2] =>
[city] =>
[country] =>
[state] =>
[zip] =>
[vat] =>
[notes] =>
)
)
[downloads] => Array
(
[0] => Array
(
[id] => 1234
[quantity] => 1
[options] => Array
(
[quantity] => 1
[price_id] => 0
)
)
)
[cart_details] => Array
(
[0] => Array
(
[name] => Sample Product
[id] => 1234
[item_number] => Array
(
[id] => 1234
[quantity] => 1
[options] => Array
(
[quantity] => 1
[price_id] => 0
)
)
[item_price] => 57.4
[quantity] => 1
[discount] => 0
[subtotal] => 57.4
[tax] => 0
[fees] => Array
(
)
[price] => 57.4
)
)
[fees] => Array
(
)
[currency] => USD
)
[address:protected] => Array
(
[line1] =>
[line2] =>
[city] =>
[country] =>
[state] =>
[zip] =>
[vat] =>
[notes] =>
)
[transaction_id:protected] => 7M999999999999999
[downloads:protected] => Array
(
[0] => Array
(
[id] => 1234
[quantity] => 1
[options] => Array
(
[quantity] => 1
[price_id] => 0
)
)
)
[ip:protected] => 192.168.1.1
[gateway:protected] => paypalexpress
[currency:protected] => USD
[cart_details:protected] => Array
(
[0] => Array
(
[name] => Sample Product
[id] => 1234
[item_number] => Array
(
[id] => 1234
[quantity] => 1
[options] => Array
(
[quantity] => 1
[price_id] => 0
)
)
[item_price] => 57.4
[quantity] => 1
[discount] => 0
[subtotal] => 57.4
[tax] => 0
[fees] => Array
(
)
[price] => 57.4
)
)
[has_unlimited_downloads:protected] =>
[pending:EDD_Payment:private] => Array
(
)
[parent_payment:protected] => 830936
)
)
$subscription->get_total_payments()
Este método devuelve un entero que es el recuento del número total de pagos realizados, incluidos los pagos iniciales más todos los pagos secundarios.
$subscription->get_lifetime_value()
Este método devuelve un flotante que es el total monetario de todos los pagos realizados.
$subscription->get_cancel_url()
Este método devolverá una URL para cancelar una suscripción que se procesa a través de la pasarela por la que se compró la suscripción.
$subscription->get_update_url()
Este método devolverá una URL para actualizar una suscripción que se procesa a través de la pasarela por la que se compró la suscripción.
$subscription->get_expiration()
Devuelve la fecha y hora en que caducará la suscripción en este formato:
2016-04-15 23:59:59
$subscription->get_expiration_time()
Este método devuelve un entero que es una marca de tiempo Unix de la expiración.
$subscription->get_status()
Este método devuelve el estado actual de una suscripción en un formato útil para el código. Las opciones son ‘pending’, ‘active’, ‘cancelled’, ‘expired’, ‘failing’, ‘completed’.
$subscription->get_status_label()
Este método devuelve el estado actual de una suscripción en un formato útil para la presentación. Las opciones son ‘Pendiente’, ‘Activa’, ‘Cancelada’, ‘Expirada’, ‘Fallida’, ‘Completada’.
Condicionales de suscripción
EDD_Subscription ofrece una serie de métodos condicionales.
$subscription->can_cancel()
Este método devuelve un booleano y es filtrado por las pasarelas de pago para devolver true en suscripciones que se pueden cancelar con un ID de perfil a través del procesador comercial.
$subscription->can_update()
Este método devuelve un booleano y es filtrado por las pasarelas de pago para devolver true si la suscripción puede actualizar su método de pago. Es solo para determinar si se puede actualizar un método de pago.
$subscription->is_active()
and the status is
either ‘active’ or ‘cancelled’.
$subscription->is_expired()
$subscription->payment_exists( $txn_id = ” )
Este método acepta un ID de transacción que ha sido creado por una pasarela de pago. Aquí tienes un ejemplo de un ID de transacción de suscripción de Stripe:
ch_17q04L4NqFpaKRwY8ucZjW3t
Este método devuelve un booleano, true si encuentra una transacción con el ID proporcionado.
Métodos de estado
$subscription->complete()
Este método cambia el estado de una suscripción a ‘complete’.
$subscription->expire()
Este método cambia el estado de una suscripción a ‘expired’.
$subscription->failing()
Este método cambia el estado de una suscripción a ‘failing’.
$subscription->cancel()
Este método cambia el estado de una suscripción a ‘cancelled’.
