Create subscription

Creates a subscription.

Authorization

AuthorizationBearer <token>

Oauth 2.0 authentication

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

Scopes

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

Header Parameters

Content-Type*string

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

Prefer?string

The preferred server response upon successful completion of the request. Value is:return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.return=representation. The server returns a complete resource representation, including the current state of the resource.

Default"return=minimal"

PayPal-Request-Id?string

The server stores keys for 72 hours.

PayPal-Client-Metadata-Id?string

The PayPal Client Metadata Id(CMID) is used to provide device-specific information to PayPal's risk engine. This is crucial for transactions that require device-specific risk assessments. Merchants typically use the Paypal SDK that automatically submits the CMID or they use tools like Fraudnet JS for web or Magnes JS for mobile to generate the CMID on the frontend and then pass it to the API as part of the request headers.

Length1 <= length <= 36

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X POST "https://api-m.sandbox.paypal.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"
    }
  ]
}

{
  "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"
    }
  ]
}

{
  "name": "INVALID_REQUEST",
  "message": "Request is not well-formed, syntactically incorrect, or violates schema.",
  "debug_id": "string",
  "links": [],
  "details": [
    {
      "issue": "INVALID_PARAMETER_SYNTAX",
      "description": "The value of a field does not conform to the expected format."
    }
  ]
}

{
  "name": "AUTHENTICATION_FAILURE",
  "message": "Authentication failed due to missing authorization header, or invalid authentication credentials.",
  "debug_id": "string",
  "links": [],
  "details": [
    {
      "issue": "INVALID_ACCOUNT_STATUS",
      "description": "Account validations failed for the user."
    }
  ]
}

{
  "name": "NOT_AUTHORIZED",
  "message": "Authorization failed due to insufficient permissions.",
  "debug_id": "string",
  "links": [],
  "details": [
    {
      "issue": "PERMISSION_DENIED",
      "description": "You do not have permission to access or perform operations on this resource."
    }
  ]
}

{
  "name": "UNPROCESSABLE_ENTITY",
  "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
  "debug_id": "string",
  "links": [],
  "details": [
    {
      "issue": "USER_ACCOUNT_CLOSED",
      "description": "User account locked or closed."
    }
  ]
}

{
  "name": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred.",
  "debug_id": "90957fca61718",
  "links": [
    {
      "href": "https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR",
      "rel": "information_link"
    }
  ]
}

{
  "name": "INVALID_REQUEST",
  "message": "Request is not well-formed, syntactically incorrect, or violates schema.",
  "details": [
    {
      "field": "string",
      "value": "string",
      "location": "body",
      "issue": "string",
      "description": "string"
    }
  ],
  "debug_id": "string",
  "links": []
}

Header Parameters

Content-Type*string

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

Prefer?string

Default"return=minimal"

PayPal-Request-Id?string

The server stores keys for 72 hours.

PayPal-Client-Metadata-Id?string

Length1 <= length <= 36

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

plan_id*string

The ID of the plan.

Match^P-[A-Z0-9]*$

Length26 <= length <= 26

start_time?date_time

The date and time when the subscription started, in Internet date and time format.

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_v3

Length20 <= length <= 64

quantity?string

The quantity of the product in the subscription.

Match^([0-9]+|([0-9]+)?[.][0-9]+)$

Length1 <= length <= 32

shipping_amount?

The shipping charges.

subscriber?

Formatpayer_v1

auto_renewal?booleanDeprecated

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

Defaultfalse

application_context?Deprecated

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

custom_id?string

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

Match^[\x20-\x7E]+

Length1 <= length <= 127

plan?

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_inventory?merchant_inventory

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

{ "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" } ] }

{ "name": "INVALID_REQUEST", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "debug_id": "string", "links": [], "details": [ { "issue": "INVALID_PARAMETER_SYNTAX", "description": "The value of a field does not conform to the expected format." } ] }

{ "name": "AUTHENTICATION_FAILURE", "message": "Authentication failed due to missing authorization header, or invalid authentication credentials.", "debug_id": "string", "links": [], "details": [ { "issue": "INVALID_ACCOUNT_STATUS", "description": "Account validations failed for the user." } ] }

{ "name": "NOT_AUTHORIZED", "message": "Authorization failed due to insufficient permissions.", "debug_id": "string", "links": [], "details": [ { "issue": "PERMISSION_DENIED", "description": "You do not have permission to access or perform operations on this resource." } ] }

{ "name": "UNPROCESSABLE_ENTITY", "message": "The requested action could not be performed, semantically incorrect, or failed business validation.", "debug_id": "string", "links": [], "details": [ { "issue": "USER_ACCOUNT_CLOSED", "description": "User account locked or closed." } ] }

{ "name": "INTERNAL_SERVER_ERROR", "message": "An internal server error occurred.", "debug_id": "90957fca61718", "links": [ { "href": "https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR", "rel": "information_link" } ] }

{ "name": "INVALID_REQUEST", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "details": [ { "field": "string", "value": "string", "location": "body", "issue": "string", "description": "string" } ], "debug_id": "string", "links": [] }

Create subscription

200application/json

201application/json

400application/json

401application/json

403application/json

422application/json

500application/json

defaultapplication/json

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 subscription

200application/json

201application/json

400application/json

401application/json

403application/json

422application/json

500application/json

defaultapplication/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`