Create subscription

Creates a subscription.

Authorization

AuthorizationBearer <token>

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

Scopes

Manage plan & subscriptionhttps://uri.paypal.com/services/subscriptions

Header Parameters

Content-TypestringRequired

The media type. Required for operations with a request body. The value is `application/`, where the `format` is `json`.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

plan_idstringRequired

The ID of the plan.

Match^P-[A-Z0-9]*$Length26 <= length <= 26

start_timestring<date_time>Optional

The date and time when the subscription started, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).

Default"Current time"Match^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$Formatppaas_date_time_v3Length20 <= length <= 64

quantitystringOptional

The quantity of the product in the subscription.

Match^([0-9]+|([0-9]+)?[.][0-9]+)$Length1 <= length <= 32

shipping_amountobject<money>Optional

The shipping charges.

subscriberobject<subscriber_request>Optional

The customer who approves and pays for the order. The customer is also known as the payer.

Formatpayer_v1

auto_renewalbooleanOptionalDeprecated

DEPRECATED. Indicates whether the subscription auto-renews after the billing cycles complete.

Defaultfalse

application_contextobject<application_context>OptionalDeprecated

DEPRECATED. The application context, which customizes the payer experience during the subscription approval process with PayPal.

application_context properties

7 properties

brand_namestringOptionalDeprecated

The label that overrides the business name in the PayPal account on the PayPal site.

Match^.*$Length1 <= length <= 127

localestring<language>OptionalDeprecated

The BCP 47-formatted locale of pages that the PayPal payment experience shows. PayPal supports a five-character code. For example, `da-DK`, `he-IL`, `id-ID`, `ja-JP`, `no-NO`, `pt-BR`, `ru-RU`, `sv-SE`, `th-TH`, `zh-CN`, `zh-HK`, or `zh-TW`.

Match^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$Formatppaas_common_language_v3Length2 <= length <= 10

shipping_preferenceenumOptionalDeprecated

The location from which the shipping address is derived.

Match^[A-Z_]+$Length1 <= length <= 24

Allowed values

"GET_FROM_FILE"Default
"NO_SHIPPING"
"SET_PROVIDED_ADDRESS"

user_actionenumOptionalDeprecated

Configures the label name to `Continue` or `Subscribe Now` for subscription consent experience.

Match^[A-Z_]+$Length1 <= length <= 24

Allowed values

"CONTINUE"
"SUBSCRIBE_NOW"Default

payment_methodobject<Payment Method>OptionalDeprecated

The customer and merchant payment preferences.

return_urlstringRequiredDeprecated

The URL where the customer is redirected after the customer approves the payment.

FormaturiLength10 <= length <= 4000

cancel_urlstringRequiredDeprecated

The URL where the customer is redirected after the customer cancels the payment.

FormaturiLength10 <= length <= 4000

custom_idstringOptional

The custom id for the subscription. Can be invoice id.

Match^[\x20-\x7E]+Length1 <= length <= 127

planobject<plan_override>Optional

An inline plan object to customise the subscription. You can override plan level default attributes by providing customised values for the subscription in this object.

merchant_inventorymerchant_inventoryOptional

Merchant's inventory identifier details for the WPS hosted button.

Response Body

`application/json`

curl -X POST "https://example.com/v1/billing/subscriptions" \  -H "Content-Type: string" \  -H "Content-Type: application/json" \  -d '{    "plan_id": "stringstringstringstringst"  }'

{  "status": "APPROVAL_PENDING",  "status_change_note": "string",  "status_update_time": "stringstringstringst",  "id": "string",  "plan_id": "string",  "start_time": "stringstringstringst",  "quantity": "string",  "shipping_amount": {    "currency_code": "str",    "value": "string"  },  "subscriber": {    "email_address": "string",    "payer_id": "stringstrings",    "name": {      "given_name": "string",      "surname": "string"    },    "shipping_address": {      "name": {        "full_name": "string"      },      "email_address": "string",      "phone_number": {        "country_code": "str",        "national_number": "string"      },      "type": "SHIPPING",      "options": [],      "address": {        "address_line_1": "string",        "address_line_2": "string",        "admin_area_2": "string",        "admin_area_1": "string",        "postal_code": "string",        "country_code": "st"      }    },    "payment_source": {      "card": {        "last_digits": "string",        "brand": "VISA",        "available_networks": [          "VISA"        ],        "type": "CREDIT",        "authentication_result": {          "liability_shift": "NO",          "three_d_secure": {            "authentication_status": "Y",            "enrollment_status": "Y"          }        },        "attributes": {          "vault": {            "id": "string",            "status": "VAULTED",            "links": [              {                "href": "string",                "rel": "string",                "method": "GET"              }            ],            "customer": {              "id": "string",              "email_address": "string",              "phone": {                "phone_type": "FAX",                "phone_number": {                  "national_number": "string"                }              },              "merchant_customer_id": "string"            }          }        },        "from_request": {          "expiry": "strings",          "last_digits": "stri"        },        "bin_details": {          "bin": "string",          "issuing_bank": "string",          "bin_country_code": "st",          "products": [            "string"          ]        },        "stored_credential": {          "payment_initiator": "CUSTOMER",          "payment_type": "ONE_TIME",          "usage": "FIRST",          "previous_network_transaction_reference": {            "id": "stringstr",            "date": "stri",            "network": "VISA",            "acquirer_reference_number": "string"          }        },        "name": "string",        "billing_address": {          "address_line_1": "string",          "address_line_2": "string",          "admin_area_2": "string",          "admin_area_1": "string",          "postal_code": "string",          "country_code": "st"        },        "expiry": "strings",        "currency_code": "str"      }    }  },  "billing_info": {    "outstanding_balance": {      "currency_code": "str",      "value": "string"    },    "cycle_executions": [],    "last_payment": {      "amount": {        "currency_code": "str",        "value": "string"      },      "time": "stringstringstringst"    },    "next_billing_time": "stringstringstringst",    "final_payment_time": "stringstringstringst",    "failed_payments_count": 0,    "last_failed_payment": {      "amount": {        "currency_code": "str",        "value": "string"      },      "time": "stringstringstringst",      "reason_code": "PAYMENT_DENIED",      "next_payment_retry_time": "stringstringstringst"    }  },  "create_time": "stringstringstringst",  "update_time": "stringstringstringst",  "payer_holding_preference": null,  "custom_id": "string",  "plan_overridden": true,  "plan": {    "product_id": "stringstringstringstri",    "name": "string",    "description": "string",    "billing_cycles": [      {        "pricing_scheme": {          "version": 0,          "fixed_price": {            "currency_code": "str",            "value": "string"          },          "pricing_model": "VOLUME",          "tiers": [            {              "starting_quantity": "string",              "ending_quantity": "string",              "amount": {                "currency_code": "str",                "value": "string"              }            }          ],          "create_time": "stringstringstringst",          "update_time": "stringstringstringst"        },        "frequency": {          "interval_unit": "DAY",          "interval_count": 1        },        "tenure_type": "REGULAR",        "sequence": 1,        "total_cycles": 1      }    ],    "payment_preferences": {      "auto_bill_outstanding": true,      "setup_fee": {        "currency_code": "str",        "value": "string"      },      "setup_fee_failure_action": "CONTINUE",      "payment_failure_threshold": 0    },    "merchant_preferences": {      "return_url": "http://example.com",      "cancel_url": "http://example.com"    },    "taxes": {      "percentage": "string",      "inclusive": true    },    "quantity_supported": false  },  "links": [    {      "href": "string",      "rel": "string",      "method": "GET"    }  ]}

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

Authorization

Header Parameters

Request Body

money properties

subscriber_request properties

name properties

phone_with_type properties

Phone properties

shipping_detail properties

name properties

Phone properties

shipping_option properties

money properties

Portable Postal Address (Medium-Grained) properties

payment_source properties

card_request properties

Portable Postal Address (Medium-Grained) properties

card_attributes properties

card_customer properties

phone_with_type properties

Phone properties

vault_instruction_base properties

card_verification properties

application_context properties

Payment Method properties

plan_override properties

billing_cycle_override properties

pricing_scheme properties

money properties

pricing_tier properties

money properties

payment_preferences_override properties

money properties

taxes_override properties

Response Body

200application/json

201application/json

400application/json

401application/json

403application/json

422application/json

500application/json

defaultapplication/json

On this page

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`