view release on metacpan or  search on metacpan

lib/Net/Simplify/Subscription.pm  view on Meta::CPAN

package Net::Simplify::Subscription;

=head1 NAME

Net::Simplify::Subscription - A Simplify Commerce Subscription object

=head1 SYNOPSIS

  use Net::Simplify;


  $Net::Simplify::public_key = 'YOUR PUBLIC KEY';
  $Net::Simplify::private_key = 'YOUR PRIVATE KEY';

  # Create a new Subscription.
  my $subscription = Net::Simplify::Subscription->create{ {...});

  # Retrieve a Subscription given its ID.
  my $subscription = Net::Simplify::Subscription->find('a7e41');

  # Update existing Subscription.
  my $subscription = Net::Simplify::Subscription->find('a7e41');
  $subscription->{PROPERTY} = "NEW VALUE";
  $subscription->update();

  # Delete
  my $subscription = Net::Simplify::Subscription->find('a7e41');
  $subscription->delete();

  # Retrieve a list of objects
  my $subscriptions = Net::Simplify::Subscription->list({max => 10});
  foreach my $v ($subscriptions->list) {
      # ...
  }

=head1 DESCRIPTION

=head2 METHODS

=head3 create(%params, $auth)

Creates a C<Net::Simplify::Subscription> object.  The parameters are:

=over 4

=item C<%params>

Hash map containing initial values for the object.  Valid keys are:

=over 4

=item amount

Amount of the payment in the smallest unit of your currency. Example: 100 = $1.00 

=item billingCycle

How the plan is billed to the customer. Values must be AUTO (indefinitely until the customer cancels) or FIXED (a fixed number of billing cycles). [default: AUTO] 

=item billingCycleLimit

The number of fixed billing cycles for a plan. Only used if the billingCycle parameter is set to FIXED. Example: 4 

=item coupon

Coupon ID associated with the subscription 

=item currency

Currency code (ISO-4217). Must match the currency associated with your account. 

=item currentPeriodEnd

End date of subscription's current period 

=item currentPeriodStart

Start date of subscription's current period 

=item customer

Customer that is enrolling in the subscription. 

=item frequency

Frequency of payment for the plan. Used in conjunction with frequencyPeriod. Valid values are "DAILY", "WEEKLY", "MONTHLY" and "YEARLY". 

=item frequencyPeriod

Period of frequency of payment for the plan. Example: if the frequency is weekly, and periodFrequency is 2, then the subscription is billed bi-weekly. 

=item name

Name describing subscription [max length: 50] 

=item plan

The ID of the plan that should be used for the subscription. 

=item quantity

Quantity of the plan for the subscription. [min value: 1] 

=item renewalReminderLeadDays

If set, how many days before the next billing cycle that a renewal reminder is sent to the customer. If null, then no emails are sent. Minimum value is 7 if set. 

=item source

Source of where subscription was created 


=back

=item C<$auth>

Authentication object for accessing the API.  If no value is passed the global keys
C<$Net::Simplify::public_key> and C<$Net::Simplify::private_key> are used.

=back




=head3 delete()

Deletes the C<Net::Simplify::Subscription> object.  Authentication is done using the same credentials used when the AccessToken was created.



=head3 list(%criteria, $auth)

Retrieve a list of C<Net::Simplify::Subscription> objects.  The parameters are:

=over 4

=item C<%criteria>

Hash map representing the criteria to limit the results of the list operation.  Valid keys are:

=over 4

=item C<filter>

<table class="filter_list"><tr><td>filter.customer</td><td>Filter by the Id of the customer with the subscription</td></tr><tr><td>filter.plan</td><td>Filter by the Id of the plan linked to the subscription</td></tr><tr><td>filter.dateCreatedMin<sup>...



=item C<max>

Allows up to a max of 50 list items to return. [min value: 0, max value: 50, default: 20]



=item C<offset>

Used in paging of the list.  This is the start offset of the page. [min value: 0, default: 0]



=item C<sorting>

Allows for ascending or descending sorting of the list.
The value maps properties to the sort direction (either C<asc> for ascending or C<desc> for descending).  Sortable properties are:

=over 4

=item C<dateCreated>

=item C<id>

=item C<plan>


=back




=back

=back



=head3 find($id, $auth)

Retrieve a C<Net::Simplify::Subscription> object from the API.  Parameters are:

=over 4

=item C<$id>

Identifier of the object to retrieve.

=item C<$auth>

Authentication object for accessing the API.  If no value is passed the global keys
C<$Net::Simplify::public_key> and C<$Net::Simplify::private_key> are used.

=back




=head3 update()

Update C<Net::Simplify::Subscription> object.
The properties that can be updated are:

=over 4


=item C<amount>

Amount of the payment in the smallest unit of your currency. Example: 100 = $1.00 

=item C<billingCycle>

How the plan is billed to the customer. Values must be AUTO (indefinitely until the customer cancels) or FIXED (a fixed number of billing cycles). [default: AUTO] 

=item C<billingCycleLimit>

The number of fixed billing cycles for a plan. Only used if the billingCycle parameter is set to FIXED. Example: 4 

=item C<coupon>

Coupon being assigned to this subscription 

=item C<currency>

Currency code (ISO-4217). Must match the currency associated with your account. 

=item C<currentPeriodEnd>

End date of subscription's current period 

=item C<currentPeriodStart>

Start date of subscription's current period 

=item C<frequency>

Frequency of payment for the plan. Used in conjunction with frequencyPeriod. Valid values are "DAILY", "WEEKLY", "MONTHLY" and "YEARLY". 

=item C<frequencyPeriod>

Period of frequency of payment for the plan. Example: if the frequency is weekly, and periodFrequency is 2, then the subscription is billed bi-weekly. [min value: 1] 


=item C<name>

Name describing subscription 

=item C<plan>

Plan that should be used for the subscription. 

=item C<prorate>