PayPal Billing API
The Billing API from PayPal — 13 operation(s) for billing.
PayPal Billing API is one of 37 APIs that PayPal publishes on the APIs.io network, described by a machine-readable OpenAPI specification and an AsyncAPI event-driven specification.
Tagged areas include Billing. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, and an AsyncAPI specification.
This API exposes 16 operations across 13 paths, and defines 113 schemas. It is described by OpenAPI 3.0.3, at version 1.6.
Requests are made against 2 base URLs: https://api-m.sandbox.paypal.com, https://api-m.paypal.com.
16 operations
13 paths
113 schemas
4 GET2 PATCH10 POST
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 1
PayPal Billing API declares
1 security scheme
for authenticating requests.
It supports OAuth 2.0 (Oauth2) using the clientCredentials flow, exposing 1 scope.
Oauth2— Oauth 2.0 authentication
Paths & Operations 16
Across 13 paths, the API surfaces 16 operations — 4 GET, 2 PATCH, 10 POST. Each is listed below with its method, path, parameters, and response codes.
Billing 16
POST
/v1/billing/plans
Create plan
GET
/v1/billing/plans
List plans
GET
/v1/billing/plans/{id}
Show plan details
PATCH
/v1/billing/plans/{id}
Update plan
POST
/v1/billing/plans/{id}/activate
Activate plan
POST
/v1/billing/plans/{id}/deactivate
Deactivate plan
POST
/v1/billing/plans/{id}/update-pricing-schemes
Update pricing
POST
/v1/billing/subscriptions
Create subscription
GET
/v1/billing/subscriptions/{id}
Show subscription details
PATCH
/v1/billing/subscriptions/{id}
Update subscription
POST
/v1/billing/subscriptions/{id}/revise
Revise plan or quantity of subscription
POST
/v1/billing/subscriptions/{id}/suspend
Suspend subscription
POST
/v1/billing/subscriptions/{id}/cancel
Cancel subscription
POST
/v1/billing/subscriptions/{id}/activate
Activate subscription
POST
/v1/billing/subscriptions/{id}/capture
Capture authorized payment on subscription
GET
/v1/billing/subscriptions/{id}/transactions
List transactions for subscription
Schemas 113
The contract defines 113 schemas that model the data the API accepts and returns. The most detailed are plan (12 properties), address_portable (10 properties), subscription_request_post (9 properties), plan_request_POST (8 properties). Each schema is shown below with its type and property counts.
plan_override
object
An inline plan object to customise the subscription. You can override plan level default attributes by providing customised values for the subscription in this…
3 properties
subscriptions.activate-422
object
1 property
shipping_detail
object
The shipping details.
3 properties
subscription_revise_response
object
The response to a request to update the quantity of the product or service in a subscription. You can also use this method to switch the plan and update the sh…
link_description
object
The request-related [HATEOAS link](/docs/api/reference/api-responses/hateoas-links) information.
3 properties
2 required
error_422
object
The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 respons…
5 properties
subscriptions.suspend-400
object
1 property
subscription_billing_info
object
The billing details for the subscription. If the subscription was or is active, these fields are populated.
7 properties
2 required
error_link_description
object
The request-related [HATEOAS link](/api/rest/responses/hateoas-links) information.
3 properties
2 required
payment_source_response
object
The payment source used to fund the payment.
1 property
phone
object
The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).
3 properties
2 required
subscriptions.revise-404
object
1 property
plan
object
The plan details.
12 properties
error_default
The default error response.
subscriber_request
object
The subscriber request information .
401
object
1 property
subscription_status
object
The subscription status details.
3 properties
pricing_scheme
object
The pricing scheme details.
6 properties
last_payment_details
object
The details for the last payment.
2 required
card
object
The payment card to use to fund a payment. Can be a credit or debit card.
8 properties
2 required
authentication_response
object
Results of Authentication such as 3D Secure.
2 properties
error_401
object
Authentication failed due to missing Authorization header, or invalid authentication credentials.
5 properties
subscription_revise_request
object
The request to update the quantity of the product or service in a subscription. You can also use this method to switch the plan and update the shippingamount a…
6 properties
subscription
object
The subscription details.
update_pricing_schemes_list_request
object
The update pricing scheme request details.
1 property
1 required
email_address
string
The internationalized email address. Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accep…
tax_info
object
The tax ID of the customer. The customer is also known as the payer. Both taxid and taxidtype are required.
2 properties
2 required
date_time
string
The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339section-5.6). Seconds are required while fractional seconds are option…
capture_status
object
The status of a captured payment.
2 properties
billing_cycle
object
The billing cycle details.
5 properties
3 required
language
string
The [language tag](https://tools.ietf.org/html/bcp47section-2) for the language in which to localize the error-related strings, such as messages, issues, and s…
payment_source
object
The payment source definition. To be eligible to create subscription using debit or credit card, you will need to sign up here (https://www.paypal.com/bizsignu…
1 property
transactions_list
object
The list transactions for a subscription request details.
4 properties
account_id
string
The account identifier for a PayPal account.
error_403
object
The client is not authorized to access this resource, although it may have valid credentials.
5 properties
subscriber
object
The subscriber response information.
liability_shift
string
Liability shift indicator. The outcome of the issuer's authentication.
plans.update-pricing-schemes-400
object
1 property
taxes_override
object
The tax details.
2 properties
subscription_suspend_request
object
The suspend subscription request details.
1 property
1 required
subscriptions.revise-400
object
1 property
name
object
The name of the party.
7 properties
subscriptions.capture-422
object
1 property
subscriptions.cancel-400
object
1 property
three_d_secure_authentication_response
object
Results of 3D Secure Authentication.
2 properties
date_year_month
string
The year and month, in ISO-8601 YYYY-MM date format. See [Internet date and time format](https://tools.ietf.org/html/rfc3339section-5.6).
subscription_cancel_request
object
The cancel subscription request details.
1 property
1 required
payment_method
object
The customer and merchant payment preferences.
3 properties
subscription_capture_request
object
The charge amount from the subscriber.
3 properties
3 required
payer_base
object
The customer who approves and pays for the order. The customer is also known as the payer.
2 properties
country_code
string
The [two-character ISO 3166-1 code](/docs/integration/direct/rest/country-codes/) that identifies the country or region. Note: The country code for Great Brita…
subscriptions.cancel-422
object
1 property
subscriptions.revise-422
object
1 property
subscriptions.capture-400
object
1 property
payment_preferences_override
object
The payment preferences to override at subscription level.
4 properties
plans.patch-400
object
1 property
422
object
1 property
frequency
object
The frequency of the billing cycle.
2 properties
1 required
subscriptions.transactions-400
object
1 property
plans.create-400
object
1 property
error_404
object
The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available.
5 properties
subscriptions.activate-400
object
1 property
cycle_execution
object
The regular and trial execution details for a billing cycle.
6 properties
3 required
card_response_with_billing_address
object
The payment card used to fund the payment. Card can be a credit or debit card.
phone_type
string
The phone type.
plans.patch-422
object
1 property
application_context
object
The application context, which customizes the payer experience during the subscription approval process with PayPal.
7 properties
2 required
error_details
object
The error details. Required for client-side 4XX errors.
5 properties
1 required
subscription_request_post
object
The create subscription request details.
9 properties
1 required
transaction
object
The transaction details.
3 required
phone_with_type
object
The phone information.
2 properties
1 required
plan_collection
object
The list of plans with details.
4 properties
amount_with_breakdown
object
The breakdown details for the amount. Includes the gross, tax, fee, and shipping amounts.
6 properties
1 required
pricing_tier
object
The pricing tier details.
3 properties
2 required
subscription_activate_request
object
The activate subscription request details.
1 property
failed_payment_details
object
The details for the failed payment of the subscription.
4 properties
2 required
error_503
object
The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime.
4 properties
pares_status
string
Transactions status result identifier. The outcome of the issuer's authentication.
currency_code
string
The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency.
payee_payment_method_preference
string
The merchant-preferred payment methods.
404
object
1 property
email
string
The internationalized email address. Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accep…
error_500
object
This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has…
4 properties
payer
object
The customer who approves and pays for the order. The customer is also known as the payer.
subscriptions.patch-400
object
1 property
plan_request_POST
object
The create plan request details.
8 properties
4 required
subscriptions.create-422
object
1 property
error_409
object
The server has detected a conflict while processing this request.
5 properties
403
object
1 property
payment_preferences
object
The payment preferences for a subscription.
4 properties
date_no_time
string
The stand-alone date, in [Internet date and time format](https://tools.ietf.org/html/rfc3339section-5.6). To represent special legal values, such as a date of…
patch
object
The JSON patch object to apply partial updates to resources.
4 properties
1 required
card_brand
string
The card network or brand. Applies to credit, debit, gift, and payment cards.
update_pricing_scheme_request
object
The update pricing scheme request details.
2 properties
2 required
enrolled
string
Status of Authentication eligibility.
plans.deactivate-422
object
1 property
400
object
1 property
error_location
string
The location of the field that caused the error. Value is body, path, or query.
patch_request
array
An array of JSON patch objects to apply partial updates to resources.
money
object
The currency and amount for a financial transaction, such as a balance or payment due.
2 properties
2 required
capture_status_details
object
The details of the captured payment status.
1 property
subscriptions.suspend-422
object
1 property
card_response
object
The payment card to use to fund a payment. Card can be a credit or debit card.
4 properties
subscriptions.patch-422
object
1 property
address_portable
object
The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) an…
10 properties
1 required
plans.update-pricing-schemes-422
object
1 property
taxes
object
The tax details.
2 properties
1 required
error_400
object
Request is not well-formed, syntactically incorrect, or violates schema.
5 properties
subscriptions.create-400
object
1 property
error_415
object
The server does not support the request payload's media type.
5 properties
plans.activate-422
object
1 property
percentage
string
The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as 19.99.
billing_cycle_override
object
The billing cycle details to override at subscription level. The subscription billing cycle definition has to adhere to the plan billing cycle definition.
3 properties
1 required
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from PayPal 12
Other APIs PayPal publishes across the network.
PayPal Activate API
PayPal Authorizations API
PayPal Balances API
PayPal Cancel API
PayPal Capture API
PayPal Captures API
PayPal Deactivate API
PayPal Disputes-Actions API
PayPal Disputes API
PayPal Invoices API
PayPal Orders API
PayPal Partner-Referrals API
#Billing
Where this information came from
This is an independent, third-party profile of PayPal Billing API, published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.
The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.
Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.
info@apievangelist.com
·
Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and
you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.