Billing Agreements API

You use billing plans and billing agreements to create an agreement for a recurring credit card, bank card, or PayPal payment for goods or services.

To create an agreement, you reference an active billing plan from which the agreement inherits information. You also supply customer and payment information and, optionally, can override the referenced plan's merchant preferences and shipping fee and tax information.

For more information, see Billing Plans and Agreements.

Billing agreements (resource group)

Use the /billing-agreements resource to create an agreement, update an agreement, show agreement details, and cancel agreements. You can also set or bill the balance for an agreement. You can re-activate an agreement, suspend an agreement, list agreement transactions, and execute agreements.

Create agreement

POST /v1/payments/billing-agreements

Creates a billing agreement. In the JSON request body, include an agreement object with the name, description, start date, ID of the plan on which to base the agreement, and customer and shipping address information. A successful request returns the HTTP 201 Created status code and a JSON response body that shows billing agreement details.

Request

Pass the agreement details in the JSON body of a POST call, including the following agreement object properties. The sample requests are:

Sample 1. Creates agreement for a recurring PayPal payment that overrides the merchant preferences and charge models.
Sample 2. Creates agreement for a recurring PayPal payment.
Sample 3. Creates agreement for a recurring direct credit card payment.

name

string

required

The agreement name.

Maximum length: 128.
description

string

required

The agreement description.

Maximum length: 128.
start_date

string

required

The date when this agreement begins, in Internet date and time format. The start date must be greater than the current date. The agreement can take up to 24 hours to activate.

The start date in the create agreement request might not match the start date that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date to the start of the day in the time zone of the merchant account. For example, the API converts a 2017-01-02T14:36:21Z start date for an account in the Berlin time zone (UTC + 1) to 2017-01-02T00:00:00.

When the API returns this date in the execute agreement response, it shows the converted date and time in the UTC time zone. So, the internal 2017-01-02T00:00:00 start date becomes 2017-01-01T23:00:00 externally.
agreement_details

object

The agreement details.
payer

object

required

The customer details. The API gathers this information from execution of the approval URL.
shipping_address

object

The shipping address of the agreement, which must be provided if it differs from the default address.
override_merchant_preferences

object

Merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan.
override_charge_models

array (contains the override_charge_model object)

A charge model that overrides default charge information during agreement creation.
plan

object

required

The details for the plan on which this agreement is based.

SDK samples: C#, Node.js, PHP, Python

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/ \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "name": "Override Agreement",
  "description": "PayPal payment agreement that overrides merchant preferences and shipping fee and tax information.",
  "start_date": "2017-12-22T09:13:49Z",
  "payer": {
  "payment_method": "paypal",
  "payer_info": {
    "email": "kkarunanidhi-per1@paypal.com"
  }
  },
  "plan": {
  "id": "P-1WJ68935LL406420PUTENA2I",
  "name": "Fast Speed Plan",
  "description": "Vanilla plan",
  "type": "INFINITE"
  },
  "shipping_address": {
  "line1": "Hotel Staybridge",
  "line2": "Crooke Street",
  "city": "San Jose",
  "state": "CA",
  "postal_code": "95112",
  "country_code": "US"
  },
  "override_merchant_preferences": {
  "setup_fee": {
    "value": "3",
    "currency": "GBP"
  },
  "return_url": "http://indiatimes.com",
  "cancel_url": "http://rediff.com",
  "auto_bill_amount": "YES",
  "initial_fail_amount_action": "CONTINUE",
  "max_fail_attempts": "11"
  },
  "override_charge_models": [
  {
    "charge_id": "CHM-8373958130821962WUTENA2Q",
    "amount": {
    "value": "1",
    "currency": "GBP"
    }
  }
  ]
}'

SDK samples: C#, Node.js, PHP, Python

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/ \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "name": "Magazine Subscription",
  "description": "Monthly subscription with a regular monthly payment definition and two-month trial payment definition.",
  "start_date": "2017-12-22T09:13:49Z",
  "plan":
  {
  "id": "{{plan_id}}"
  },
  "payer":
  {
  "payment_method": "paypal"
  },
  "shipping_address":
  {
  "line1": "751235 Stout Drive",
  "line2": "0976249 Elizabeth Court",
  "city": "Quimby",
  "state": "IA",
  "postal_code": "51049",
  "country_code": "US"
  }
}'

SDK samples: C#, Node.js, PHP, Python

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/ \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "name": "Direct Credit Card Payment",
  "description": "Recurring credit card payment.",
  "start_date": "2017-12-22T09:13:49Z",
  "plan":
  {
  "id": "P-2PL786081D358645F6NWEKFQ"
  },
  "payer":
  {
  "payment_method": "credit_card",
  "payer_info":
  {
    "email": "johndoe@example.com"
  },
  "funding_instruments": [
  {
    "credit_card":
    {
    "type": "visa",
    "number": "4417119664863864",
    "expire_month": "12",
    "expire_year": "2021",
    "cvv2": "111",
    "start_month": "11",
    "start_year": "2016",
    "billing_address":
    {
      "line1": "065769 Holcomb Bridge Road #141",
      "line2": "5713 E Dimond Boulevard #B9",
      "city": "Wichita",
      "state": "KS",
      "postal_code": "67202",
      "country_code": "US",
      "phone": "+1 6202311026"
    }
    }
  }]
  }
}'

Response

A successful request returns the HTTP 201 Created status code and a JSON response body that shows billing agreement details. The response includes a billing agreement id and redirect links to get the buyer's approval. The sample responses are:

Sample 1. Agreement for a recurring PayPal payment that overrides the merchant preferences and charge models.
Sample 2. Agreement for a recurring PayPal payment.
Sample 3. Agreement for a recurring direct credit card payment.

id

string

The PayPal-generated agreement ID.

Read only.

Maximum length: 128.
state

string

The state of the agreement. Value is Active, Cancelled, Completed, Created, Pending, Reactivated, or Suspended.

Read only.

Maximum length: 128.
name

string

The agreement name.

Maximum length: 128.
description

string

The agreement description.

Maximum length: 128.
start_date

string

The date when this agreement begins, in Internet date and time format. The start date must be greater than the current date. The agreement can take up to 24 hours to activate.

The start date in the create agreement request might not match the start date that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date to the start of the day in the time zone of the merchant account. For example, the API converts a 2017-01-02T14:36:21Z start date for an account in the Berlin time zone (UTC + 1) to 2017-01-02T00:00:00.

When the API returns this date in the execute agreement response, it shows the converted date and time in the UTC time zone. So, the internal 2017-01-02T00:00:00 start date becomes 2017-01-01T23:00:00 externally.
agreement_details

object

The agreement details.
payer

object

The customer details. The API gathers this information from execution of the approval URL.
shipping_address

object

The shipping address of the agreement, which must be provided if it differs from the default address.
override_merchant_preferences

object

Merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan.
override_charge_models

array (contains the override_charge_model object)

A charge model that overrides default charge information during agreement creation.
plan

object

The details for the plan on which this agreement is based.
links

array (contains the link object)

HATEOAS links related to this call.

Read only.

Sample Response

{
  "id": "I-1TJ3GAGG82Y9",
  "name": "Override Agreement",
  "description": "Agreement that overrides merchant preferences and charge models",
  "payer": {
    "payment_method": "paypal",
    "payer_info": {
      "email": "kkarunanidhi-per1@paypal.com"
    }
  },
  "plan": {
    "id": "P-1WJ68935LL406420PUTENA2I",
    "state": "ACTIVE",
    "name": "Fast Speed Plan",
    "description": "Vanilla plan",
    "type": "INFINITE",
    "payment_definitions": [
      {
        "id": "PD-9WG6983719571780GUTENA2I",
        "name": "Regular payment definition",
        "type": "REGULAR",
        "frequency": "DAY",
        "amount": {
          "currency": "GBP",
          "value": "10"
        },
        "charge_models": [
          {
            "id": "CHM-8373958130821962WUTENA2Q",
            "type": "SHIPPING",
            "amount": {
              "currency": "GBP",
              "value": "1"
            }
          },
          {
            "id": "CHM-2937144979861454NUTENA2Q",
            "type": "TAX",
            "amount": {
              "currency": "GBP",
              "value": "2"
            }
          }
        ],
        "cycles": "0",
        "frequency_interval": "1"
      },
      {
        "id": "PD-89M493313S710490TUTENA2Q",
        "name": "Trial payment definition",
        "type": "TRIAL",
        "frequency": "MONTH",
        "amount": {
          "currency": "GBP",
          "value": "100"
        },
        "charge_models": [
          {
            "id": "CHM-78K47820SS4923826UTENA2Q",
            "type": "SHIPPING",
            "amount": {
              "currency": "GBP",
              "value": "10"
            }
          },
          {
            "id": "CHM-9M366179U7339472RUTENA2Q",
            "type": "TAX",
            "amount": {
              "currency": "GBP",
              "value": "12"
            }
          }
        ],
        "cycles": "5",
        "frequency_interval": "2"
      }
    ],
    "merchant_preferences": {
      "setup_fee": {
        "currency": "GBP",
        "value": "3"
      },
      "max_fail_attempts": "11",
      "return_url": "http://indiatimes.com",
      "cancel_url": "http://rediff.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-83C745436S346813F",
      "rel": "approval_url",
      "method": "REDIRECT"
    },
    {
      "href": "https://www.sandbox.paypal.com/v1/payments/billing-agreements/EC-83C745436S346813F/agreement-execute",
      "rel": "execute",
      "method": "POST"
    }
  ],
  "start_date": "2017-12-22T09:13:49Z"
}

Sample Response

{
  "id": "I-Y6TL8T5KT95R",
  "name": "Magazine Subscription",
  "description": "Monthly subscription with a regular monthly payment definition and two-month trial payment definition.",
  "plan": {
    "id": "P-3NL67884YE672133CEXBTJTA",
    "state": "ACTIVE",
    "name": "Magazine Subscription",
    "description": "Monthly subscription with a regular monthly payment definition and two-month trial payment definition.",
    "type": "FIXED",
    "payment_definitions": [
      {
        "id": "PD-7AP59297JL233383BEXBTJTA",
        "name": "Regular monthly payment definition",
        "type": "REGULAR",
        "frequency": "Month",
        "amount": {
          "currency": "USD",
          "value": "5.99"
        },
        "cycles": "10",
        "charge_models": [
          {
            "id": "CHM-0808282002866834SEXBTJTA",
            "type": "TAX",
            "amount": {
              "currency": "USD",
              "value": "0.29"
            }
          },
          {
            "id": "CHM-86952323Y27891226EXBTJTA",
            "type": "SHIPPING",
            "amount": {
              "currency": "USD",
              "value": "0.2"
            }
          }
        ],
        "frequency_interval": "1"
      },
      {
        "id": "PD-3F67327340580952AEXBTJTA",
        "name": "Free trial payment definition",
        "type": "TRIAL",
        "frequency": "Month",
        "amount": {
          "currency": "USD",
          "value": "0"
        },
        "cycles": "2",
        "charge_models": [],
        "frequency_interval": "1"
      }
    ],
    "merchant_preferences": {
      "setup_fee": {
        "currency": "USD",
        "value": "0.4"
      },
      "max_fail_attempts": "2",
      "return_url": "http://www.example.com/success",
      "cancel_url": "http://www.example.com/cancel",
      "auto_bill_amount": "YES",
      "initial_fail_amount_action": "CONTINUE"
    }
  },
  "start_date": "2017-12-22T09:13:49Z",
  "links": [
    {
      "href": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-7WN97463LN263864T",
      "rel": "approval_url",
      "method": "REDIRECT"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/EC-7WN97463LN263864T/agreement-execute",
      "rel": "execute",
      "method": "POST"
    }
  ]
}

Sample Response

{
  "id": "I-Y6TL8T5KT95R",
  "state": "Active",
  "description": "Recurring credit card payment.",
  "payer": {
    "payment_method": "credit_card",
    "payer_info": {
      "email": "johndoe@example.com"
    },
    "funding_instruments": [
      {
        "credit_card": {
          "type": "visa",
          "number": "3864",
          "expire_month": "12",
          "expire_year": "2021",
          "start_month": "11",
          "start_year": "2016",
          "billing_address": {
            "line1": "065769 Holcomb Bridge Road #141",
            "line2": "5713 E Dimond Boulevard #B9",
            "city": "Wichita",
            "state": "KS",
            "postal_code": "67202",
            "country_code": "US"
          }
        }
      }
    ]
  },
  "plan": {
    "payment_definitions": [
      {
        "type": "TRIAL",
        "frequency": "Month",
        "amount": {
          "value": "0",
          "currency": "USD"
        },
        "cycles": "2",
        "charge_models": [
          {
            "type": "TAX",
            "amount": {
              "value": "0",
              "currency": "USD"
            }
          },
          {
            "type": "SHIPPING",
            "amount": {
              "value": "0",
              "currency": "USD"
            }
          }
        ],
        "frequency_interval": "1"
      },
      {
        "type": "REGULAR",
        "frequency": "Month",
        "amount": {
          "value": "5.99",
          "currency": "USD"
        },
        "cycles": "10",
        "charge_models": [
          {
            "type": "TAX",
            "amount": {
              "value": "0.29",
              "currency": "USD"
            }
          },
          {
            "type": "SHIPPING",
            "amount": {
              "value": "0.20",
              "currency": "USD"
            }
          }
        ],
        "frequency_interval": "1"
      }
    ],
    "merchant_preferences": {
      "setup_fee": {
        "value": "0.40",
        "currency": "USD"
      },
      "max_fail_attempts": "3",
      "auto_bill_amount": "YES"
    },
    "links": [],
    "currency_code": "USD"
  },
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-Y6TL8T5KT95R",
      "rel": "self",
      "method": "GET"
    }
  ],
  "start_date": "2017-12-22T09:13:49Z",
  "agreement_details": {
    "outstanding_balance": {
      "value": "0.00",
      "currency": "USD"
    },
    "cycles_remaining": "12",
    "cycles_completed": "0",
    "next_billing_date": "2017-12-22T09:13:49Z",
    "last_payment_date": "2017-01-02T09:13:49Z",
    "last_payment_amount": {
      "value": "0.40",
      "currency": "USD"
    },
    "final_payment_date": "2017-12-03T00:00:00Z",
    "failed_payment_count": "0"
  }
}

Update agreement

PATCH /v1/payments/billing-agreements/agreement_id

Updates details of a billing agreement, by ID. Details include the description, shipping address, start date, and so on. A successful request returns the HTTP 200 OK status code with no JSON response body.

Parameters

agreement_id

path string

The ID of the agreement to update.

Request

items

array (contains the json_patch object)

A JSON patch object to use to apply partial updates to resources.

SDK samples: Node.js, PHP, Python

Sample Request

curl -v -X PATCH https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9 \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[
  {
  "op": "replace",
  "path": "/",
  "value": {
    "description": "Updated description.",
    "start_date": "2017-12-22T09:13:49Z",
    "shipping_address": {
    "line1": "Hotel Blue Diamond",
    "line2": "Church Street",
    "city": "San Jose",
    "state": "CA",
    "postal_code": "95112",
    "country_code": "US"
    }
  }
  }
]'

Response

A successful request returns the HTTP 200 OK status code with no JSON response body.

Sample Response

200 OK

Show agreement details

GET /v1/payments/billing-agreements/agreement_id

Shows details for a billing agreement, by ID. A successful request returns the HTTP 200 OK status code and a JSON response body that shows billing agreement details.

Parameters

agreement_id

path string

The ID of the agreement for which to show details.

SDK samples: C#, Node.js, PHP, Python

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-5D3XDN2D5FH1 \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that shows billing agreement details.

id

string

The PayPal-generated agreement ID.

Read only.

Maximum length: 128.
state

string

The state of the agreement. Value is Active, Cancelled, Completed, Created, Pending, Reactivated, or Suspended.

Read only.

Maximum length: 128.
name

string

The agreement name.

Maximum length: 128.
description

string

The agreement description.

Maximum length: 128.
start_date

string

The date when this agreement begins, in Internet date and time format. The start date must be greater than the current date. The agreement can take up to 24 hours to activate.

The start date in the create agreement request might not match the start date that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date to the start of the day in the time zone of the merchant account. For example, the API converts a 2017-01-02T14:36:21Z start date for an account in the Berlin time zone (UTC + 1) to 2017-01-02T00:00:00.

When the API returns this date in the execute agreement response, it shows the converted date and time in the UTC time zone. So, the internal 2017-01-02T00:00:00 start date becomes 2017-01-01T23:00:00 externally.
agreement_details

object

The agreement details.
payer

object

The customer details. The API gathers this information from execution of the approval URL.
shipping_address

object

The shipping address of the agreement, which must be provided if it differs from the default address.
override_merchant_preferences

object

Merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan.
override_charge_models

array (contains the override_charge_model object)

A charge model that overrides default charge information during agreement creation.
plan

object

The details for the plan on which this agreement is based.
links

array (contains the link object)

HATEOAS links related to this call.

Read only.

Sample Response

{
  "id": "I-1TJ3GAGG82Y9",
  "state": "Active",
  "name": "Monthly agreement with free trial payment definition",
  "description": "Monthly agreement with free trial payment definition.",
  "payer": {
    "payment_method": "paypal",
    "status": "unverified",
    "payer_info": {
      "email": "johndoe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "payer_id": "NEW8A85AK4ET4",
      "shipping_address": {
        "recipient_name": "John Doe",
        "line1": "751235 Stout Drive",
        "line2": "0976249 Elizabeth Court",
        "city": "Quimby",
        "state": "IA",
        "postal_code": "51049",
        "country_code": "US"
      }
    }
  },
  "plan": {
    "name": "Plan with Regular and Trial Payment Definitions",
    "description": "Plan with regular and trial payment definitions.",
    "type": "FIXED",
    "payment_definitions": [
      {
        "name": "Trial payment definition",
        "type": "TRIAL",
        "frequency": "MONTH",
        "amount": {
          "value": "0.00",
          "currency": "USD"
        },
        "cycles": "2",
        "charge_models": [
          {
            "type": "TAX",
            "amount": {
              "value": "0.00",
              "currency": "USD"
            }
          },
          {
            "type": "SHIPPING",
            "amount": {
              "value": "0.00",
              "currency": "USD"
            }
          }
        ],
        "frequency_interval": "1"
      },
      {
        "name": "Regular payment definition",
        "type": "REGULAR",
        "frequency": "MONTH",
        "amount": {
          "value": "5.99",
          "currency": "USD"
        },
        "cycles": "10",
        "charge_models": [
          {
            "type": "TAX",
            "amount": {
              "value": "0.29",
              "currency": "USD"
            }
          },
          {
            "type": "SHIPPING",
            "amount": {
              "value": "0.20",
              "currency": "USD"
            }
          }
        ],
        "frequency_interval": "1"
      }
    ],
    "merchant_preferences": {
      "setup_fee": {
        "value": "0.40",
        "currency": "USD"
      },
      "return_url": "http://www.paypal.com",
      "cancel_url": "http://www.paypal.com/cancel",
      "max_fail_attempts": "2",
      "auto_bill_amount": "YES"
    },
    "links": [],
    "currency_code": "USD"
  },
  "start_date": "2016-12-23T08:00:00Z",
  "shipping_address": {
    "recipient_name": "John Doe",
    "line1": "751235 Stout Drive",
    "line2": "0976249 Elizabeth Court",
    "city": "Quimby",
    "state": "IA",
    "postal_code": "51049",
    "country_code": "US"
  },
  "agreement_details": {
    "outstanding_balance": {
      "currency": "USD",
      "value": "0.00"
    },
    "cycles_remaining": "2",
    "cycles_completed": "0",
    "next_billing_date": "2017-01-23T08:00:00Z",
    "last_payment_date": "2016-12-23T08:00:00Z",
    "last_payment_amount": {
      "currency": "USD",
      "value": "0.40"
    },
    "final_payment_date": "2017-09-23T08:00:00Z",
    "failed_payment_count": "0"
  },
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/suspend",
      "rel": "suspend",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/re-activate",
      "rel": "re_activate",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/cancel",
      "rel": "cancel",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/bill-balance",
      "rel": "self",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/set-balance",
      "rel": "self",
      "method": "POST"
    }
  ]
}

Bill agreement balance

POST /v1/payments/billing-agreements/agreement_id/bill-balance

Bills the balance for an agreement, by ID. In the JSON request body, include an optional note that describes the reason for the billing action and the agreement amount and currency. A successful request returns the HTTP 204 No Content status code with no JSON response body.

Parameters

agreement_id

path string

The ID of the agreement for which to bill the balance.

Request

note

string

The reason for the agreement state change.

Maximum length: 128.

SDK samples: Node.js, Python

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/bill-balance \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "note": "Billing balance amount.",
  "amount": {
  "value": "100",
  "currency": "USD"
  }
}'

Response

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Sample Response

204 No Content

Cancel agreement

POST /v1/payments/billing-agreements/agreement_id/cancel

Cancels a billing agreement, by ID. In the JSON request body, include an agreement_state_descriptor object with an optional note that describes the reason for the cancellation and the agreement amount and currency. A successful request returns the HTTP 204 No Content status code with no JSON response body.

Parameters

agreement_id

path string

The ID of the agreement to cancel.

Request

note

string

The reason for the agreement state change.

Maximum length: 128.

SDK samples: Node.js, Python

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/cancel \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "note": "Canceling the profile."
}'

Response

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Sample Response

204 No Content

Re-activate agreement

POST /v1/payments/billing-agreements/agreement_id/re-activate

Re-activates a suspended billing agreement, by ID. In the JSON request body, include an agreement_state_descriptor object with with a note that describes the reason for the re-activation and the agreement amount and currency. A successful request returns the HTTP 204 No Content status code with no JSON response body.

Parameters

agreement_id

path string

The ID of the agreement to re-activate.

Request

note

string

The reason for the agreement state change.

Maximum length: 128.

SDK samples: Node.js, PHP, Python

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/re-activate \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "note": "Re-activating the profile."
}'

Response

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Sample Response

204 No Content

Set agreement balance

POST /v1/payments/billing-agreements/agreement_id/set-balance

Sets the balance for an agreement, by ID. In the JSON request body, specify the balance currency type and value. A successful request returns the HTTP 204 No Content status code with no JSON response body.

Parameters

agreement_id

path string

The ID of the agreement for which to set a balance.

Request

currency

string

required

The three-letter ISO 4217 alphabetic currency code.
value

string

required

The currency value. Might be an integer for currencies like JPY that are not typically fractional or a three-place decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see ISO 4217.

Maximum length: 32.

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

SDK samples: Node.js, Python

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/set-balance \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "value": "100",
  "currency": "USD"
}'

Response

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Sample Response

204 No Content

Suspend agreement

POST /v1/payments/billing-agreements/agreement_id/suspend

Suspends a billing agreement, by ID. A successful request returns the HTTP 204 No Content status code with no JSON response body.

Parameters

agreement_id

path string

The ID of the agreement to suspend.

Request

note

string

The reason for the agreement state change.

Maximum length: 128.

SDK samples: Node.js, PHP, Python

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/suspend \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "note": "Suspending the profile."
}'

Response

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Sample Response

204 No Content

List agreement transactions

GET /v1/payments/billing-agreements/agreement_id/transactions

Lists transactions for an agreement, by ID. To filter the transactions that appear in the response, specify the optional start and end date query parameters. A successful request returns the HTTP 200 OK status code and a JSON response body that lists transactions with details.

Parameters

agreement_id

path string

The ID of the agreement for which to list transactions.
start_date

query_string date

The start date of the range of transactions to list.
end_date

query_string date

The end date of the range of transactions to list.

SDK samples: C#, Node.js, PHP, Python

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/transaction?start_date=2017-06-15&end_date=2017-06-17 \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that lists transactions with details.

agreement_transaction_list

array (contains the agreement_transaction object)

An agreement transaction. Returned for a transaction search.

Sample Response

{
  "agreement_transaction_list": [
    {
      "transaction_id": "I-V8SSE9WLJGY6",
      "status": "Created",
      "transaction_type": "Recurring Payment",
      "amount": {
        "value": "100",
        "currency": "USD"
      },
      "fee_amount": {
        "value": "1",
        "currency": "USD"
      },
      "net_amount": {
        "value": "100",
        "currency": "USD"
      },
      "payer_email": "",
      "payer_name": " ",
      "time_stamp": "2017-06-16T13:46:53Z",
      "time_zone": "GMT"
    },
    {
      "transaction_id": "I-V8SSE9WLJGY6",
      "status": "Suspended",
      "transaction_type": "Recurring Payment",
      "amount": {
        "value": "100",
        "currency": "USD"
      },
      "fee_amount": {
        "value": "1",
        "currency": "USD"
      },
      "net_amount": {
        "value": "100",
        "currency": "USD"
      },
      "payer_email": "",
      "payer_name": " ",
      "time_stamp": "2017-06-16T13:52:26Z",
      "time_zone": "GMT"
    },
    {
      "transaction_id": "I-V8SSE9WLJGY6",
      "status": "Reactivated",
      "transaction_type": "Recurring Payment",
      "amount": {
        "value": "100",
        "currency": "USD"
      },
      "fee_amount": {
        "value": "1",
        "currency": "USD"
      },
      "net_amount": {
        "value": "100",
        "currency": "USD"
      },
      "payer_email": "",
      "payer_name": " ",
      "time_stamp": "2017-06-16T14:00:23Z",
      "time_zone": "GMT"
    },
    {
      "transaction_id": "I-V8SSE9WLJGY6",
      "status": "Cancelled",
      "transaction_type": "Recurring Payment",
      "amount": {
        "value": "100",
        "currency": "USD"
      },
      "fee_amount": {
        "value": "1",
        "currency": "USD"
      },
      "net_amount": {
        "value": "100",
        "currency": "USD"
      },
      "payer_email": "",
      "payer_name": " ",
      "time_stamp": "2017-06-16T14:02:54Z",
      "time_zone": "GMT"
    }
  ]
}

Execute agreement

POST /v1/payments/billing-agreements/payment_token/agreement-execute

Executes a billing agreement, by ID, after customer approval. A successful request returns the HTTP 200 OK status code and a JSON response body that shows billing agreement details.

Parameters

payment_token

path string

The ID of the agreement to execute.

SDK samples: C#, Node.js, PHP, Python

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/EC-7WN97463LN263864T/agreement-execute \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that shows billing agreement details.

id

string

The PayPal-generated agreement ID.

Read only.

Maximum length: 128.
state

string

The state of the agreement. Value is Active, Cancelled, Completed, Created, Pending, Reactivated, or Suspended.

Read only.

Maximum length: 128.
name

string

The agreement name.

Maximum length: 128.
description

string

The agreement description.

Maximum length: 128.
start_date

string

The date when this agreement begins, in Internet date and time format. The start date must be greater than the current date. The agreement can take up to 24 hours to activate.

The start date in the create agreement request might not match the start date that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date to the start of the day in the time zone of the merchant account. For example, the API converts a 2017-01-02T14:36:21Z start date for an account in the Berlin time zone (UTC + 1) to 2017-01-02T00:00:00.

When the API returns this date in the execute agreement response, it shows the converted date and time in the UTC time zone. So, the internal 2017-01-02T00:00:00 start date becomes 2017-01-01T23:00:00 externally.
agreement_details

object

The agreement details.
payer

object

The customer details. The API gathers this information from execution of the approval URL.
shipping_address

object

The shipping address of the agreement, which must be provided if it differs from the default address.
override_merchant_preferences

object

Merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan.
override_charge_models

array (contains the override_charge_model object)

A charge model that overrides default charge information during agreement creation.
plan

object

The details for the plan on which this agreement is based.
links

array (contains the link object)

HATEOAS links related to this call.

Read only.

Sample Response

{
  "id": "I-1TJ3GAGG82Y9",
  "state": "Active",
  "name": "Monthly agreement with free trial payment definition",
  "description": "Monthly agreement with free trial payment definition.",
  "payer": {
    "payment_method": "paypal",
    "status": "unverified",
    "payer_info": {
      "email": "johndoe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "payer_id": "NEW8A85AK4ET4",
      "shipping_address": {
        "recipient_name": "John Doe",
        "line1": "751235 Stout Drive",
        "line2": "0976249 Elizabeth Court",
        "city": "Quimby",
        "state": "IA",
        "postal_code": "51049",
        "country_code": "US"
      }
    }
  },
  "plan": {
    "name": "Plan with Regular and Trial Payment Definitions",
    "description": "Plan with regular and trial payment definitions.",
    "type": "FIXED",
    "payment_definitions": [
      {
        "name": "Trial payment definition",
        "type": "TRIAL",
        "frequency": "MONTH",
        "amount": {
          "value": "0.00",
          "currency": "USD"
        },
        "cycles": "2",
        "charge_models": [
          {
            "type": "TAX",
            "amount": {
              "value": "0.00",
              "currency": "USD"
            }
          },
          {
            "type": "SHIPPING",
            "amount": {
              "value": "0.00",
              "currency": "USD"
            }
          }
        ],
        "frequency_interval": "1"
      },
      {
        "name": "Regular payment definition",
        "type": "REGULAR",
        "frequency": "MONTH",
        "amount": {
          "value": "5.99",
          "currency": "USD"
        },
        "cycles": "10",
        "charge_models": [
          {
            "type": "TAX",
            "amount": {
              "value": "0.29",
              "currency": "USD"
            }
          },
          {
            "type": "SHIPPING",
            "amount": {
              "value": "0.20",
              "currency": "USD"
            }
          }
        ],
        "frequency_interval": "1"
      }
    ],
    "merchant_preferences": {
      "setup_fee": {
        "value": "0.40",
        "currency": "USD"
      },
      "return_url": "http://www.paypal.com",
      "cancel_url": "http://www.paypal.com/cancel",
      "max_fail_attempts": "2",
      "auto_bill_amount": "YES"
    },
    "links": [],
    "currency_code": "USD"
  },
  "start_date": "2016-12-23T08:00:00Z",
  "shipping_address": {
    "recipient_name": "John Doe",
    "line1": "751235 Stout Drive",
    "line2": "0976249 Elizabeth Court",
    "city": "Quimby",
    "state": "IA",
    "postal_code": "51049",
    "country_code": "US"
  },
  "agreement_details": {
    "outstanding_balance": {
      "value": "0.00",
      "currency": "USD"
    },
    "cycles_remaining": "2",
    "cycles_completed": "0",
    "next_billing_date": "2017-01-23T08:00:00Z",
    "last_payment_date": "2016-12-23T08:00:00Z",
    "last_payment_amount": {
      "value": "0.40",
      "currency": "USD"
    },
    "final_payment_date": "2017-09-23T08:00:00Z",
    "failed_payment_count": "0"
  },
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Common object definitions

agreement

id

string

The PayPal-generated agreement ID.

Read only.

Maximum length: 128.
state

string

The state of the agreement. Value is Active, Cancelled, Completed, Created, Pending, Reactivated, or Suspended.

Read only.

Maximum length: 128.
name

string

The agreement name.

Maximum length: 128.
description

string

The agreement description.

Maximum length: 128.
start_date

string

The date when this agreement begins, in Internet date and time format. The start date must be greater than the current date. The agreement can take up to 24 hours to activate.

The start date in the create agreement request might not match the start date that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date to the start of the day in the time zone of the merchant account. For example, the API converts a 2017-01-02T14:36:21Z start date for an account in the Berlin time zone (UTC + 1) to 2017-01-02T00:00:00.

When the API returns this date in the execute agreement response, it shows the converted date and time in the UTC time zone. So, the internal 2017-01-02T00:00:00 start date becomes 2017-01-01T23:00:00 externally.
agreement_details

object

The agreement details.
payer

object

The customer details. The API gathers this information from execution of the approval URL.
shipping_address

object

The shipping address of the agreement, which must be provided if it differs from the default address.
override_merchant_preferences

object

Merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan.
override_charge_models

array (contains the override_charge_model object)

A charge model that overrides default charge information during agreement creation.
plan

object

The details for the plan on which this agreement is based.
links

array (contains the link object)

HATEOAS links related to this call.

Read only.

agreement_details

outstanding_balance

object

The outstanding balance for this agreement.
cycles_remaining

string

The number of payment cycles remaining for this agreement.
cycles_completed

string

The number of payment cycles completed for this agreement.
next_billing_date

string

The next billing date for this agreement, in Internet date and time format. For example, 2017-01-23T08:00:00Z.
last_payment_date

string

The last payment date for this agreement, in Internet date and time format. For example, 2016-12-23T08:00:00Z.
last_payment_amount

object

The last payment amount for this agreement.
final_payment_date

string

The final payment date for this agreement, in Internet date and time format. For example, 2017-09-23T08:00:00Z.
failed_payment_count

string

The total number of failed payments for this agreement.

agreement_state_descriptor

note

string

The reason for the agreement state change.

Maximum length: 128.

agreement_transaction

transaction_id

string

The ID of the transaction.

Read only.
status

enum

The current status of the billing agreement.

Read only.

Possible values: Active, Cancelled, Completed, Created, Pending, Reactivated, Suspended.
transaction_type

string

The type of transaction. Typically, Recurring Payment.

Read only.
amount

object

The transaction amount.
fee_amount

object

The transaction fee.
net_amount

object

The transaction net amount.
payer_email

string

The email ID of the customer.

Read only.
payer_name

string

The business name of the customer.

Read only.
time_stamp

string

The date and time when the transaction occurred.

Read only.
time_zone

string

The time zone of the update_time field.

Read only.

agreement_transactions

agreement_transaction_list

array (contains the agreement_transaction object)

An agreement transaction. Returned for a transaction search.

bank_account

id

string

The ID of the bank account that is being saved for later use.

Read only.

Maximum length: 128.
account_number

string

The account number in international bank account number (IBAN) format or basic bank account number (BBAN) format. The maximum length for the IBAN format is 34 characters. The maximum length for the BBAN format is 17 characters.

Maximum length: 34.
account_number_type

enum

The type of bank account number. A valid value is basic bank account number (BBAN) or international bank account number (IBAN). For more information, see International Bank Account Number.

Possible values: BBAN, IBAN.
routing_number

string

The routing transit number, or bank code, of the bank. Typically, you specify this value for domestic use only. International bank account numbers (IBAN) include the bank code. For more information, see Bank code.

Maximum length: 34.
account_type

enum

The bank account type.

Possible values: CHECKING, SAVINGS.
account_name

string

A customer-designated account name.

Maximum length: 64.
check_type

enum

The check type when the information was obtained from the facilitator or merchant.

Possible values: PERSONAL, COMPANY.
auth_type

enum

The authorization type, which indicates how the check was obtained from the customer if a check is the source of information.

Possible values: CCD, PPD, TEL, POP, ARC, RCK, WEB.
auth_capture_timestamp

string

The date and time when the authorization was captured. Use this parameter if you must capture the user authorization due to any privacy requirements.
bank_name

string

The bank name.

Maximum length: 64.
country_code

string

The two-letter country code of the bank.
first_name

string

The account holder's first name.

Maximum length: 64.
last_name

string

The account holder's last name.

Maximum length: 64.
birth_date

string

The account holder's birth date.
billing_address

object

The billing address.
state

enum

The state of this funding instrument.

Read only.

Possible values: ACTIVE, INACTIVE, DELETED.
confirmation_status

enum

The confirmation status of a bank account.

Read only.

Possible values: UNCONFIRMED, CONFIRMED.
payer_id

string

Deprecated. Instead, use the external_customer_id parameter.
external_customer_id

string

A unique, facilitator-generated ID for the customer who owns this bank account. Required when you create or use a vaulted funding instrument.

Maximum length: 256.
merchant_id

string

A unique, facilitator-generated ID for the merchant for whom the bank account was vaulted. Can be used to restrict usage of the bank account to the merchant.

Maximum length: 256.
create_time

string

The date and time when the bank account was created.

Read only.
update_time

string

The date and time when the bank account was last updated.

Read only.
valid_until

string

The date and time after which the bank account can no longer be used to fund a payment.

Read only.
links

array (contains the link object)

HATEOAS links related to this call.

Read only.

bank_token

bank_id

string

The ID of the vaulted bank card.
external_customer_id

string

The ID of the customer who owns the bank card.
mandate_reference_number

string

The ID of the direct debit mandate to validate. Supported only for Single Euro Payments Area (SEPA) bank accounts in the European Union (EU).

charge_models

id

string

The ID of the charge model.

Read only.

Maximum length: 128.
type

enum

The charge model type.

Possible values: TAX, SHIPPING.

Maximum length: 20.
amount

object

The amount for this charge model.

country_code

country_code

string

The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as is used in that country's top-level domain names. Use the C2 country code for CHINA WORLDWIDE (for CUP, bank card, and cross-border transactions).

Minimum length: 2.

Maximum length: 2.

Pattern: ^([A-Z]{2}|C2)$.

credit_card

id

string

The ID of the credit card to save for later use.

Read only.
number

string

The card number.
type

string

The card type. For example, Visa, MasterCard, and so on.
expire_month

see description

The two-digit card expiry month, in MM format. Value is from 01 to 12.
Possible types: integer
expire_year

see description

The four-digit card expiry year, in YYYY format.
Possible types: integer
cvv2

see description

The card validation code. Supported only when making a payment but not when saving a credit card for future use.
Possible types: integer
first_name

string

The first name of the card holder.
last_name

string

The last name of the card holder.
billing_address

object

The billing address associated with this card.
external_customer_id

string

The facilitator-provided ID of the customer who owns this bank account. Required when storing a funding instrument or using a stored funding instrument in the PayPal vault.

Maximum length: 256.
state

enum

The state of the funding instrument.

Read only.

Possible values: expired, ok.
valid_until

string

The date and time when the credit card becomes unusable from the vault, in Internet date and time format. The valid_until parameter is not the same as the expiration month and year. The expiration month and year might be later than the valid_until date. For example, the card expires in November 2019 but the valid_until date is October 17th, 2019.

Read only.
links

array (contains the link object)

HATEOAS links related to this call.

Read only.

credit_card_token

credit_card_id

string

The ID of the vaulted credit card.
payer_id

string

The ID of the customer who owns the Credit card.
last4

string

The last four digits of the card number from the vaulted credit card.

Read only.
type

string

The card type of the vaulted credit card. For example, visa, mastercard, and so on. Note that the values are always lowercase and are not meant for display.

Read only.
expire_month

see description

The expiry month from the vaulted card. Value is from 1 to 12.
Possible types: integer

Read only.
expire_year

see description

The expiry year from the vaulted card, in YYYY format.
Possible types: integer

Read only.

credit_instrument

id

string

The ID of the credit instrument.

Read only.
type

enum

The credit instrument type.

Read only.

Possible values: BILL_ME_LATER, PAYPAL_EXTRAS_MASTERCARD, EBAY_MASTERCARD, PAYPAL_SMART_CONNECT.
terms

string

The URI to the associated terms for the credit instrument.

Read only.

currency_code

currency_code

string

The three-letter ISO 4217 alphabetic currency code.

Minimum length: 3.

Maximum length: 3.

extended_bank_account

mandate_reference_number

string

The ID of the direct debit mandate to validate. Currently supported for only Single Euro Payments Area (SEPA) bank accounts in the European Union (EU).
id

string

The ID of the bank account that is being saved for later use.

Read only.

Maximum length: 128.
account_number

string

The account number in international bank account number (IBAN) format or basic bank account number (BBAN) format. The maximum length for the IBAN format is 34 characters. The maximum length for the BBAN format is 17 characters.

Maximum length: 34.
account_number_type

enum

The type of bank account number. A valid value is basic bank account number (BBAN) or international bank account number (IBAN). For more information, see International Bank Account Number.

Possible values: BBAN, IBAN.
routing_number

string

The routing transit number, or bank code, of the bank. Typically, you specify this value for domestic use only. International bank account numbers (IBAN) include the bank code. For more information, see Bank code.

Maximum length: 34.
account_type

enum

The bank account type.

Possible values: CHECKING, SAVINGS.
account_name

string

A customer-designated account name.

Maximum length: 64.
check_type

enum

The check type when the information was obtained from the facilitator or merchant.

Possible values: PERSONAL, COMPANY.
auth_type

enum

The authorization type, which indicates how the check was obtained from the customer if a check is the source of information.

Possible values: CCD, PPD, TEL, POP, ARC, RCK, WEB.
auth_capture_timestamp

string

The date and time when the authorization was captured. Use this parameter if you must capture the user authorization due to any privacy requirements.
bank_name

string

The bank name.

Maximum length: 64.
country_code

string

The two-letter country code of the bank.
first_name

string

The account holder's first name.

Maximum length: 64.
last_name

string

The account holder's last name.

Maximum length: 64.
birth_date

string

The account holder's birth date.
billing_address

object

The billing address.
state

enum

The state of this funding instrument.

Read only.

Possible values: ACTIVE, INACTIVE, DELETED.
confirmation_status

enum

The confirmation status of a bank account.

Read only.

Possible values: UNCONFIRMED, CONFIRMED.
payer_id

string

Deprecated. Instead, use the external_customer_id parameter.
external_customer_id

string

A unique, facilitator-generated ID for the customer who owns this bank account. Required when you create or use a vaulted funding instrument.

Maximum length: 256.
merchant_id

string

A unique, facilitator-generated ID for the merchant for whom the bank account was vaulted. Can be used to restrict usage of the bank account to the merchant.

Maximum length: 256.
create_time

string

The date and time when the bank account was created.

Read only.
update_time

string

The date and time when the bank account was last updated.

Read only.
valid_until

string

The date and time after which the bank account can no longer be used to fund a payment.

Read only.
links

array (contains the link object)

HATEOAS links related to this call.

Read only.

funding_instrument

credit_card

object

Credit card information.
credit_card_token

object

Credit card token information.
payment_card

object

Payment card information.
payment_card_token

object

Payment card token information.
bank_account

object

Bank account information.
bank_account_token

object

Bank account token information.
credit

object

Credit funding information.

json_patch

op

enum

The operation to perform.

Possible values: add, remove, replace, move, copy, test.
path

string

A JSON pointer that references a location in the target document where the operation is performed.
value

see description

The value to apply based on the operation. The remove operation does not require a value.
Possible types: number, integer, string, boolean, null, array, object
from

string

A JSON pointer that references the location in the target document from which to move the value. Required for the move operation.

json_patch_request

items

(contains the json_patch object)

A JSON patch object to use to apply partial updates to resources.

link

href

string

The URL of the related HATEOAS link that you can use for subsequent calls.
rel

string

The link relationship. Describes how this link relates to the previous call. For example, use a self link to show details for the current call. Use a parent_payment link to show details for the parent payment. The rel value can also be a related call, such as execute or refund.
method

string

The HTTP method required to make the related call.

merchant_preferences

id

string

The ID of the merchant preferences.

Read only.

Maximum length: 128.
setup_fee

object

The fee to set up the agreement. Default is 0.
cancel_url

string

The URL where the customer can cancel the agreement.

Maximum length: 1000.
return_url

string

The URL where the customer can approve agreement.

Maximum length: 1000.
notify_url

string

The URL where the customer is notified that the agreement was created. Read-only and reserved for future use.

Read only.

Maximum length: 1000.
max_fail_attempts

string

The maximum number of allowed failed payment attempts. Default is 0, which allows infinite failed payment attempts.
auto_bill_amount

enum
Indicates whether PayPal automatically bills the outstanding balance in the next billing cycle. The outstanding balance is the total amount of any previously failed scheduled payments. Value is:
- NO. PayPal does not automatically bill the customer the outstanding balance. Default is NO.
- YES. PayPal automatically bills the customer the outstanding balance.
Possible values: YES, NO.
initial_fail_amount_action

enum
The action if the customer's initial payment fails. Value is:
- CONTINUE. The agreement remains active and the failed payment amount is added to the outstanding balance. If auto-billing is enabled, PayPal automatically bills the outstanding balance in the next billing cycle. Default is CONTINUE.
- CANCEL PayPal creates the agreement but sets its state to pending until the initial payment clears. If the initial payment clears, the pending agreement becomes active. If the initial payment fails, the pending agreement is canceled.
Possible values: CONTINUE, CANCEL.
accepted_payment_type

string

The payment types that are accepted for this agreement. Read-only and reserved for future use.

Read only.
char_set

string

The character set for this agreement. Read-only and reserved for future use.

Read only.

money_type_with_currency_code_qualified_value

currency

string

The three-letter ISO 4217 alphabetic currency code.
value

string

The currency value. Might be an integer for currencies like JPY that are not typically fractional or a three-place decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see ISO 4217.

Maximum length: 32.

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

override_charge_model

charge_id

string

The ID of the charge model.
amount

object

The updated amount for this charge model.

payer

payment_method

enum

The payment method.

Possible values: credit_card, bank, paypal.
funding_instruments

array (contains the funding_instrument object)

Information about a customer's funding instrument.
funding_option_id

string

The ID of the customer-selected funding option for the payment. Value is OneOf funding_instruments or funding_option_id.

Read only.
payer_info

object

The customer information.

payer_information

email

string

The customer's email address.
first_name

string

The customer's first name.

Read only.
last_name

string

The customer's last name.

Read only.
payer_id

string

The PayPal-assigned ID for the customer.

Read only.
phone

string

The customer's phone number. For future use.
billing_address

object

The customer's billing address.

payment_card

id

string

The ID of the vaulted payment card.

Read only.
number

string

The card number.
type

enum

The card type.

Possible values: VISA, AMEX, SOLO, JCB, STAR, DELTA, DISCOVER, SWITCH, MAESTRO, CB_NATIONALE, CONFINOGA, COFIDIS, ELECTRON, CETELEM, CHINA_UNION_PAY, MASTERCARD.
expire_month

see description

The two-digit card expiry month.
Possible types: integer
expire_year

see description

The four-digit card expiry year.
Possible types: integer
start_month

see description

The two-digit card start month.
Possible types: integer
start_year

see description

The four-digit card start year.
Possible types: integer
cvv2

see description

The card validation code. Supported only when making a payment but not when saving a payment card for future use.
Possible types: integer
first_name

string

The card holder's first name.
last_name

string

The card holder's last name.
billing_address

object

The card holder's billing address.
external_customer_id

string

The facilitator-provided ID of the card holder. Required when storing a funding instrument or using a stored funding instrument in the PayPal vault.

Maximum length: 256.
status

enum

The status of the funding instrument.

Read only.

Possible values: EXPIRED, ACTIVE.
valid_until

string

The date and time when the card becomes unusable from the vault, in Internet date and time format. The valid_until parameter is not the same as the expiration month and year. The expiration month and year might be later than the valid_until date. For example, the card expires in November 2019 but the valid_until date is October 17th, 2019.

Read only.
links

array (contains the link object)

HATEOAS links related to this call.

Read only.

payment_card_token

payment_card_id

string

The ID of the vaulted payment card.
external_customer_id

string

The ID of the customer who owns this payment card.
last4

string

The last four digits of the card number from the vaulted card.

Read only.
type

enum

The card type.

Read only.

Possible values: VISA, AMEX, SOLO, JCB, STAR, DELTA, DISCOVER, SWITCH, MAESTRO, CB_NATIONALE, CONFINOGA, COFIDIS, ELECTRON, CETELEM, CHINA_UNION_PAY, MASTERCARD.
expire_month

see description

The expiry month from the vaulted card. Value is from 1 to 12.
Possible types: integer

Read only.
expire_year

see description

The four-digit expiry year from the vaulted card, in YYYY format.
Possible types: integer

Read only.

payment_definition

id

string

The ID of the payment definition. A payment definition defines a regular or trial payment.

Read only.

Maximum length: 128.
name

string

The payment definition name.

Maximum length: 128.
type

enum

The payment definition type.

Possible values: TRIAL, REGULAR.
frequency_interval

string

The interval at which the customer is charged. Value cannot be greater than 12 months.
frequency

enum

The frequency of the payment in this definition.

Possible values: WEEK, DAY, YEAR, MONTH.
cycles

string

The number of payment cycles in this definition. For infinite plans with a regular payment definition, set cycles to 0.
amount

object

The amount to charge at the end of each payment cycle for this definition.
charge_models

array (contains the charge_models object)

A charge model for a payment definition. A charge model defines shipping fee and tax information.

plan

id

string

The ID of the plan.

Read only.

Maximum length: 128.
name

string

The plan name.

Maximum length: 128.
description

string

The plan description.

Maximum length: 128.
type

enum

The plan type.

Possible values: FIXED, INFINITE.

Maximum length: 20.
state

enum

The status of the plan.

Read only.

Possible values: CREATED, ACTIVE, INACTIVE, DELETED.
create_time

string

The date and time when the plan was created, in Internet date and time format.

Read only.
update_time

string

The date and time when this plan was updated, in Internet date and time format.

Read only.
payment_definitions

array (contains the payment_definition object)

A definition for a regular or trial payment.
terms

array (contains the terms object)

The plan terms.

Read only.
merchant_preferences

object

The merchant preferences for this plan. Defines how much it costs to set up the agreement, the URLs where the customer can approve or can cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.
links

array (contains the link object)

HATEOAS links related to this call.

Read only.

simple_postal_address_(coarse_grained)

line1

string

The first line of the address. For example, number, street, and so on.
line2

string

Optional. The second line of the address. For example, suite, apt number, and so on.
city

string

The city name.
state

string

The two-letter code for a US state. Use the equivalent for other countries.
country_code

string

The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as is used in that country's top-level domain names. Use the C2 country code for CHINA WORLDWIDE (for CUP, bank card, and cross-border transactions).
postal_code

string

The postal code, which is the zip code or equivalent. Typically required for countries with postal codes. For countries that have postal codes or an equivalent, see Postal code.

terms

id

string

The ID of the terms.

Read only.

Maximum length: 128.
type

enum

The term type.

Possible values: MONTHLY, WEEKLY, YEARLY.
max_billing_amount

object

The maximum amount associated with this term.
occurrences

string

The number of times that money can be pulled during this term.
amount_range

object

The amount range for this term.
buyer_editable

string

Indicates whether the customer can edit the amount in this term.

Error messages

In addition to common REST API errors, the Billing Agreements API can return the following errors. Corrective action is provided where possible.

ACCOUNT_RESTRICTED

This transaction cannot be processed. Please contact PayPal Customer Service. Transaction cannot be processed. Contact PayPal Customer Service.
ADDRESS_INVALID

Provided user address is invalid. The user address is not valid.
BILL_AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE

Bill amount is greater than outstanding balance. Bill amount should be less than outstanding balance.
BUSADD_STATE_UNSUPPORTED

This transaction cannot be processed. The country listed for your business address is not currently supported. The country listed for your business address is not currently supported.
CALL_FAILED_PAYMENT

Payment is failing.
CANNOT_FIND_PROFILE_DESC

Profile description is invalid. Provide a valid agreement description.
CANNOT_MIX_CURRENCIES

Invalid currency code, all currency codes much match. Use same currency for all the amount objects.
CANT_INCREASE_OUTSTANDING_AMOUNT

Cannot increase delinquent amount. Bill outstanding amount cannot be increased.
CC_STATUS_INVALID

Profile is not active. The state of the profile is not active.
CC_TYPE_NOT_SUPPORTED

The credit card type is not supported. Use another type of credit card.
DPRP_DISABLED

DPRP is disabled for this merchant. To enable Direct Payment Recurring Payments (DPRP), enable Pro mode for your merchant sandbox account. Go to Sandbox accounts and click the Business account in the Type column. Click Profile and enable Pro features on this business sandbox account.
DUPLICATE_REQUEST_ID

The value of PayPal-Request-Id header has already been used Resend the request by using a unique PayPal-Request-Id header value.
FEATURE_DISABLED

This transaction cannot be processed. This feature is disabled.
FEATURE_NOT_AVAILABLE

Recurring payments feature is not currently available; try again later. Because the tecurring payments feature is not currently available, you must try again later.
GATEWAY_DECLINE_CVV2

This transaction cannot be processed. Please enter a valid Credit Card Verification Number. Use a valid credit card.
INTERNAL_ERROR

Internal Error. Resend the request at another time. If this error continues, contact PayPal Merchant Technical Support.
INTERNAL_SERVICE_ERROR

An internal service error has occurred. Resend the request at another time. If this error continues, contact PayPal Merchant Technical Support.
INVALID_AMOUNT

Bill amount must be greater than 0. Specify a valid amount.
INVALID_ARGS

Invalid argument; description field or custom field is empty and the status is active. Pass correct arguments in description field and make sure status is active.
INVALID_CC_NUMBER

This transaction cannot be processed. Please enter a valid credit card number and type. Enter a valid credit card number and type.
INVALID_CURRENCY

This transaction cannot be processed due to an unsupported currency. The currency specified in the transaction is not supported.
INVALID_PROFILE_ACTION

Invalid action value provided. Provide a valid action value.
INVALID_PROFILE_ID

The profile ID is invalid. Provide a valid agreement ID.
INVALID_STATUS_TO_CANCEL

Invalid profile status for suspend action; profile should be active. The agreement must be active before you can suspend it.
INVALID_STATUS_TO_REACTIVATE

The activation type is invalid. Pass a valid activation type.
INVALID_PROFILE_STATUS

The profile status must be one of (A)ctive, (C)ancelled, or e(X)pired. Enter a valid profile status.
INVALID_STATUS_TO_SUSPEND

Invalid profile status for reactivate action; profile should be suspended. To complete this action, you must first suspend the agreement.
INVALID_TOKEN

The token is missing or is invalid. Use a valid token.
MERCHANT_ACCOUNT_DENIED

Merchant account is denied.
MERCHANT_COUNTRY_NOT_SUPPORTED

The merchant country is not supported. You cannot create agreement for this country.
MISSING_CVV2

This transaction cannot be processed without a Credit Card Verification number. Enter CVV2 for the credit card.
OUTSTANDING_PAYMENT_ALREADY_SCHEDULED

Another outstanding payment is scheduled.
PAYER_ACCOUNT_DENIED

Payer's account is denied.
PAYER_COUNTRY_NOT_SUPPORTED

The payer's country is currently not supported.
PROCESSOR_DECLINE_INVALID_CC_COUNTRY

This credit card was issued from an unsupported country.
RECURRING_PAYMENT_SCHEDULED_WITHIN_24HOURS

Recurring payment scheduled within 24 hours, so we are not processing the bill outstanding amount.
REQUIRED_SCOPE_MISSING

Access token does not have required scope. Obtain user consent using the correct scope required for this type of request.
SET_BALANCE_INVALID_CURRENCY_CODE

Invalid currency for delinquent amount. Specify a valid currency in bill-balance call.
SHIPPING_ADDRESS_NOT_IN_RESIDENCE_COUNTRY

This transaction cannot be processed. The shipping country is not allowed by the buyer's country of residence. The buyer's country of residence does not allow the specified shipping country.
SHP_INVALID_COUNTRY_CODE

This transaction cannot be processed. Please enter a valid country code in the shipping address. Enter a valid country code in the shipping address.
START_DATE_INVALID_FORMAT

Subscription start date should be valid. Specify a valid start date in Internet date and time format. The start date must be greater than the current date.
STATUS_INVALID

Invalid profile status for reactivate action; profile should be suspended. Specify a valid status for agreement state change.
SUBSCRIPTION_UNMAPPED_ERROR

Some unmapped business/ internal error has occurred. To resolve this error, review the message details.
TIME_TO_UPDATE_CLOSE_TO_BILLING_DATE

The time of the update is too close to the billing date. The billing date and the update time are too close to each other.
UNAUTHORIZED_AGREEMENT_REQUEST

You don't have permission to create such agreement. Get the permission to create agreement.
USR_BILLING_AGRMNT_NOT_ACTIVE

This transaction cannot be processed due to an invalid merchant configuration. The agreement is disabled or inactive.
VALIDATION_ERROR

Invalid request - see details. Your request has a validation error.
WALLET_TOO_MANY_ATTEMPTS

You have exceeded the maximum number of payment attempts for this token. Create a token and use it to create an agreement.

name

description

start_date

agreement_details

payer

shipping_address

override_merchant_preferences

override_charge_models

plan

Sample Request

Sample Request

Sample Request

id

state

name

description

start_date

agreement_details

payer

shipping_address

override_merchant_preferences

override_charge_models

plan

links

Sample Response

Sample Response

Sample Response

agreement_id

items

Sample Request

Sample Response

agreement_id

Sample Request

id

state

name

description

start_date

agreement_details

payer

shipping_address

override_merchant_preferences

override_charge_models

plan

links

Sample Response

agreement_id

note

Sample Request

Sample Response

agreement_id

note

Sample Request

Sample Response

agreement_id

note

Sample Request

Sample Response

agreement_id

currency

value

Sample Request

Sample Response

agreement_id

note

Sample Request

Sample Response

agreement_id

start_date

end_date

Sample Request

agreement_transaction_list

Sample Response

payment_token

Sample Request

id

state

name

description

start_date

`name`

`description`

`start_date`

`agreement_details`

`payer`

`shipping_address`

`override_merchant_preferences`

`override_charge_models`

`plan`

`id`

`state`

`name`

`description`

`start_date`

`agreement_details`

`payer`

`shipping_address`

`override_merchant_preferences`

`override_charge_models`

`plan`

`links`

`agreement_id`

`items`

`agreement_id`

`id`

`state`

`name`

`description`

`start_date`

`agreement_details`

`payer`

`shipping_address`

`override_merchant_preferences`

`override_charge_models`

`plan`

`links`

`agreement_id`

`note`

`agreement_id`

`note`

`agreement_id`

`note`

`agreement_id`

`currency`

`value`

`agreement_id`

`note`

`agreement_id`

`start_date`

`end_date`

`agreement_transaction_list`

`payment_token`

`id`

`state`

`name`

`description`

`start_date`

`agreement_details`

`payer`

`shipping_address`

`override_merchant_preferences`

`override_charge_models`

`plan`

`links`

`id`

`state`

`name`

`description`

`start_date`

`agreement_details`

`payer`

`shipping_address`

`override_merchant_preferences`

`override_charge_models`

`plan`

`links`

`outstanding_balance`

`cycles_remaining`

`cycles_completed`

`next_billing_date`