Retrieving buyers billing end period - ruby-on-rails

Question

I browse around PayPal's API and I was not able to find the information I am looking for. I would like to save the billing period end value for the new subscription to the database. I have two plans to choose from, monthly and annually. Each subscription plan is set to auto renewal.
If someone could help assist me in saving the end date of the billing period to the Subscriptions table that would be helpful!
I need help finding the PayPal attribute I can call on to save to the database since I can't locate it in the API.

Answer 1

Legal note: This answer is based on my understanding, you should verify anything you have a question on with PayPal. Your reading and use of any information contained herein constitutes your agreement that any liability on my part for your use of this information is limited to $1 including all types of claims, special, etc.
If you do, or will continue to, receive end date information is unclear. The existence of a final_payment_date property is not defined in the PayPal API specification. However, in one, and only one of multiple examples, an additional agreement_details object is shown. This object is not mentioned anywhere else in the API specification other than within the "Response Sample" provided as an example of the response to a request to "Retrieve an agreement". Nor are any of the properties anywhere else in the API specification, other than in that one example.
The example shows this object as:
"agreement_details": {
"outstanding_balance": {
"currency": "USD",
"value": "0.00"
},
"cycles_remaining": "12",
"cycles_completed": "0",
"final_payment_date": "2016-12-19T10:00:00Z",
"failed_payment_count": "0"
}
As can be noted this structure contains very useful information, some of which is unavailable elsewhere. It is possible, even probable that this structure was merely left out of the specification by accident. However, there is no way to know that for sure. You will need to make a choice as to how you want to handle the situation.
If I were writing code to interact with the API: If the code was just for my own use, I would go ahead an use/rely on the structure and make some effort to contact PayPal for clarification. If I were writing code to be used for any other situation other than myself, I would make a very concerted effort to get clarification from PayPal. If I received no clarification from PayPal, I would probably have the code calculate the end date and compare it against the date which might be in this field. At a minimum, I would log a warning/bring it to the user's attention if there was a discrepancy.
It should be noted that this information is not contained in the examples of the responses you get when going through the process of "Create an agreement", "Execute an agreement", "Update an agreement", "Suspend an agreement", "Reactivate an agreement", "Cancel an agreement", "Set outstanding agreement amounts", or "Bill outstanding agreement amounts".
The full example of the response to a "Retrieve an agreement" request is:
{
"id": "I-0LN988D3JACS",
"state": "Pending",
"description": "New Description",
"plan": {
"payment_definitions": [
{
"type": "REGULAR",
"frequency": "Month",
"amount": {
"currency": "USD",
"value": "100.00"
},
"charge_models": [
{
"type": "TAX",
"amount": {
"currency": "USD",
"value": "12.00"
}
},
{
"type": "SHIPPING",
"amount": {
"currency": "USD",
"value": "10.00"
}
}
],
"cycles": "12",
"frequency_interval": "2"
}
],
"merchant_preferences": {
"setup_fee": {
"currency": "USD",
"value": "0.00"
},
"max_fail_attempts": "0",
"auto_bill_amount": "YES"
}
},
"links": [
{
"href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-0LN988D3JACS/suspend",
"rel": "suspend",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-0LN988D3JACS/re-activate",
"rel": "re_activate",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-0LN988D3JACS/cancel",
"rel": "cancel",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-0LN988D3JACS/bill-balance",
"rel": "self",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-0LN988D3JACS/set-balance",
"rel": "self",
"method": "POST"
}
],
"start_date": "2015-02-19T08:00:00Z",
"agreement_details": {
"outstanding_balance": {
"currency": "USD",
"value": "0.00"
},
"cycles_remaining": "12",
"cycles_completed": "0",
"final_payment_date": "2016-12-19T10:00:00Z",
"failed_payment_count": "0"
}
}
The PayPal API specifies that "After creating a profile, PayPal automatically queues payments based on the billing start date, billing frequency, and billing amount. Payments reoccur until the profile expires, there are too many failed payments to continue, or you cancel the profile." Thus, the end date is based on the start date and billing frequency, and number of payments.
In contrast to the above data structure, when you "Create an agreement", the request returns no calculated information as to the end date. The data you receive as a response looks like:
Response (agreement object):
Returns the agreement object based on the billing plan. The response includes a billing agreement id and return links to obtain the buyer information and to execute the subscription.
Property Type Description
id string Identifier of the agreement.
name string Name of the agreement.
description string Description of the agreement.
start_date string Start date of the agreement. Date format yyyy-MM-dd z, as defined in ISO8601.
payer payer Details of the buyer who is enrolling in this agreement. This information is gathered from execution of the approval URL.
shipping_address address Shipping address object of the agreement, which should be provided if it is different from the default address.
override_merchant_preferences merchant_preferences Default merchant preferences from the billing plan are used, unless override preferences are provided here.
override_charge_models array of override_charge_model Array of override_charge_model for this agreement if needed to change the default models from the billing plan.
plan plan Plan details for this agreement.
create_time string Date and time that this resource was created. Date format yyyy-MM-dd z, as defined in ISO8601.
update_time string Date and time that this resource was updated. Date format yyyy-MM-dd z, as defined in ISO8601.
links array of links ~
plan object:
Billing plan resource that will be used to create a billing agreement.
Property Type Description
id string Identifier of the billing plan. Assigned in response.
name string Name of the billing plan. Required.
description string Description of the billing plan. Required.
type string Type of the billing plan. Possible types include: FIXED and INFINITE. Required.
state string Status of the billing plan. Possible states include: CREATED, ACTIVE, and INACTIVE. Assigned in response.
payee payee Details of the merchant who is creating this billing plan. Assigned in response.
create_time string Time when the billing plan was created, represented as YYYY-MM-DDTimeTimezone format. Assigned in response.
update_time string Time when this billing plan was updated, represented as YYYY-MM-DDTimeTimezone format. Assigned in response.
payment_definitions array of payment_definition Array of payment definitions for this billing plan.
terms array of terms Array of terms for this billing plan. Assigned in response.
merchant_preferences merchant_preferences Specific preferences such as: set up fee, max fail attempts, autobill amount, and others that are configured for this billing plan.
links array of links ~
payment_definition object:
Resource representing payment definition scheduling information.
Property Type Description
id string Identifier of the payment_definition. Assigned in response.
name string Name of the payment definition. Required.
type string Type of the payment definition. Possible types include: TRIAL and REGULAR. Required.
frequency_interval string How frequently the customer should be charged. Required.
frequency string Frequency of the payment definition offered. Required.
cycles string Number of cycles in this payment definition. Required.
amount currency Amount that will be charged at the end of each cycle for this payment definition. Required.
charge_models array of charge_models Array of charge_models for this payment definition.
terms object:
Resource representing terms used by the plan.
Property Type Description
id string Identifier of the terms. Assigned in response.
type string Term type Required.
max_billing_amount currency Max Amount associated with this term. Required.
occurrences string How many times money can be pulled during this term. Required.
amount_range currency Amount_range associated with this term. Required.
buyer_editable string Buyer’s ability to edit the amount in this term. Required.
currency object:
Base object for all financial value related fields (balance, payment due, etc.)
Property Type Description
currency string 3 letter currency code as defined by ISO 4217. Required.
value string amount up to N digit after the decimals separator as defined in ISO 4217 for the appropriate currency code. Required.
charge_models object:
A resource representing a charge model for a payment definition.
Property Type Description
id string Identifier of the charge model. Assigned in response.
type string Type of charge model, possible values can be shipping/tax. Required.
amount currency Specific amount for this charge model. Required.
[Some portions of the data structure definition are not included here as they do not affect the end date.]
Example response:
{
"name": "T-Shirt of the Month Club Agreement",
"description": "Agreement for T-Shirt of the Month Club Plan",
"plan": {
"id": "P-94458432VR012762KRWBZEUA",
"state": "ACTIVE",
"name": "T-Shirt of the Month Club Plan",
"description": "Template creation.",
"type": "FIXED",
"payment_definitions": [
{
"id": "PD-50606817NF8063316RWBZEUA",
"name": "Regular Payments",
"type": "REGULAR",
"frequency": "Month",
"amount": {
"currency": "USD",
"value": "100"
},
"charge_models": [
{
"id": "CHM-92S85978TN737850VRWBZEUA",
"type": "TAX",
"amount": {
"currency": "USD",
"value": "12"
}
},
{
"id": "CHM-55M5618301871492MRWBZEUA",
"type": "SHIPPING",
"amount": {
"currency": "USD",
"value": "10"
}
}
],
"cycles": "12",
"frequency_interval": "2"
}
],
"merchant_preferences": {
"setup_fee": {
"currency": "USD",
"value": "1"
},
"max_fail_attempts": "0",
"return_url": "http://www.return.com",
"cancel_url": "http://www.cancel.com",
"auto_bill_amount": "YES",
"initial_fail_amount_action": "CONTINUE"
}
},
"links": [
{
"href": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-0JP008296V451950C",
"rel": "approval_url",
"method": "REDIRECT"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/EC-0JP008296V451950C/agreement-execute",
"rel": "execute",
"method": "POST"
}
],
"start_date": "2015-02-19T00:37:04Z"
}
Calculating the end date yourself:
For this profile the information relevant to determining the end date is:
{
"plan": {
"payment_definitions": [
{
"frequency": "Month",
"cycles": "12",
"frequency_interval": "2"
}
],
},
"start_date": "2015-02-19T00:37:04Z"
}
That is the information you receive. You do not get an explicitly stated end date. You have to calculate the end of the payments yourself. In the above example, payments would be made 12 times, every other month, starting on 2015-02-19. The customer will be billed on the following days:
Charge Date
Number
1 2015-02-19
2 2015-04-19
3 2015-06-19
4 2015-08-19
5 2015-10-19
6 2015-12-19
7 2016-02-19
8 2016-04-19
9 2016-06-19
10 2016-08-19
11 2016-10-19
12 2016-12-19

Answer 2

Once you retrieve the Billing Agreement Details you will get the variable "final_payment_date" which you can store in your DB as it indicates the end date for the billing agreement .
I have included the sample request and response :
Request
GET https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-YBM89E79APJ1
Response :
{
"id": "I-YBM89E79APJ1",
"state": "Active",
"description": "Agreement for Fast Speed Plan",
"plan": {
"payment_definitions": [
{
"type": "TRIAL",
"frequency": "Month",
"amount": {
"currency": "USD",
"value": "100.00"
},
"cycles": "12",
"charge_models": [
{
"type": "TAX",
"amount": {
"currency": "USD",
"value": "12.00"
}
},
{
"type": "SHIPPING",
"amount": {
"currency": "USD",
"value": "10.00"
}
}
],
"frequency_interval": "2"
},
{
"type": "REGULAR",
"frequency": "Month",
"amount": {
"currency": "USD",
"value": "100.00"
},
"cycles": "12",
"charge_models": [
{
"type": "TAX",
"amount": {
"currency": "USD",
"value": "12.00"
}
},
{
"type": "SHIPPING",
"amount": {
"currency": "USD",
"value": "10.00"
}
}
],
"frequency_interval": "2"
}
],
"merchant_preferences": {
"setup_fee": {
"currency": "USD",
"value": "1.00"
},
"max_fail_attempts": "0",
"auto_bill_amount": "YES"
}
},
"links": [
{
"href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-YBM89E79APJ1/suspend",
"rel": "suspend",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-YBM89E79APJ1/re-activate",
"rel": "re_activate",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-YBM89E79APJ1/cancel",
"rel": "cancel",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-YBM89E79APJ1/bill-balance",
"rel": "self",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-YBM89E79APJ1/set-balance",
"rel": "self",
"method": "POST"
}
],
"start_date": "2015-02-19T08:00:00Z",
"agreement_details": {
"outstanding_balance": {
"currency": "USD",
"value": "0.00"
},
"cycles_remaining": "12",
"cycles_completed": "0",
"next_billing_date": "2015-02-19T08:00:00Z",
"last_payment_date": "2014-07-21T09:18:28Z",
"last_payment_amount": {
"currency": "USD",
"value": "1.00"
},
"final_payment_date": "2018-12-19T10:00:00Z",
"failed_payment_count": "0"
}
}