Create agreement

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.

Authorization

AuthorizationBearer <token>

FlowClient CredentialsToken URLhttps://api-m.sandbox.paypal.com/v1/oauth2/tokenInheader

Scopes

Create and Manage a billing-agreementhttps://uri.paypal.com/services/subscriptions

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

namestringRequired

The agreement name.

Length0 <= length <= 128

descriptionstringRequired

The agreement description.

Length0 <= length <= 128

start_datestringRequired

The date and time when this agreement begins, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). 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.

Formatdate-time

agreement_detailsobject<agreement_details>Optional

The agreement details.

agreement_details properties

8 properties

cycles_remainingstringOptional

The number of payment cycles remaining for this agreement.

cycles_completedstringOptional

The number of payment cycles completed for this agreement.

next_billing_datestringOptional

The next billing date and time for this agreement, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, `2017-01-23T08:00:00Z`.

last_payment_datestringOptional

The last payment date and time for this agreement, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, `2016-12-23T08:00:00Z`.

final_payment_datestringOptional

The final payment date and time for this agreement, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, `2017-09-23T08:00:00Z`.

failed_payment_countstringOptional

The total number of failed payments for this agreement.

outstanding_balanceobject<currency>Optional

The currency and amount of the outstanding balance for this agreement.

last_payment_amountobject<currency>Optional

The currency and amount of the last payment amount for this agreement.

payerobject<payer>Required

The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.

override_merchant_preferencesobject<merchant_preferences>Optional

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.

merchant_preferences properties

6 properties

cancel_urlstringRequired

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

FormaturiLength0 <= length <= 1000

return_urlstringRequired

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

FormaturiLength0 <= length <= 1000

max_fail_attemptsstringOptional

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

auto_bill_amountenumOptional

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.

Value in"YES" | "NO"

initial_fail_amount_actionenumOptional

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.

Default"CONTINUE"Value in"CONTINUE" | "CANCEL"

setup_feeobject<currency>Optional

The currency and amount for a transaction.

override_charge_modelsobject<override_charge_model>[]Optional

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.

planobject<plan>Required

The ID of the plan on which this agreement is based.

shipping_addressobject<shipping_address>Optional

The shipping address for a payment. Must be provided if it differs from the default address.

Response Body

`application/json`

curl -X POST "https://example.com/billing-agreements" \  -H "Content-Type: application/json" \  -d '{    "name": "Direct Payment Recurring Profile",    "description": "Credit card payment",    "start_date": "2016-12-23T08:00:00Z",    "plan": {      "id": "P-2PL786081D358645F6NWEKFQ"    },    "payer": {      "payment_method": "credit_card",      "payer_info": {        "email": "[email protected]"      },      "funding_instruments": [        {          "credit_card": {            "type": "visa",            "number": "4417119664863864",            "expire_month": 12,            "expire_year": 2021,            "cvv2": 111,            "billing_address": {              "line1": "065769 Holcomb Bridge Road #141",              "line2": "5713 E Dimond Boulevard #B9",              "city": "Wichita",              "state": "KS",              "postal_code": "67202",              "country_code": "US"            }          }        }      ]    }  }'

{  "id": "string",  "state": "Pending",  "name": "string",  "description": "string",  "start_date": "2019-08-24T14:15:22Z",  "agreement_details": {    "cycles_remaining": "string",    "cycles_completed": "string",    "next_billing_date": "string",    "last_payment_date": "string",    "final_payment_date": "string",    "failed_payment_count": "string",    "outstanding_balance": {      "value": "string",      "currency": {}    },    "last_payment_amount": {      "value": "string",      "currency": {}    }  },  "payer": {    "payment_method": "bank",    "funding_instruments": [      {        "credit_card": {          "id": "string",          "number": "string",          "type": "string",          "expire_month": 0,          "expire_year": 0,          "cvv2": 0,          "first_name": "string",          "last_name": "string",          "external_customer_id": "string",          "state": "expired",          "valid_until": "string",          "links": [            {              "href": "string",              "rel": "string",              "method": "GET"            }          ],          "billing_address": {            "line1": "string",            "line2": "string",            "city": "string",            "state": "string",            "country_code": "st",            "postal_code": "string"          }        }      }    ],    "funding_option_id": "string",    "payer_info": {      "email": "[email protected]",      "first_name": "string",      "last_name": "string",      "payer_id": "string",      "shipping_address": {        "recipient_name": "string",        "default_address": true,        "line1": "string",        "line2": "string",        "city": "string",        "state": "string",        "country_code": "st",        "postal_code": "string"      },      "billing_address": {        "line1": "string",        "line2": "string",        "city": "string",        "state": "string",        "country_code": "st",        "postal_code": "string"      }    }  },  "override_merchant_preferences": {    "id": "string",    "cancel_url": "http://example.com",    "return_url": "http://example.com",    "max_fail_attempts": "string",    "auto_bill_amount": "YES",    "initial_fail_amount_action": "CONTINUE",    "accepted_payment_type": "string",    "char_set": "string",    "setup_fee": {      "value": "string",      "currency": {}    }  },  "override_charge_models": [    {      "charge_id": "string",      "amount": {        "value": "string",        "currency": {}      }    }  ],  "plan": {    "id": "string",    "name": "string",    "description": "string",    "type": "FIXED",    "state": "CREATED",    "create_time": "string",    "update_time": "string",    "payment_definitions": [      {        "id": "string",        "name": "string",        "type": "TRIAL",        "frequency_interval": "string",        "frequency": "string",        "cycles": "string",        "charge_models": [          {            "id": "string",            "type": "TAX",            "amount": {              "value": "string",              "currency": {}            }          }        ],        "amount": {          "value": "string",          "currency": {}        }      }    ],    "terms": [      {        "id": "string",        "type": "string",        "occurrences": "string",        "buyer_editable": "string",        "max_billing_amount": {          "value": "string",          "currency": {}        },        "amount_range": {          "value": "string",          "currency": {}        }      }    ],    "merchant_preferences": {      "id": "string",      "cancel_url": "http://example.com",      "return_url": "http://example.com",      "max_fail_attempts": "string",      "auto_bill_amount": "YES",      "initial_fail_amount_action": "CONTINUE",      "accepted_payment_type": "string",      "char_set": "string",      "setup_fee": {        "value": "string",        "currency": {}      }    },    "links": [      {        "href": "string",        "rel": "string",        "method": "GET"      }    ],    "currency_code": {}  },  "links": [    {      "href": "string",      "rel": "string",      "method": "GET"    }  ],  "shipping_address": {    "line1": "string",    "line2": "string",    "city": "string",    "state": "string",    "country_code": "st",    "postal_code": "string"  }}

curl -X POST "https://example.com/billing-agreements" \ -H "Content-Type: application/json" \ -d '{ "name": "Direct Payment Recurring Profile", "description": "Credit card payment", "start_date": "2016-12-23T08:00:00Z", "plan": { "id": "P-2PL786081D358645F6NWEKFQ" }, "payer": { "payment_method": "credit_card", "payer_info": { "email": "[email protected]" }, "funding_instruments": [ { "credit_card": { "type": "visa", "number": "4417119664863864", "expire_month": 12, "expire_year": 2021, "cvv2": 111, "billing_address": { "line1": "065769 Holcomb Bridge Road #141", "line2": "5713 E Dimond Boulevard #B9", "city": "Wichita", "state": "KS", "postal_code": "67202", "country_code": "US" } } } ] } }'

{ "id": "string", "state": "Pending", "name": "string", "description": "string", "start_date": "2019-08-24T14:15:22Z", "agreement_details": { "cycles_remaining": "string", "cycles_completed": "string", "next_billing_date": "string", "last_payment_date": "string", "final_payment_date": "string", "failed_payment_count": "string", "outstanding_balance": { "value": "string", "currency": {} }, "last_payment_amount": { "value": "string", "currency": {} } }, "payer": { "payment_method": "bank", "funding_instruments": [ { "credit_card": { "id": "string", "number": "string", "type": "string", "expire_month": 0, "expire_year": 0, "cvv2": 0, "first_name": "string", "last_name": "string", "external_customer_id": "string", "state": "expired", "valid_until": "string", "links": [ { "href": "string", "rel": "string", "method": "GET" } ], "billing_address": { "line1": "string", "line2": "string", "city": "string", "state": "string", "country_code": "st", "postal_code": "string" } } } ], "funding_option_id": "string", "payer_info": { "email": "[email protected]", "first_name": "string", "last_name": "string", "payer_id": "string", "shipping_address": { "recipient_name": "string", "default_address": true, "line1": "string", "line2": "string", "city": "string", "state": "string", "country_code": "st", "postal_code": "string" }, "billing_address": { "line1": "string", "line2": "string", "city": "string", "state": "string", "country_code": "st", "postal_code": "string" } } }, "override_merchant_preferences": { "id": "string", "cancel_url": "http://example.com", "return_url": "http://example.com", "max_fail_attempts": "string", "auto_bill_amount": "YES", "initial_fail_amount_action": "CONTINUE", "accepted_payment_type": "string", "char_set": "string", "setup_fee": { "value": "string", "currency": {} } }, "override_charge_models": [ { "charge_id": "string", "amount": { "value": "string", "currency": {} } } ], "plan": { "id": "string", "name": "string", "description": "string", "type": "FIXED", "state": "CREATED", "create_time": "string", "update_time": "string", "payment_definitions": [ { "id": "string", "name": "string", "type": "TRIAL", "frequency_interval": "string", "frequency": "string", "cycles": "string", "charge_models": [ { "id": "string", "type": "TAX", "amount": { "value": "string", "currency": {} } } ], "amount": { "value": "string", "currency": {} } } ], "terms": [ { "id": "string", "type": "string", "occurrences": "string", "buyer_editable": "string", "max_billing_amount": { "value": "string", "currency": {} }, "amount_range": { "value": "string", "currency": {} } } ], "merchant_preferences": { "id": "string", "cancel_url": "http://example.com", "return_url": "http://example.com", "max_fail_attempts": "string", "auto_bill_amount": "YES", "initial_fail_amount_action": "CONTINUE", "accepted_payment_type": "string", "char_set": "string", "setup_fee": { "value": "string", "currency": {} } }, "links": [ { "href": "string", "rel": "string", "method": "GET" } ], "currency_code": {} }, "links": [ { "href": "string", "rel": "string", "method": "GET" } ], "shipping_address": { "line1": "string", "line2": "string", "city": "string", "state": "string", "country_code": "st", "postal_code": "string" }}

Authorization

Request Body

agreement_details properties

currency properties

currency properties

payer properties

funding_instrument properties

credit_card properties

address properties

payer_info properties

shipping_address properties

address properties

merchant_preferences properties

currency properties

override_charge_model properties

currency properties

plan properties

shipping_address properties

Response Body

201application/json

defaultapplication/json

On this page

On this page

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Create agreement

Authorization

Request Body

agreement_details properties

currency properties

currency properties

payer properties

funding_instrument properties

credit_card properties

address properties

payer_info properties

shipping_address properties

address properties

merchant_preferences properties

currency properties

override_charge_model properties

currency properties

plan properties

shipping_address properties

Response Body

201application/json

defaultapplication/json

On this page

On this page

`application/json`

`application/json`

`application/json`

`application/json`