PayPal Billing API
The Billing API from PayPal — 13 operation(s) for billing.
PayPal Billing API is one of 27 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.2.0, 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.
shipping_detail
object
The shipping details.
3 properties
plans.update-pricing-schemes-400
object
1 property
enrolled
string
Status of Authentication eligibility.
subscriptions.activate-422
object
1 property
401
object
1 property
error_default
The default error response.
amount_with_breakdown
object
The breakdown details for the amount. Includes the gross, tax, fee, and shipping amounts.
6 properties
1 required
failed_payment_details
object
The details for the failed payment of the subscription.
4 properties
2 required
update_pricing_schemes_list_request
object
The update pricing scheme request details.
1 property
1 required
cycle_execution
object
The regular and trial execution details for a billing cycle.
6 properties
3 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
pricing_tier
object
The pricing tier details.
3 properties
2 required
liability_shift
string
Liability shift indicator. The outcome of the issuer's authentication.
error_400
object
Request is not well-formed, syntactically incorrect, or violates schema.
5 properties
three_d_secure_authentication_response
object
Results of 3D Secure Authentication.
2 properties
subscriptions.transactions-400
object
1 property
plan_collection
object
The list of plans with details.
4 properties
pares_status
string
Transactions status result identifier. The outcome of the issuer's authentication.
subscriber_request
object
The subscriber request information .
payment_preferences
object
The payment preferences for a subscription.
4 properties
400
object
1 property
payee_payment_method_preference
string
The merchant-preferred payment methods.
phone_type
string
The phone type.
subscriptions.capture-422
object
1 property
subscriptions.suspend-400
object
1 property
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…
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…
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…
plans.activate-422
object
1 property
phone_with_type
object
The phone information.
2 properties
1 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…
subscriber
object
The subscriber response information.
payer_base
object
The customer who approves and pays for the order. The customer is also known as the payer.
2 properties
plans.update-pricing-schemes-422
object
1 property
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
subscription
object
The subscription details.
subscriptions.capture-400
object
1 property
card_brand
string
The card network or brand. Applies to credit, debit, gift, and payment cards.
address_portable
object
The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) an…
10 properties
1 required
plans.create-400
object
1 property
403
object
1 property
subscription_capture_request
object
The charge amount from the subscriber.
3 properties
3 required
patch
object
The JSON patch object to apply partial updates to resources.
4 properties
1 required
capture_status_details
object
The details of the captured payment status.
1 property
patch_request
array
An array of JSON patch objects to apply partial updates to resources.
transaction
object
The transaction details.
3 required
authentication_response
object
Results of Authentication such as 3D Secure.
2 properties
plan_request_POST
object
The create plan request details.
8 properties
4 required
error_503
object
The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime.
4 properties
percentage
string
The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as 19.99.
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
subscriptions.cancel-400
object
1 property
error_401
object
Authentication failed due to missing Authorization header, or invalid authentication credentials.
5 properties
subscriptions.revise-404
object
1 property
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
error_415
object
The server does not support the request payload's media type.
5 properties
subscriptions.patch-400
object
1 property
subscription_activate_request
object
The activate subscription request details.
1 property
link_description
object
The request-related [HATEOAS link](/docs/api/reference/api-responses/hateoas-links) information.
3 properties
2 required
subscription_suspend_request
object
The suspend subscription request details.
1 property
1 required
currency_code
string
The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency.
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…
transactions_list
object
The list transactions for a subscription request details.
4 properties
taxes_override
object
The tax details.
2 properties
subscription_request_post
object
The create subscription request details.
9 properties
1 required
account_id
string
The account identifier for a PayPal account.
pricing_scheme
object
The pricing scheme details.
6 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…
subscriptions.activate-400
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_403
object
The client is not authorized to access this resource, although it may have valid credentials.
5 properties
plans.deactivate-422
object
1 property
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
plans.patch-400
object
1 property
subscriptions.patch-422
object
1 property
subscriptions.create-400
object
1 property
last_payment_details
object
The details for the last payment.
2 required
card_response_with_billing_address
object
The payment card used to fund the payment. Card can be a credit or debit card.
subscriptions.revise-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
payment_method
object
The customer and merchant payment preferences.
3 properties
plan
object
The plan details.
12 properties
error_details
object
The error details. Required for client-side 4XX errors.
5 properties
1 required
plans.patch-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
error_location
string
The location of the field that caused the error. Value is body, path, or query.
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
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
taxes
object
The tax details.
2 properties
1 required
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_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).
subscriptions.create-422
object
1 property
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
subscription_status
object
The subscription status details.
3 properties
error_409
object
The server has detected a conflict while processing this request.
5 properties
frequency
object
The frequency of the billing cycle.
2 properties
1 required
money
object
The currency and amount for a financial transaction, such as a balance or payment due.
2 properties
2 required
card
object
The payment card to use to fund a payment. Can be a credit or debit card.
8 properties
2 required
subscriptions.revise-422
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…
422
object
1 property
error_link_description
object
The request-related [HATEOAS link](/api/rest/responses/hateoas-links) information.
3 properties
2 required
payment_preferences_override
object
The payment preferences to override at subscription level.
4 properties
billing_cycle
object
The billing cycle details.
5 properties
3 required
name
object
The name of the party.
7 properties
update_pricing_scheme_request
object
The update pricing scheme request details.
2 properties
2 required
payer
object
The customer who approves and pays for the order. The customer is also known as the payer.
subscription_cancel_request
object
The cancel subscription request details.
1 property
1 required
subscriptions.cancel-422
object
1 property
capture_status
object
The status of a captured payment.
2 properties
404
object
1 property
subscriptions.suspend-422
object
1 property
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from PayPal 12
Other APIs PayPal publishes across the network.
PayPal Authorizations API
PayPal Balances API
PayPal Captures API
PayPal Disputes-Actions API
PayPal Disputes API
PayPal Invoices API
PayPal Orders API
PayPal Partner-Referrals API
PayPal Payment-Tokens API
PayPal Payouts API
PayPal Payouts-Item API
PayPal Products 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.