Billing Agreements API

Deprecation notice: The /v1/payments/billing-agreements endpoints are deprecated. Use the /v1/billing/subscriptions endpoints instead. For details, see Subscriptions Integration.

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.

Note: The Billing Agreements API does not support the payee object.

Billing agreements (resource group)

Use the /billing-agreements resource to create, update, show details for, bill the balance for, cancel, reactivate, set the balance for, suspend, list transactions for, 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.

Request body

id
string
The PayPal-generated ID for the resource.
Maximum length: 128.
state
enum
The state of the agreement. Value is:
- Pending. The agreement awaits initial payment completion.
- Active. The agreement is active and payments are scheduled.
- Suspended. The agreement is suspended and payments are not scheduled until the agreement is reactivated.
- Cancelled. The agreement is cancelled and payments are not scheduled.
- Expired. The agreement is expired and no more payments remain to be scheduled.
Possible values: Pending,Active,Suspended,Cancelled,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 no less than 24 hours after the current date as 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 details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
shipping_address
object
The shipping address for a payment. Must be provided if it differs from the default address.
override_merchant_preferences
object
The 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. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or 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.
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 ID of the plan on which this agreement is based.
links
array (contains the link_description object)
An array of request-related HATEOAS links.

SDK samples:

Sample Request

curl -v -X POST https://api-m.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"
  },
  "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://example.com/",
    "cancel_url": "https://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 ID for the resource.
Read only.
Maximum length: 128.
state
enum
The state of the agreement. Value is:
- Pending. The agreement awaits initial payment completion.
- Active. The agreement is active and payments are scheduled.
- Suspended. The agreement is suspended and payments are not scheduled until the agreement is reactivated.
- Cancelled. The agreement is cancelled and payments are not scheduled.
- Expired. The agreement is expired and no more payments remain to be scheduled.
Read only.
Possible values: Pending,Active,Suspended,Cancelled,Expired.
Maximum length: 128.
name
string
The agreement name.
Maximum length: 128.
description
string
The agreement description.
Maximum length: 128.
start_date
string
The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as 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
The details for the customer who funds the payment. 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
The 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. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or 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.
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
The plan that can be used to create an agreement.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "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://example.com/",
      "cancel_url": "https://example.com/cancel",
      "auto_bill_amount": "YES",
      "initial_fail_amount_action": "CONTINUE"
    }
  },
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-83C745436S346813F",
      "rel": "approval_url",
      "method": "REDIRECT"
    },
    {
      "href": "https://api-m.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. The details include the description, shipping address, start date, and so on.

Note: For the PayPal payment method, you cannot update the start_date after the agreement is created.

Path parameters

agreement_id
string
required
The ID of the agreement to update.

Request body

patch_request
array (contains the patch object)
An array of JSON patch objects to apply partial updates to resources.

SDK samples:

Sample Request

curl -v -X PATCH https://api-m.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.

Path parameters

agreement_id
string
required
The ID of the agreement for which to show details.

SDK samples:

Sample Request

curl -v -X GET https://api-m.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 ID for the resource.
Read only.
Maximum length: 128.
state
enum
The state of the agreement. Value is:
- Pending. The agreement awaits initial payment completion.
- Active. The agreement is active and payments are scheduled.
- Suspended. The agreement is suspended and payments are not scheduled until the agreement is reactivated.
- Cancelled. The agreement is cancelled and payments are not scheduled.
- Expired. The agreement is expired and no payments remain to be scheduled.
Read only.
Possible values: Pending,Active,Suspended,Cancelled,Expired.
Maximum length: 128.
description
string
The agreement description.
Maximum length: 128.
start_date
string
The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as 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
The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
shipping_address
object
The shipping address for a payment. Must be provided if it differs from the default address.
override_merchant_preferences
object
The 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. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or 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.
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
The plan that can be used to create an agreement.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "id": "I-1TJ3GAGG82Y9",
  "state": "Active",
  "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": "https://example.com",
      "cancel_url": "https://example.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-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/suspend",
      "rel": "suspend",
      "method": "POST"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/re-activate",
      "rel": "re_activate",
      "method": "POST"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/cancel",
      "rel": "cancel",
      "method": "POST"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/bill-balance",
      "rel": "self",
      "method": "POST"
    },
    {
      "href": "https://api-m.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.

Path parameters

agreement_id
string
required
The ID of the agreement for which to bill the balance.

Request body

note
string
The reason for the agreement state change.
Maximum length: 128.

SDK samples:

Sample Request

curl -v -X POST https://api-m.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."
}'

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.

Path parameters

agreement_id
string
required
The ID of the agreement to cancel.

Request body

note
string
The reason for the agreement state change.
Maximum length: 128.

SDK samples:

Sample Request

curl -v -X POST https://api-m.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

Reactivate agreement

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

Reactivates 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 reactivation and the agreement amount and currency.

Path parameters

agreement_id
string
required
The ID of the agreement to reactivate.

Request body

note
string
The reason for the agreement state change.
Maximum length: 128.

SDK samples:

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/re-activate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "note": "Reactivating 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.

Path parameters

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

Request body

currency
string
required
The three-character ISO-4217 currency code that identifies the currency.
Minimum length: 3.
Maximum length: 3.
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 Currency codes - ISO 4217.
Maximum length: 32.
Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

SDK samples:

Sample Request

curl -v -X POST https://api-m.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.

Path parameters

agreement_id
string
required
The ID of the agreement to suspend.

Request body

note
string
The reason for the agreement state change.
Maximum length: 128.

SDK samples:

Sample Request

curl -v -X POST https://api-m.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.

Query parameters

start_date
string
The start date of the range of transactions to list.
end_date
string
The end date of the range of transactions to list.

Path parameters

agreement_id
string
required
The ID of the agreement for which to list transactions.

SDK samples:

Sample Request

curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/transactions?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 array of agreement transactions.

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.

Path parameters

payment_token
string
required
The ID of the agreement to execute.

SDK samples:

Sample Request

curl -v -X POST https://api-m.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 ID for the resource.
Read only.
Maximum length: 128.
state
enum
The state of the agreement. Value is:
- Pending. The agreement awaits initial payment completion.
- Active. The agreement is active and payments are scheduled.
- Suspended. The agreement is suspended and payments are not scheduled until the agreement is reactivated.
- Cancelled. The agreement is cancelled and payments are not scheduled.
- Expired. The agreement is expired and no payments remain to be scheduled.
Read only.
Possible values: Pending,Active,Suspended,Cancelled,Expired.
Maximum length: 128.
description
string
The agreement description.
Maximum length: 128.
start_date
string
The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as 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
The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
shipping_address
object
The shipping address for a payment. Must be provided if it differs from the default address.
override_merchant_preferences
object
The 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. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or 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.
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
The plan that can be used to create an agreement.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "id": "I-1TJ3GAGG82Y9",
  "state": "Active",
  "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": "https://example.com",
      "cancel_url": "https://example.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-m.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 or street.
line2
string
The second line of the address. For example, suite or apartment number.
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, China, India, Italy, Japan, Mexico, Thailand, or United States. Maximum length is 40 single-byte characters.
country_code
string
required
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)$.
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.

address_postal_code_validation

address_postal_code_validation

agreement

id
string
The PayPal-generated ID for the resource.
Read only.
Maximum length: 128.
state
enum
The state of the agreement. Value is:
- Pending. The agreement awaits initial payment completion.
- Active. The agreement is active and payments are scheduled.
- Suspended. The agreement is suspended and payments are not scheduled until the agreement is reactivated.
- Cancelled. The agreement is cancelled and payments are not scheduled.
- Expired. The agreement is expired and no payments remain to be scheduled.
Read only.
Possible values: Pending,Active,Suspended,Cancelled,Expired.
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 no less than 24 hours after the current date as 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 details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
shipping_address
object
The shipping address for a payment. Must be provided if it differs from the default address.
override_merchant_preferences
object
The 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. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or 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.
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 plan that can be used to create an agreement.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

agreement_details

outstanding_balance
object
The currency and amount of 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
object
The currency and amount of 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.
Read only.
status
enum
The current status of the transaction. Value is:
- Completed. The transaction is complete and the money has been transferred 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.
Read only.
Possible values: Completed,Partially_Refunded,Pending,Refunded,Denied.
transaction_type
string
The type of transaction. Typically, Recurring Payment.
Read only.
amount
object
required
The currency and amount of the transaction.
fee_amount
object
required
The currency and amount of the transaction fee.
net_amount
object
required
The currency and amount of 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, in Internet date and time format.
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 array of agreement transactions.

bank_account

id
string
The PayPal-generated ID for the resource.
Read only.
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.
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
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 that 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.
Read only.
update_time
string
The date and time when the bank account was last updated, in Internet date and time format.
Read only.
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.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

charge_model

id
string
The PayPal-generated ID for the resource.
Read only.
Maximum length: 128.
type
enum
required
The charge model type.
Possible values: TAX,SHIPPING.
Maximum length: 20.
amount
object
required
The currency and 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)$.

create_agreement_request

id
string
The PayPal-generated ID for the resource.
Read only.
Maximum length: 128.
state
enum
The state of the agreement. Value is:
- Pending. The agreement awaits initial payment completion.
- Active. The agreement is active and payments are scheduled.
- Suspended. The agreement is suspended and payments are not scheduled until the agreement is reactivated.
- Cancelled. The agreement is cancelled and payments are not scheduled.
- Expired. The agreement is expired and no more payments remain to be scheduled.
Read only.
Possible values: Pending,Active,Suspended,Cancelled,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 no less than 24 hours after the current date as 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 details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
shipping_address
object
The shipping address for a payment. Must be provided if it differs from the default address.
override_merchant_preferences
object
The 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. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or 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.
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 ID of the plan on which this agreement is based.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

create_agreement_response

id
string
The PayPal-generated ID for the resource.
Read only.
Maximum length: 128.
state
enum
The state of the agreement. Value is:
- Pending. The agreement awaits initial payment completion.
- Active. The agreement is active and payments are scheduled.
- Suspended. The agreement is suspended and payments are not scheduled until the agreement is reactivated.
- Cancelled. The agreement is cancelled and payments are not scheduled.
- Expired. The agreement is expired and no more payments remain to be scheduled.
Read only.
Possible values: Pending,Active,Suspended,Cancelled,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 no less than 24 hours after the current date as 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 details for the customer who funds the payment. 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
The 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. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or 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.
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 plan that can be used to create an agreement.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

credit_card

id
string
The PayPal-generated ID for the resource.
Read only.
number
string
required
The card number.
type
string
required
The card type. For example, Visa, MasterCard, and so on.
expire_month
integer
required
The two-digit card expiry month, in MM format. Value is from 01 to 12.
expire_year
integer
required
The four-digit card expiry year, in YYYY format.
cvv2
integer
The card validation code. Supported only when making a payment but not when saving a credit card for future use.
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_description object)
An array of request-related HATEOAS links.
Read only.

currency

currency
string
required
The three-character ISO-4217 currency code that identifies the currency.
Minimum length: 3.
Maximum length: 3.
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 Currency codes - ISO 4217.
Maximum length: 32.
Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

currency_code

currency_code
string
The three-character ISO-4217 currency code that identifies the currency.
Minimum length: 3.
Maximum length: 3.

error

name
string
required
The human-readable, unique name of the error.
Read only.
debug_id
string
The PayPal internal ID. Used for correlation purposes.
Read only.
message
string
required
The message that describes the error.
Read only.
information_link
string
required
The URI to detailed information related to this error for the developer.
Read only.
details
array (contains the error_details object)
An array of additional details for the error.
Read only.

error_details

field
string
required
The name of the field that caused the error.
issue
string
required
The reason for the error.

funding_instrument

credit_card
object
A credit card that can be used to fund a payment.

link_description

href
string
required
The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.
rel
string
required
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method
enum
The HTTP method required to make the related call.
Possible values: GET,POST,PUT,DELETE,HEAD,CONNECT,OPTIONS,PATCH.

merchant_preferences

id
string
The PayPal-generated ID for the resource.
Read only.
Maximum length: 128.
setup_fee
object
The currency and amount of 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.
- CANCEL. PayPal creates the agreement but sets its state to pending until the initial payment clears. When the initial payment clears, the pending agreement becomes active. If the initial payment fails, the pending agreement is cancelled.
Note: Initial payment failures will not increment the max_fail_attempt counter as initial payments are not considered regularly recurring payments.
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.

override_charge_model

charge_id
string
required
The ID of the charge model.
amount
object
required
The updated amount and currency for this charge model.

patch

`op`

enum

required

The operation.

The possible values are:

add.
Depending on the target location reference, completes one of these functions:
- The target location is an array index. Inserts a new value into the array at the specified index.
- The target location is an object parameter that does not already exist. Adds a new parameter to the object.
- The target location is an object parameter that does exist. Replaces that parameter's value.
The value parameter defines the value to add. For more information, see 4.1. add.
remove. Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.
replace. Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.
move. Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.
copy. Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.

test. Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:

Type	Considered equal if both values
strings	Contain the same number of Unicode characters and their code points are byte-by-byte equal.
numbers	Are numerically equal.
arrays	Contain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objects	Contain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (`false`, `true`, and `null`)	Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.

For more information, see 4.6. test.

path
string
The JSON Pointer to the target document location 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
The JSON Pointer to the target document location 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.
Read only.
payer_info
object
The payer information.

payer_info

email
string
The payer's email address.
first_name
string
The payer's first name.
Read only.
last_name
string
The payer's last name.
Read only.
payer_id
string
The PayPal-assigned ID for the payer.
Read only.
shipping_address
object
The shipping address for a payment. Must be provided if it differs from the default address.
billing_address
object
The payer's billing address.

payment_definition

id
string
The PayPal-generated ID for the resource.
Read only.
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.
Note: You can specify the frequency value in any case. For example, you can specify the frequency of the payment as WEEK, Week, or week.
The possible values are:
- WEEK. The payment is weekly.
- DAY. The payment is daily.
- YEAR. The payment is yearly.
- MONTH. The payment is monthly.
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 currency and amount to charge at the end of each payment cycle for this definition.
charge_models
array (contains the charge_model object)
An array of shipping fee and tax information for this definition.

plan

id
string
The PayPal-generated ID for the resource.
Read only.
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.
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)
An array of payment definitions for this plan.
terms
array (contains the terms object)
An array of terms for this plan.
Read only.
merchant_preferences
object
The 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. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or 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.
currency_code
string
The currency code for the plan.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

plan

id
string
The ID of the plan.
Maximum length: 128.

shipping_address

recipient_name
string
The name of the recipient at this address.
default_address
boolean
The default shipping address of the payer.

line1
string
required
The first line of the address. For example, number or street.
line2
string
The second line of the address. For example, suite or apartment number.
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, China, India, Italy, Japan, Mexico, Thailand, or United States. Maximum length is 40 single-byte characters.
country_code
string
required
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)$.
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.

terms

id
string
The PayPal-generated ID for the resource.
Read only.
Maximum length: 128.
type
enum
required
The term type.
The possible values are:
- MONTHLY. The term is monthly.
- WEEKLY. The term is weekly.
- YEARLY. The term is yearly.
max_billing_amount
object
required
The currency and amount of the maximum billing 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.

Error messages

In addition to the 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.
BA_TOKEN
Invalid request - see details.
BILL_AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE
The billed amount should be less than the outstanding balance.
BUSADD_STATE_UNSUPPORTED
This transaction cannot be processed.
CALL_FAILED_PAYMENT
Payment is failing.
CANNOT_FIND_PROFILE_DESC
The profile description is not valid.
CANNOT_MIX_CURRENCIES
The currency code is not valid. All currency codes much match.
CANT_INCREASE_OUTSTANDING_AMOUNT
Cannot increase the delinquent amount.
CC_STATUS_INVALID
Profile is not active.
CC_TYPE_NOT_SUPPORTED
The credit card type is not supported.
DPRP_DISABLED
DPRP is disabled for this merchant.
DUPLICATE_REQUEST_ID
The value of PayPal-Request-Id header has already been used.
EXECUTE_AGREEMENT_BUYER_NOT_ACCEPTED
Business error.
EXECUTE_AGREEMENT_DOES_NOT_OWN_TOKEN
Business error.
FEATURE_DISABLED
This transaction cannot be processed.
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.
INTERNAL_SERVICE_ERROR
An internal service error has occurred.
INVALID_AMOUNT
The bill amount must be greater than 0.
INVALID_ARGS
Invalid argument. The description field or custom field is empty and 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_ID_PASSED
Business error.
INVALID_PROFILE_ACTION
The action value is not valid.
INVALID_PROFILE_ID
The profile ID is not valid.
INVALID_PROFILE_STATUS
The profile status must be one of (A)ctive, (C)ancelled, or e(X)pired.
INVALID_SECURITY_CTX
Business error.
INVALID_STATUS_TO_CANCEL
The status is not valid for the suspend action. The profile must be active.
INVALID_STATUS_TO_REACTIVATE
The activation type is not valid.
INVALID_STATUS_TO_SUSPEND
Invalid profile status for reactivate action. Profile must be suspended.
INVALID_TOKEN
The token is missing or is invalid.
MALFORMED_REQUEST
The request JSON is not well formed.
MERCHANT_ACCOUNT_DENIED
Merchant account is denied.
MERCHANT_COUNTRY_NOT_SUPPORTED
The merchant country is not supported.
MERCHANT_ID_NOT_AUTHORIZED
Business error.
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.
PAYMENT_METHOD
Invalid request - see details.
PLAN_TYPE
Invalid request - see details.
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.
REFUSED_CHANNEL_INITIATED_BILLING_NOT_ENABLED
Authorization error.
REFUSED_MARK_REF_TXN_NOT_ENABLED
Authorization error.
RT_AGREEMENT_ALREADY_CANCELED
Business error.
RT_INVALID_AGREEMENT_ID
Business error.
SET_BALANCE_INVALID_CURRENCY_CODE
Invalid currency for delinquent amount.
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.
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.
TOKEN_NOT_FOUND
Internal error.
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.
WALLET_TOO_MANY_ATTEMPTS
You have exceeded the maximum number of payment attempts for this token.

PayPal Commerce Platform for Business

PayPal Commerce Platform for Marketplaces and Platforms

PayPal Commerce Platform for Enterprise

Docs Catalog

Reference

Developer Tools

Regional Codes

id

state

name

description

start_date

agreement_details

payer

shipping_address

override_merchant_preferences

override_charge_models

plan

links

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

patch_request

Sample Request

Sample Response

agreement_id

Sample Request

id

state

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

start_date

end_date

agreement_id

Sample Request

agreement_transaction_list

Sample Response

payment_token

Sample Request

`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`

`agreement_id`

`patch_request`

`agreement_id`

`id`

`state`

`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`

`start_date`

`end_date`

`agreement_id`

`agreement_transaction_list`

`payment_token`

`id`

`state`

`description`

`start_date`

`agreement_details`

`payer`

`shipping_address`

`override_merchant_preferences`

`override_charge_models`

`plan`

`links`

`line1`

`line2`

`city`

`state`

`country_code`

`postal_code`

`address_postal_code_validation`

`id`

`state`

`description`

`start_date`

`agreement_details`

`payer`