Agreement

The billing agreement information.

stateenumOptional

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.

Length0 <= length <= 128Value in"Pending" | "Active" | "Suspended" | "Cancelled" | "Expired"

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

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

9 properties

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.

linksobject<link_description>[]Optional

An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).

shipping_addressobject<shipping_address>Optional

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

The billing agreement information.

stateenumOptional

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.

Length0 <= length <= 128Value in"Pending" | "Active" | "Suspended" | "Cancelled" | "Expired"

descriptionstringRequired

The agreement description.

Length0 <= length <= 128

start_datestringRequired

Formatdate-time

override_merchant_preferencesobject<merchant_preferences>Optional

merchant_preferences properties

9 properties

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

linksobject<link_description>[]Optional

An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).

shipping_addressobject<shipping_address>Optional

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

Agreement

agreement_details properties

currency properties

currency properties

payer properties

funding_instrument properties

credit_card properties

link_description properties

address properties

payer_info properties

shipping_address properties

address properties

merchant_preferences properties

currency properties

override_charge_model properties

currency properties

plan properties

payment_definition properties

charge_models properties

currency properties

currency properties

terms properties

currency properties

currency properties

merchant_preferences properties

currency properties

link_description properties

link_description properties

shipping_address properties

Back to top

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

Agreement

agreement_details properties

currency properties

currency properties

payer properties

funding_instrument properties

credit_card properties

link_description properties

address properties

payer_info properties

shipping_address properties

address properties

merchant_preferences properties

currency properties

override_charge_model properties

currency properties

plan properties

payment_definition properties

charge_models properties

currency properties

currency properties

terms properties

currency properties

currency properties

merchant_preferences properties

currency properties

link_description properties

link_description properties

shipping_address properties

Back to top

On this page