Billing Agreements API

Use billing plans and billing agreements to create an agreement for a recurring PayPal or debit card 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.
Important: The use of the PayPal REST /payments APIs to accept credit card payments is restricted. Instead, you can accept credit card payments with Braintree Direct.

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.

Parameters

  • agreement

    body object

    A billing agreement.
SDK samples: C#, Node, 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": "payer@example.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": "https://www.example.com/return",
  "cancel_url": "https://www.example.com/cancel",
  "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"
    }
  }
  ]
}'

Response

A successful request returns the HTTP 201 Created status code and a JSON response body that shows billing agreement details including a billing agreement id and redirect links to get the buyer's approval.
  • id

    string

    The PayPal-generated agreement ID.

    Maximum length: 128.

  • state

    enum

    The state of the agreement. Value is:
    • Pending. The agreement is awaiting initial payment completion.
    • Active. The agreement is active and payments will be scheduled.
    • Suspended. The agreement is suspended and payments will not be scheduled until the agreement is reactivated.
    • Canceled. The agreement is canceled and payments will not be scheduled.
    • Expired. The agreement is expired and no more payments remain to be scheduled.

    Possible values: Pending, Active, Suspended, Canceled, Expired.

    Maximum length: 128.

  • name

    string

    required

    The agreement name.

    Maximum length: 128.

  • description

    string

    required

    The agreement description.

    Maximum length: 128.

  • start_date

    string

    required

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

    The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time 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 and time for an account in the Berlin time zone (UTC + 1) to 2017-01-02T00:00:00. When the API returns this date and time 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 and time 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)

    An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan.
  • plan

    object

    required

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

    array (contains the link_description object)

    An array of request-related HATEOAS links.

Sample Response

{
  "id": "I-1TJ3GAGG82Y9",
  "name": "Override Agreement",
  "description": "Agreement that overrides merchant preferences and charge models",
  "payer": {
    "payment_method": "paypal",
    "payer_info": {
      "email": "payer@example.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": "https://www.example.com/return",
      "cancel_url": "https://www.example.com/cancel",
      "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"
}

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.

Parameters

  • agreement_id

    path string

    required

    The ID of the agreement to update.
  • patch_request

    body object

    An array of JSON patch objects to apply partial updates to resources.
SDK samples: Node, 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

{}

Show agreement details

GET /v1/payments/billing-agreements/{agreement_id}
Shows details for a billing agreement, by ID.

Parameters

  • agreement_id

    path string

    required

    The ID of the agreement for which to show details.
SDK samples: C#, Node, 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" \
-d '{}'

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.

    Maximum length: 128.

  • state

    enum

    The state of the agreement. Value is:
    • Pending. The agreement is awaiting initial payment completion.
    • Active. The agreement is active and payments will be scheduled.
    • Suspended. The agreement is suspended and payments will not be scheduled until the agreement is reactivated.
    • Canceled. The agreement is canceled and payments will not be scheduled.
    • Expired. The agreement is expired and no more payments remain to be scheduled.

    Possible values: Pending, Active, Suspended, Canceled, Expired.

    Maximum length: 128.

  • name

    string

    required

    The agreement name.

    Maximum length: 128.

  • description

    string

    required

    The agreement description.

    Maximum length: 128.

  • start_date

    string

    required

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

    The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time 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 and time for an account in the Berlin time zone (UTC + 1) to 2017-01-02T00:00:00. When the API returns this date and time 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 and time 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)

    An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan.
  • plan

    object

    required

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

    array (contains the link_description object)

    An array of request-related HATEOAS links.

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.

Parameters

  • agreement_id

    path string

    required

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

    body object

    A description of the current state of the agreement.
SDK samples: Node, 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.

Parameters

  • agreement_id

    path string

    required

    The ID of the agreement to cancel.
  • agreement_state_descriptor

    body object

    A description of the current state of the agreement.
SDK samples: Node, 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.

Parameters

  • agreement_id

    path string

    required

    The ID of the agreement to re-activate.
  • agreement_state_descriptor

    body object

    A description of the current state of the agreement.
SDK samples: Node, 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.

Parameters

  • agreement_id

    path string

    required

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

    body object

    A type for all financial value-related fields. For example, balance, payment due, and so on.
SDK samples: Node, 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.

Parameters

  • agreement_id

    path string

    required

    The ID of the agreement to suspend.
  • agreement_state_descriptor

    body object

    A description of the current state of the agreement.
SDK samples: Node, 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.

Parameters

  • agreement_id

    path string

    required

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

    query string

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

    query string

    The end date of the range of transactions to list.
SDK samples: C#, Node, 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" \
-d '{}'

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 array of agreement transaction objects.

Sample Response

{
  "agreement_transaction_list": [
    {
      "transaction_id": "I-V8SSE9WLJGY6",
      "status": "Completed",
      "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": "Denied",
      "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": "Pending",
      "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": "Denied",
      "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.

Parameters

  • payment_token

    path string

    required

    The ID of the agreement to execute.
SDK samples: C#, Node, 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" \
-d '{}'

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.

    Maximum length: 128.

  • state

    enum

    The state of the agreement. Value is:
    • Pending. The agreement is awaiting initial payment completion.
    • Active. The agreement is active and payments will be scheduled.
    • Suspended. The agreement is suspended and payments will not be scheduled until the agreement is reactivated.
    • Canceled. The agreement is canceled and payments will not be scheduled.
    • Expired. The agreement is expired and no more payments remain to be scheduled.

    Possible values: Pending, Active, Suspended, Canceled, Expired.

    Maximum length: 128.

  • name

    string

    required

    The agreement name.

    Maximum length: 128.

  • description

    string

    required

    The agreement description.

    Maximum length: 128.

  • start_date

    string

    required

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

    The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time 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 and time for an account in the Berlin time zone (UTC + 1) to 2017-01-02T00:00:00. When the API returns this date and time 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 and time 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)

    An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan.
  • plan

    object

    required

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

    array (contains the link_description object)

    An array of request-related HATEOAS links.

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

address

  • line1

    string

    required

    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, apartment number, and so on.
  • city

    string

    required

    The city name.
  • state

    string

    The code for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: Argentina, Brazil, Canada, India, Italy, Japan, Mexico, Thailand, or United States. Maximum length is 40 single-byte characters.
  • country_code

    object

    required

    A simple postal address with coarse-grained fields. Do not use for an international address. Use for backward compatibility only. Does not contain phone.
  • postal_code

    string

    The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See Postal code.

agreement

  • id

    string

    The PayPal-generated agreement ID.

    Maximum length: 128.

  • state

    enum

    The state of the agreement. Value is:
    • Pending. The agreement is awaiting initial payment completion.
    • Active. The agreement is active and payments will be scheduled.
    • Suspended. The agreement is suspended and payments will not be scheduled until the agreement is reactivated.
    • Canceled. The agreement is canceled and payments will not be scheduled.
    • Expired. The agreement is expired and no more payments remain to be scheduled.

    Possible values: Pending, Active, Suspended, Canceled, Expired.

    Maximum length: 128.

  • name

    string

    required

    The agreement name.

    Maximum length: 128.

  • description

    string

    required

    The agreement description.

    Maximum length: 128.

  • start_date

    string

    required

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

    The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time 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 and time for an account in the Berlin time zone (UTC + 1) to 2017-01-02T00:00:00. When the API returns this date and time 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 and time 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)

    An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan.
  • plan

    object

    required

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

    array (contains the link_description object)

    An array of request-related HATEOAS links.

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 and time for this agreement, in Internet date and time format. For example, 2017-01-23T08:00:00Z.
  • last_payment_date

    string

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

    string

    The last payment amount for this agreement.
  • final_payment_date

    string

    The final payment date and time 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.
  • status

    enum

    The current status of the transaction. Value is:
    • Completed. The transaction is complete and the money has been transfered to the payee.
    • Partially_Refunded. A part of the transaction amount has been refunded to the payer.
    • Pending. The transaction is pending settlement.
    • Refunded. The transaction amount has been refunded to the payer.
    • Denied. The transaction has been denied.

    Possible values: Completed, Partially_Refunded, Pending, Refunded, Denied.

  • transaction_type

    string

    The type of transaction. Typically, Recurring Payment.
  • amount

    object

    required

    The transaction amount.
  • fee_amount

    object

    required

    The transaction fee.
  • net_amount

    object

    required

    The transaction net amount.
  • payer_email

    string

    The email ID of the customer.
  • payer_name

    string

    The business name of the customer.
  • time_stamp

    string

    The date and time when the transaction occurred, in Internet date and time format.
  • time_zone

    string

    The time zone of the update_time field.

agreement_transactions

  • agreement_transaction_list

    array (contains the agreement_transaction object)

    An array of agreement transaction objects.

bank-account

  • id

    string

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

    Maximum length: 128.

  • account_number

    string

    required

    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

    required

    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, in Internet date and time format. 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.

    Possible values: ACTIVE, INACTIVE, DELETED.

  • confirmation_status

    enum

    The confirmation status of a bank account.

    Possible values: UNCONFIRMED, CONFIRMED.

  • payer_id

    string

    Deprecated. Instead, use the external_customer_id parameter.
  • external_customer_id

    string

    The 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

    The 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, in Internet date and time format.
  • update_time

    string

    The date and time when the bank account was last updated, in Internet date and time format.
  • valid_until

    string

    The date and time after which the bank account can no longer be used to fund a payment, in Internet date and time format.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

charge_models

  • id

    string

    The ID of the charge model.

    Maximum length: 128.

  • type

    enum

    required

    The charge model type.

    Possible values: TAX, SHIPPING.

    Maximum length: 20.

  • amount

    object

    required

    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 used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

    Minimum length: 2.

    Maximum length: 2.

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

currency

  • currency

    object

    required

    A type for all financial value-related fields. For example, balance, payment due, and so on.
  • 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]+))$.

currency_code

error

  • name

    string

    required

    A human readable, unique name of the error.
  • debug_id

    string

    The PayPal internal ID. Used for correlation purposes.
  • message

    string

    required

    A message that describes the error.
  • information_link

    string

    required

    The URI to detailed information related to this error for the developer.
  • details

    array (contains the error_details object)

    An array of additional details for the error.

error_details

  • field

    string

    required

    The name of the field that caused the error.
  • issue

    string

    required

    The reason for the error.

merchant_preferences

  • id

    string

    The ID of the merchant preferences.

    Maximum length: 128.

  • setup_fee

    object

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

    string

    required

    The URL to which the customer is redirected if they cancel the agreement.

    Maximum length: 1000.

  • return_url

    string

    required

    The URL to which the customer is redirected if they accept the agreement.

    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.
    • char_set

      string

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

    override_charge_model

    • charge_id

      string

      required

      The ID of the charge model.
    • amount

      object

      required

      The updated amount for this charge model.

    patch

    • op

      enum

      required

      The operation to complete.

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

    • path

      string

      A JSON pointer to a location in the target document at which to complete the operation.
    • value

      number,integer,string,boolean,null,array,object

      The value to apply. The remove operation does not require a value.
    • from

      string

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

    patch_request

    • patch_request

      array (contains the patch object)

      An array of JSON patch objects to apply partial updates to resources.

    payer

    • payment_method

      enum

      required

      The payment method.

      Possible values: bank, paypal.

    • funding_instruments

      array (contains the funding_instrument object)

      An array of funding instruments.
    • funding_option_id

      string

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

      object

      The customer information.

    payer_info

    • email

      string

      The customer's email address.
    • first_name

      string

      The customer's first name.
    • last_name

      string

      The customer's last name.
    • payer_id

      string

      The PayPal-assigned ID for the customer.
    • billing_address

      object

      The customer's billing address.

    payment_definition

    • id

      string

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

      Maximum length: 128.

    • name

      string

      required

      The payment definition name.

      Maximum length: 128.

    • type

      enum

      required

      The payment definition type.

      Possible values: TRIAL, REGULAR.

    • frequency_interval

      string

      required

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

      enum

      required

      The frequency of the payment in this definition.

      Possible values: WEEK, DAY, YEAR, MONTH.

    • cycles

      string

      required

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

      object

      required

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

      array (contains the charge_models object)

      An array of shipping fee and tax information for this definition.

    plan

    • id

      string

      The ID of the plan.

      Maximum length: 128.

    • name

      string

      required

      The plan name.

      Maximum length: 128.

    • description

      string

      required

      The plan description.

      Maximum length: 128.

    • type

      enum

      required

      The plan type.

      Possible values: FIXED, INFINITE.

      Maximum length: 20.

    • state

      enum

      The status of the plan.

      Possible values: CREATED, ACTIVE, INACTIVE, DELETED.

    • create_time

      string

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

      string

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

      array (contains the payment_definition object)

      An array of payment definitions for this plan.
    • terms

      array (contains the terms object)

      An array of terms for this plan.
    • 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_description object)

      An array of request-related HATEOAS links.

    terms

    • id

      string

      The ID of the terms.

      Maximum length: 128.

    • type

      enum

      required

      The term type.

      Possible values: MONTHLY, WEEKLY, YEARLY.

    • max_billing_amount

      object

      required

      The maximum amount associated with this term.
    • occurrences

      string

      required

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

      object

      required

      The amount range for this term.
    • buyer_editable

      string

      required

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

    Additional API information

    Error messages

    In addition to common HTTP status codes that the REST APIs return, the Billing Agreements API can return the following errors.

    • ACCOUNT_RESTRICTED

      This transaction cannot be processed. Contact PayPal Customer Service.

    • ADDRESS_INVALID

      The user address is not valid.

    • BILL_AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE

      The billed amount should be less than the outstanding balance.

    • BUSADD_STATE_UNSUPPORTED

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

    • CALL_FAILED_PAYMENT

      Payment is failing.

    • CANNOT_FIND_PROFILE_DESC

      The profile description is not valid. Provide a valid agreement description.

    • CANNOT_MIX_CURRENCIES

      The currency code is not valid. All currency codes much match. Use same currency code for all amount objects.

    • CANT_INCREASE_OUTSTANDING_AMOUNT

      Cannot increase the delinquent amount. You cannot increase the outstanding amount for the bill.

    • 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. Use a unique PayPal-Request-Id header value to resend the request.

    • FEATURE_DISABLED

      This transaction cannot be processed. This feature is disabled.

    • FEATURE_NOT_AVAILABLE

      Because the recurring payments feature is not currently available, you must try again later.

    • GATEWAY_DECLINE_CVV2

      This transaction cannot be processed. Enter a valid credit card verification number.

    • 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

      The bill amount must be greater than 0. Specify a valid amount.

    • INVALID_ARGS

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

    • INVALID_CC_NUMBER

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

    • INVALID_CURRENCY

      This transaction cannot be processed due to an unsupported currency.

    • INVALID_PROFILE_ACTION

      The action value is not valid.

    • INVALID_PROFILE_ID

      The profile ID is not valid.

    • INVALID_STATUS_TO_CANCEL

      The status is not valid for the suspend action. The profile must be active. The agreement must be active before you can suspend it.

    • INVALID_STATUS_TO_REACTIVATE

      The activation type is not valid. 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 must 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.

    • MALFORMED_REQUEST

      The request JSON is not well formed. Review the JSON request.

    • MERCHANT_ACCOUNT_DENIED

      Merchant account is denied.

    • MERCHANT_COUNTRY_NOT_SUPPORTED

      The merchant country is not supported.

    • MISSING_CVV2

      This transaction cannot be processed without a credit card verification number.

    • OUTSTANDING_PAYMENT_ALREADY_SCHEDULED

      Another outstanding payment is scheduled.

    • PAYER_ACCOUNT_DENIED

      The 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

      The recurring payment was scheduled within 24 hours, so the bill outstanding amount cannot be processed.

    • REQUIRED_SCOPE_MISSING

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

    • SET_BALANCE_INVALID_CURRENCY_CODE

      Invalid currency for delinquent amount. Specify a valid currency in the 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.

    • SHP_INVALID_COUNTRY_CODE

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

    • START_DATE_INVALID_FORMAT

      The subscription start date must 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

      The profile status is not valid for the reactivate action. The status must be active.

    • SUBSCRIPTION_UNMAPPED_ERROR

      An internal error occurred.

    • TIME_TO_UPDATE_CLOSE_TO_BILLING_DATE

      The time of the update is too close to the billing date.

    • UNAUTHORIZED_AGREEMENT_REQUEST

      You do not have permission to create this agreement.

    • USR_BILLING_AGRMNT_NOT_ACTIVE

      This transaction cannot be processed due to an invalid merchant configuration.

    • 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.