PayPal REST API Specifications

https://github.com/paypal/paypal-rest-api-specifications
Admin
This project provides the specification files for PayPal's REST APIs, allowing developers to...
Tokens:75,009
Snippets:432
Trust Score:9.5
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### POST /v3/vault/setup-tokens

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/endpoints.md

Creates a setup token to be used for future setup.

```APIDOC
## POST /v3/vault/setup-tokens

### Description
Creates a setup token.

### Method
POST

### Endpoint
/v3/vault/setup-tokens

### Parameters
No parameters documented.

### Request Example
{ }

### Response
#### Success Response (200, 201)
No response schema documented.

```

--------------------------------

### Create Product with cURL

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/catalog-products.md

Example cURL command to create a product with return=representation to get the full product object. Use sandbox server with OAuth2 bearer token; the body must include name and type.

```bash
curl -sS -X POST https://api-m.sandbox.paypal.com/v1/catalogs/products \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '{ "name": "Video Streaming Service", "type": "SERVICE", "category": "SOFTWARE", "home_url": "https://example.com" }'
```

--------------------------------

### GET /v3/vault/setup-tokens/{id}

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/endpoints.md

Retrieves details of a specific setup token.

```APIDOC
## GET /v3/vault/setup-tokens/{id}

### Description
Retrieves a specific setup token by ID.

### Method
GET

### Endpoint
/v3/vault/setup-tokens/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the setup token to retrieve.

### Response
#### Success Response (200)
No response schema documented.

```

--------------------------------

### Create setup token with curl

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/payment-method-tokens.md

Creates a setup token using a test card, then pipes the response through jq to extract `id`, `status`, and `links`. Follow the payer-action link (e.g. 3DS) until the status becomes APPROVED.

```bash
# Create setup token, then follow payer-action link (e.g. 3DS) until APPROVED
curl -sS -X POST https://api-m.sandbox.paypal.com/v3/vault/setup-tokens \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "payment_source": { "card": { "number": "4111111111111111", "expiry": "2027-01" } } }' \
  | jq '{id, status, links}'
```

--------------------------------

### GET /v3/vault/setup-tokens/{id} — setup-tokens.get

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/payment-method-tokens.md

Returns a readable representation of the temporarily vaulted payment source using the setup token ID.

```APIDOC
## [GET] /v3/vault/setup-tokens/{id}

### Description
Returns a readable representation of the temporarily vaulted payment source.

### Method
GET

### Endpoint
/v3/vault/setup-tokens/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The setup token ID. Must match pattern `^[0-9a-zA-Z_-]+$`, min length 7, max length 36.

### Response
#### Success Response (200)
- **id** (string) - The setup token ID.
- **status** (string) - Status of the setup token.
- **customer** (object) - The customer associated with the setup token.
- **payment_source** (object) - The payment source.
- **links** (array) - HATEOAS links.

#### Response Example
```json
{
  "id": "6FJQFXrWxTOh34o7nIGo",
  "status": "APPROVED",
  "customer": { "id": "customer_id" },
  "payment_source": { "card": { "last_digits": "1111" } },
  "links": [
    { "href": "https://api-m.paypal.com/v3/vault/setup-tokens/6FJQFXrWxTOh34o7nIGo", "rel": "self" }
  ]
}
```

### Errors
403, 404, 422, 500 → error object

```

--------------------------------

### Create Order with curl

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/orders.md

Example curl command to create an order with a CAPTURE intent and a purchase unit of 100.00 USD. Uses the 'Prefer: return=representation' header to get the full order in the response.

```bash
curl -sS -X POST https://api-m.paypal.com/v2/checkout/orders \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '{
    "intent": "CAPTURE",
    "purchase_units": [{ "amount": { "currency_code": "USD", "value": "100.00" } }]
  }'
```

--------------------------------

### Get Product Details (GET by product_id)

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/catalog-products.md

Retrieves details for a product by its product_id, which must match the pattern ^PROD-[A-Z0-9]*$ and be 22 characters long. Returns a product object on success.

```http
GET /v1/catalogs/products/{product_id}
operationId: products.get
parameters: product_id (path, REQUIRED, ^PROD-[A-Z0-9]*$, length 22)
responses: 200 → product
```

--------------------------------

### Capture Authorization - curl Example

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/payments.md

Example curl command to POST to the capture endpoint. Uses a PayPal API domain and includes an amount and final_capture in the JSON body.

```bash
curl -sS -X POST https://api-m.paypal.com/v2/payments/authorizations/2MU14914XX593120P/capture \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "amount": { "currency_code": "USD", "value": "100.00" }, "final_capture": true }'
```

--------------------------------

### GET /v3/vault/setup-tokens/{id} — setup-tokens.get

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/payment-method-tokens.md

Returns a readable representation of the temporarily vaulted payment source. Returns `setup_token_response`. Errors: `403/404/422/500` → `error`.

```http
GET /v3/vault/setup-tokens/{id}
operationId: setup-tokens.get
parameters: id (path, REQUIRED, ^[0-9a-zA-Z_-]+$, min 7 max 36)
responses: 200 → setup_token_response
```

--------------------------------

### GET /v2/invoicing/templates

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/endpoints.md

Lists invoice templates.

```APIDOC
## [GET] /v2/invoicing/templates

### Description
This endpoint lists invoice templates.

### Method
GET

### Endpoint
/v2/invoicing/templates

### Response
#### Success Response (200)
Successful response.

```

--------------------------------

### GET /v1/billing/plans

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/endpoints.md

Lists all billing plans that are available on PayPal.

```APIDOC
## GET /v1/billing/plans

### Description
Lists all billing plans that are available on PayPal.

### Method
GET

### Endpoint
/v1/billing/plans

### Parameters
#### Query Parameters
- None explicitly documented in the source.

### Request Example
None explicitly documented in the source.

### Response
#### Success Response (200)
- A list of billing plans. Specific response fields not detailed in the source.

#### Response Example
None explicitly documented in the source.
```

--------------------------------

### GET /v2/invoicing/invoices

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/endpoints.md

Lists invoices.

```APIDOC
## [GET] /v2/invoicing/invoices

### Description
This endpoint lists invoices.

### Method
GET

### Endpoint
/v2/invoicing/invoices

### Response
#### Success Response (200)
Successful response.

```

--------------------------------

### GET /v1/catalogs/products - products.list

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/catalog-products.md

Lists products with optional pagination and total count parameters. Returns a collection of products.

```APIDOC
## GET /v1/catalogs/products

### Description
List products with pagination support. Optionally include total counts.

### Method
GET

### Endpoint
/v1/catalogs/products

### Parameters
#### Query Parameters
- **page_size** (integer) - Optional - Number of items per page, 1–20, default 10
- **page** (integer) - Optional - Page number, 1–100000, default 1
- **total_required** (boolean) - Optional - Include total_items/total_pages in response, default false

### Response
#### Success Response (200)
- **products** (array of product) - Array of product objects
- **total_items** (integer) - Total number of items (when total_required is true)
- **total_pages** (integer) - Total number of pages (when total_required is true)
- **links** (link_description_list) - HATEOAS links

#### Response Example
{
  "products": [],
  "total_items": 0,
  "total_pages": 0,
  "links": []
}

### Errors
- 400 - Bad Request (error_400 plus 400)
- 401 - Unauthorized (error_401 plus 401)
- 403 - Forbidden
- 500 - Internal Server Error
- default - No content
```

--------------------------------

### curl example for balances.get

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/transaction-search.md

Curl command to call the balances endpoint with as_of_time and currency_code, using a bearer token and piping to jq to extract balances.

```bash
curl -sS "https://api-m.sandbox.paypal.com/v1/reporting/balances?as_of_time=2024-04-01T00:00:00-07:00&currency_code=USD" \
  -H "Authorization: Bearer $TOKEN" | jq '.balances'
```

--------------------------------

### GET /v1/billing/plans — plans.list

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/subscriptions.md

Lists billing plans, optionally filtered by product ID. Returns a collection of plans with pagination information.

```APIDOC
## GET /v1/billing/plans

### Description
Lists billing plans, optionally filtered by product ID. Returns a collection of plans with pagination information.

### Method
GET

### Endpoint
/v1/billing/plans

### Parameters
#### Header Parameters
- **Prefer** (string) - Optional - Response preference, default `"return=minimal"`

#### Query Parameters
- **product_id** (string, min 6 max 50) - Optional - Filter plans by product
- **page_size** (integer, 1–20, default `10`) - Optional - Page size
- **page** (integer, 1–100000, default `1`) - Optional - Page number
- **total_required** (boolean, default `false`) - Optional - Include total in response

### Response
#### Success Response (200)
Returns `plan_collection` (plans array + `total_items`, `total_pages`, `links`).

#### Response Example
```json
{
  "plans": [],
  "total_items": 0,
  "total_pages": 0,
  "links": []
}
```
```

--------------------------------

### curl example for search.get

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/transaction-search.md

Curl command to call the transactions endpoint with start_date, end_date, fields, and page_size, using a bearer token and piping to jq to extract transaction_details.

```bash
curl -sS "https://api-m.sandbox.paypal.com/v1/reporting/transactions?start_date=2024-04-01T00:00:00-07:00&end_date=2024-04-02T23:59:59-07:00&fields=transaction_info,payer_info&page_size=50" \
  -H "Authorization: Bearer $TOKEN" | jq '.transaction_details'
```

--------------------------------

### GET /v1/payment-experience/web-profiles

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/payment-experience.md

Lists the latest 20 web experience profiles for a merchant or subject. Returns an array of web_profile objects.

```APIDOC
## GET /v1/payment-experience/web-profiles

### Description
Lists the latest 20 web experience profiles for a merchant or subject.

### Method
GET

### Endpoint
/v1/payment-experience/web-profiles

### Parameters
None

### Response
#### Success Response (200)
- **web_profile_list** (array of web_profile) - List of web experience profiles.

#### Response Example
```json
[
  {
    "id": "string",
    "name": "string",
    "temporary": false,
    "presentation": {},
    "input_fields": {},
    "flow_config": {},
    "links": []
  }
]
```

### Error Responses
- **500** - Internal Server Error (error schema)
- **default** - Error (error schema)
```

--------------------------------

### GET /v1/reporting/balances — balances.get

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/transaction-search.md

Lists all balances. Optionally filter by as_of_time and currency_code.

```APIDOC
## GET /v1/reporting/balances

### Description
Lists all balances.

### Method
GET

### Endpoint
/v1/reporting/balances

### Parameters
#### Query Parameters
- **as_of_time** (date_time pattern) - Optional - Balance as of this time (balances take up to 3 hours to appear)
- **currency_code** (string, min 3 max 3) - Optional - `^[A-Z]{3}$` currency filter

### Request Example
```bash
curl -sS "https://api-m.sandbox.paypal.com/v1/reporting/balances?as_of_time=2024-04-01T00:00:00-07:00&currency_code=USD" \
  -H "Authorization: Bearer $TOKEN" | jq '.balances'
```

### Response
#### Success Response (200)
- **balances** (array of `balance_detail`) - Each `balance_detail` has `currency`, `total_balance`, `available_balance`, `withheld_balance` (each: `currency_code` + `value`)
- **account_id** (string) - Account ID

#### Response Example
```json
{
  "balances": [
    {
      "currency": "USD",
      "total_balance": {
        "currency_code": "USD",
        "value": "100.00"
      },
      "available_balance": {
        "currency_code": "USD",
        "value": "80.00"
      },
      "withheld_balance": {
        "currency_code": "USD",
        "value": "20.00"
      }
    }
  ],
  "account_id": "string"
}
```

### Error Responses
- **400** → `error_400`
- **403** → `error_403`
- **500** → `error_500`
- **default** → no content
```

--------------------------------

### GET /v1/reporting/balances — balances.get

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/transaction-search.md

HTTP request definition for the balances.get operation. Lists all balances. Optional as_of_time and currency_code parameters.

```http
GET /v1/reporting/balances
operationId: balances.get
responses: 200 → balances_response
```

--------------------------------

### GET /v1/payment-experience/web-profiles/{id}

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/payment-experience.md

Retrieves a specific web experience profile by its ID.

```APIDOC
## GET /v1/payment-experience/web-profiles/{id}

### Description
Retrieves a specific web experience profile by its ID.

### Method
GET

### Endpoint
/v1/payment-experience/web-profiles/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the web experience profile.

### Response
#### Success Response (200)
- **web_profile** (object) - The requested web experience profile.

#### Response Example
```json
{
  "id": "string",
  "name": "string",
  "temporary": false,
  "presentation": {},
  "input_fields": {},
  "flow_config": {},
  "links": []
}
```

### Error Responses
- **500** - Internal Server Error (error schema)
- **default** - Error (error schema)
```

--------------------------------

### POST /v1/shipping/trackers-batch request example

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/shipment-tracking.md

HTTP request to add tracking details for multiple PayPal transactions. The endpoint is deprecated for legacy integrations; use the newer tracking integration instead.

```http
POST /v1/shipping/trackers-batch
operationId: trackers-batch.post
requestBody: application/json → $ref: '#/components/requestBodies/tracker_collection'
responses: 200 → batch_tracker_collection
```

--------------------------------

### GET /v1/catalogs/products/{product_id} - products.get

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/catalog-products.md

Retrieves details of a specific product by its ID. The product ID must follow the format PROD-[A-Z0-9]* and have length 22.

```APIDOC
## GET /v1/catalogs/products/{product_id}

### Description
Shows product details by product ID.

### Method
GET

### Endpoint
/v1/catalogs/products/{product_id}

### Parameters
#### Path Parameters
- **product_id** (string) - Required - Product ID, format ^PROD-[A-Z0-9]*$, length 22

### Response
#### Success Response (200)
- **id** (string) - Product ID
- **name** (string) - Product name
- **type** (enum) - Product type
- **category** (string) - Product category
- **description** (string) - Product description
- **image_url** (string) - Product image URL
- **home_url** (string) - Product homepage URL
- **create_time** (string) - Creation timestamp
- **update_time** (string) - Last update timestamp
- **links** (array) - HATEOAS links

#### Response Example
{
  "id": "PROD-XXG1234567890123",
  "name": "Video Streaming Service",
  "type": "SERVICE",
  "category": "SOFTWARE",
  "description": "High-quality streaming",
  "image_url": "https://example.com/image.png",
  "home_url": "https://example.com",
  "create_time": "2023-01-01T00:00:00Z",
  "update_time": "2023-01-01T00:00:00Z",
  "links": []
}

### Errors
- 401 - Unauthorized
- 403 - Forbidden
- 404 - Not Found
- 500 - Internal Server Error
- default - No content
```

--------------------------------

### GET /v1/billing/subscriptions/{id} — subscriptions.get

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/subscriptions.md

Shows subscription details. `fields` query: string, min 1 max 100 (e.g. `plan,billing_info`). Errors: `401/403/404/500`.

```http
GET /v1/billing/subscriptions/{id}
operationId: subscriptions.get
parameters: id (path, required), fields (query, optional)
responses: 200 → subscription
```

--------------------------------

### POST /v3/vault/setup-tokens — setup-tokens.create

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/payment-method-tokens.md

Creates a Setup Token from a payment source and adds it to the Vault of the associated customer. Returns a setup_token_response with the token ID, status, customer, payment source, and links for next steps.

```APIDOC
## [POST] /v3/vault/setup-tokens

### Description
Creates a Setup Token from a payment source and adds it to the Vault of the associated customer.

### Method
POST

### Endpoint
/v3/vault/setup-tokens

### Parameters
#### Header Parameters
- **PayPal-Request-Id** (string) - Optional - A unique identifier for the request.

#### Request Body
- **payment_source** (object) - Required - The payment source (card, paypal, venmo, apple_pay, bank). Must include `experience_context` where applicable.
- **customer** (object) - Optional - The customer associated with the payment source.

### Request Example
```json
{
  "payment_source": {
    "card": {
      "number": "4111111111111111",
      "expiry": "2027-01"
    }
  }
}
```

### Response
#### Success Response (200, 201)
- **id** (string) - The setup token ID.
- **status** (string) - Status of the setup token. Possible values: APPROVED, CREATED, PAYER_ACTION_REQUIRED (based on payment_token_status).
- **customer** (object) - The customer associated with the setup token.
- **payment_source** (object) - The payment source.
- **links** (array) - HATEOAS links for next steps, e.g., payer action.

#### Response Example
```json
{
  "id": "6FJQFXrWxTOh34o7nIGo",
  "status": "APPROVED",
  "customer": { "id": "customer_id" },
  "payment_source": { "card": { "last_digits": "1111" } },
  "links": [
    { "href": "https://api-m.paypal.com/v3/vault/setup-tokens/6FJQFXrWxTOh34o7nIGo", "rel": "self" }
  ]
}
```

### Errors
400, 403, 422, 500 → error object

```

--------------------------------

### POST /v3/vault/setup-tokens — setup-tokens.create

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/payment-method-tokens.md

Creates a Setup Token from a payment source and adds it to the Vault of the associated customer. Body `setup_token_request` — required `payment_source` (card/paypal/venmo/apple_pay/bank with `experience_context` where applicable); optional `customer`. Returns `setup_token_response` — `id`, `status` (`APPROVED | CREATED | PAYER_ACTION_REQUIRED` via payment_token_status), `customer`, `payment_source`, `links`. Errors: `400/403/422/500` → `error`.

```http
POST /v3/vault/setup-tokens
operationId: setup-tokens.create
requestBody: application/json → $ref: '#/components/schemas/setup_token_request'
parameters: PayPal-Request-Id (header, optional)
responses: 200, 201 → setup_token_response
```

--------------------------------

### Create a Partner Referral with curl and extract links

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/partner-referrals.md

This curl command creates a partner referral by sending a POST request to the Sandbox environment endpoint `/v2/customer/partner-referrals`. It includes an authentication header with `Bearer $TOKEN` and a JSON payload with products, operations, legal consents, and a return URL. The response is piped through `jq` to extract the `links` field, which contains HATEOAS links as the response includes no `referral_id`.

```bash
curl -sS -X POST https://api-m.sandbox.paypal.com/v2/customer/partner-referrals \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "products": ["EXPRESS_CHECKOUT", "PPCP"],
    "operations": [{ "operation": "API_INTEGRATION",
        "api_integration_preference": { "rest_api_integration": {
            "integration_method": "PAYPAL", "integration_type": "THIRD_PARTY" } } }],
    "legal_consents": [{ "type": "SHARE_DATA_CONSENT", "granted": true }],
    "partner_config_override": { "return_url": "https://partner.example.com/return" }
  }' | jq '.links'

```

--------------------------------

### POST /v1/catalogs/products - products.create

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/catalog-products.md

Creates a product. The request body must include name and type, with optional category, description, image_url, and home_url. Returns the created product.

```APIDOC
## POST /v1/catalogs/products

### Description
Creates a new product. The request requires a name and type, with optional descriptive fields. Returns the created product.

### Method
POST

### Endpoint
/v1/catalogs/products

### Parameters
#### Header Parameters
- **Prefer** (string) - Optional - Preferred response representation, default "return=minimal"
- **PayPal-Request-Id** (string) - Optional - Request identifier for idempotency

#### Request Body
- **name** (string) - Required - Product name, min 1 max 127 characters
- **type** (enum: DIGITAL | PHYSICAL | SERVICE) - Required - Product type
- **category** (string) - Optional - Product category
- **description** (string) - Optional - Product description
- **image_url** (string) - Optional - URL for product image
- **home_url** (string) - Optional - URL for product homepage

### Request Example
{
  "name": "Video Streaming Service",
  "type": "SERVICE",
  "category": "SOFTWARE",
  "home_url": "https://example.com"
}

### Response
#### Success Response (201)
- **id** (string) - Read-only, format ^PROD-[A-Z0-9]*$
- **create_time** (string) - Creation timestamp
- **update_time** (string) - Last update timestamp
- **links** (array) - HATEOAS links

#### Response Example
{
  "id": "PROD-XXG1234567890123",
  "create_time": "2023-01-01T00:00:00Z",
  "update_time": "2023-01-01T00:00:00Z",
  "links": []
}

### Errors
- 400 - Bad Request (error_400 plus products.create-400)
- 401 - Unauthorized (error_401)
- 403 - Forbidden
- 422 - Unprocessable Entity (error_422 plus 422)
- 500 - Internal Server Error
- default - No content
```

--------------------------------

### Endpoint definition for GET partner-referrals/{partner_referral_id}

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/partner-referrals.md

Defines the API endpoint with operationId, parameters, and response. Uses HTTP method GET, path parameter partner_referral_id (required, string), and returns referral_data_response with HTTP 200 status.

```http
GET /v2/customer/partner-referrals/{partner_referral_id}
operationId: partner-referrals.read
parameters: partner_referral_id (path, REQUIRED, string)
responses: 200 → referral_data_response
```

--------------------------------

### Create Product (POST /v1/catalogs/products)

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/catalog-products.md

Creates a product with a JSON body. The name and type fields are required; type must be DIGITAL, PHYSICAL, or SERVICE. Returns a product object with id, create_time, update_time, and links.

```http
POST /v1/catalogs/products
operationId: products.create
requestBody: application/json → $ref: '#/components/schemas/product_request_POST'
parameters: Prefer (header, default "return=minimal"), PayPal-Request-Id (header)
responses: 200, 201 → product
```

--------------------------------

### GET /v1/shipping/trackers

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/endpoints.md

Retrieves shipment trackers.

```APIDOC
## GET /v1/shipping/trackers

### Description
Retrieves a list of shipment trackers.

### Method
GET

### Endpoint
/v1/shipping/trackers

### Parameters
No parameters documented.

### Response
#### Success Response (200)
No response schema documented.

```

--------------------------------

### POST /v1/billing/plans — plans.create

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/subscriptions.md

Creates a billing plan that defines pricing and billing cycle details. Requires product ID, name, billing cycles, and payment preferences.

```APIDOC
## POST /v1/billing/plans

### Description
Creates a billing plan that defines pricing and billing cycle details. Requires product ID, name, billing cycles, and payment preferences.

### Method
POST

### Endpoint
/v1/billing/plans

### Parameters
#### Header Parameters
- **Prefer** (string) - Optional - Response preference
- **PayPal-Request-Id** (string) - Optional - Request ID for idempotency

#### Request Body
- **name** (string) - Required - Plan name
- **billing_cycles** (billing_cycle_list) - Required - List of billing cycles
- **payment_preferences** (object) - Required - Payment preferences (e.g., auto_bill_outstanding, payment_failure_threshold)
- **product_id** (string, pattern `^PROD-[A-Z0-9]*$`, length 22) - Required - Product ID
- **status** (string, `CREATED | ACTIVE`) - Optional - Plan status
- **description** (string) - Optional - Plan description
- **taxes** (object) - Optional - Tax information
- **quantity_supported** (boolean, default `false`) - Optional - Whether quantity is supported

### Request Example
```json
{
  "product_id": "PROD-XXG1234567890123",
  "name": "Basic Plan",
  "billing_cycles": [
    {
      "frequency": { "interval_unit": "MONTH", "interval_count": 1 },
      "tenure_type": "REGULAR",
      "sequence": 1,
      "pricing_scheme": { "fixed_price": { "value": "10.00", "currency_code": "USD" } }
    }
  ],
  "payment_preferences": { "auto_bill_outstanding": true, "payment_failure_threshold": 3 }
}
```

### Response
#### Success Response (200/201)
Returns the created plan object.

#### Response Example
```json
{
  "id": "P-123456789",
  "name": "Basic Plan",
  "status": "CREATED"
}
```
```

--------------------------------

### error_400 JSON schema example

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/types.md

Example of the error_400 envelope from openapi/billing_subscriptions_v1.json. It fixes the name and message values via enums and includes details, debug_id, and links fields. The table lists the enum values for error_401, error_403, error_404, error_422, and error_500.

```json
{
  "type": "object",
  "title": "Bad Request Error",
  "description": "Request is not well-formed, syntactically incorrect, or violates schema.",
  "properties": {
    "name": { "type": "string", "enum": [ "INVALID_REQUEST" ] },
    "message": { "type": "string", "enum": [ "Request is not well-formed, syntactically incorrect, or violates schema." ] },
    "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } },
    "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." },
    "links": {
      "type": "array", "minItems": 0, "maxItems": 10000,
      "items": { "$ref": "#/components/schemas/error_link_description" }
    }
  }
}
```

--------------------------------

### GET /v1/notifications/webhooks-lookup

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/endpoints.md

Retrieves a list of webhook lookup entries.

```APIDOC
## GET /v1/notifications/webhooks-lookup

### Description
Lists webhook lookup entries.

### Method
GET

### Endpoint
/v1/notifications/webhooks-lookup

### Response
#### Success Response (200)
- **200** - OK

```

--------------------------------

### POST /v1/billing/subscriptions/{id}/suspend, /cancel, /activate — subscriptions.suspend, subscriptions.cancel, subscriptions.activate

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/subscriptions.md

Suspend, cancel, or activate a subscription. `suspend` and `cancel` bodies **require** `reason` (`subscription_suspend_request`/`subscription_cancel_request`, both `required: ["reason"]`); `activate` accepts an optional `reason` (`subscription_activate_request`, no required fields). Errors: `400/401/403/404/422/500`.

```http
POST /v1/billing/subscriptions/{id}/suspend    operationId: subscriptions.suspend    responses: 204
POST /v1/billing/subscriptions/{id}/cancel     operationId: subscriptions.cancel     responses: 204
POST /v1/billing/subscriptions/{id}/activate   operationId: subscriptions.activate   responses: 204
parameters: id (path, required); requestBody: application/json (subscription_suspend_request / subscription_cancel_request / subscription_activate_request)
```

--------------------------------

### GET /v1/notifications/webhooks

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/endpoints.md

Retrieves a list of webhooks for the authenticated app.

```APIDOC
## GET /v1/notifications/webhooks

### Description
Lists webhooks for an app.

### Method
GET

### Endpoint
/v1/notifications/webhooks

### Response
#### Success Response (200)
- **200** - OK

```

--------------------------------

### POST /v1/billing/subscriptions — subscriptions.create

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/subscriptions.md

Creates a subscription. Body `subscription_request_post` — required `plan_id`; optional `start_time`, `quantity`, `shipping_amount` (money), `subscriber`, `custom_id`, `application_context`, `payment_source`, `plan`. **Returns** `subscription` (id, status, create_time, links). Errors: `400/401/403/422/500`, `default`.

```http
POST /v1/billing/subscriptions
operationId: subscriptions.create
requestBody: application/json → $ref: '#/components/schemas/subscription_request_post'
parameters: Prefer, PayPal-Request-Id (headers)
responses: 200, 201 → subscription
```

--------------------------------

### GET /v1/payments/payouts/{id}

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/endpoints.md

Retrieves details of a specific payout.

```APIDOC
## GET /v1/payments/payouts/{id}

### Description
Retrieves a payout by ID.

### Method
GET

### Endpoint
/v1/payments/payouts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the payout to retrieve.

### Response
#### Success Response (200)
No response schema documented.

```

--------------------------------

### List available npm scripts

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/README.md

Lists all available npm scripts in the package, including preview, bundle, lint, and code generation commands.

```bash
npm run
```

--------------------------------

### GET /v3/vault/payment-tokens

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/endpoints.md

Lists all payment tokens for the authenticated customer.

```APIDOC
## GET /v3/vault/payment-tokens

### Description
Retrieves a list of payment tokens.

### Method
GET

### Endpoint
/v3/vault/payment-tokens

### Parameters
No parameters documented.

### Response
#### Success Response (200)
No response schema documented.

```

--------------------------------

### List Products (GET /v1/catalogs/products)

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/catalog-products.md

Lists products with pagination using optional page_size, page, and total_required query parameters. Returns a product_collection containing products, total_items, total_pages, and links. Requires OAuth2 clientCredentials with the subscriptions scope.

```http
GET /v1/catalogs/products
operationId: products.list
parameters: page_size, page, total_required (query, optional)
responses: 200 → product_collection
```

--------------------------------

### GET /v2/invoicing/accounting-sync/merchant/connections

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/endpoints.md

Retrieves merchant connections for accounting sync.

```APIDOC
## [GET] /v2/invoicing/accounting-sync/merchant/connections

### Description
This endpoint retrieves merchant connections for accounting sync.

### Method
GET

### Endpoint
/v2/invoicing/accounting-sync/merchant/connections

### Response
#### Success Response (200)
Successful response.

```

--------------------------------

### GET /v2/invoicing/templates/{template_id}

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/endpoints.md

Retrieves details for a specific template.

```APIDOC
## [GET] /v2/invoicing/templates/{template_id}

### Description
This endpoint retrieves details for a specific template.

### Method
GET

### Endpoint
/v2/invoicing/templates/{template_id}

### Parameters
#### Path Parameters
- **template_id** (string) - Required - The ID of the template.

### Response
#### Success Response (200)
Successful response.

```

--------------------------------

### Create a web experience profile

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/payment-experience.md

Creates a new web experience profile using a JSON request body.

```http
POST /v1/payment-experience/web-profiles
operationId: web-profile.create
requestBody: application/json → $ref: '#/components/schemas/web_profile'
parameters: PayPal-Request-Id (header, optional)
responses: 200, 201 → web_profile
```

```bash
curl -sS -X POST https://api-m.sandbox.paypal.com/v1/payment-experience/web-profiles \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "name": "my-website-checkout",
        "presentation": { "brand_name": "My Website", "locale_code": "US" },
        "input_fields": { "no_shipping": 1 },
        "flow_config": { "user_action": "commit", "landing_page_type": "billing" } }'
```

--------------------------------

### GET /v2/invoicing/invoices

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/invoices.md

Lists invoices with pagination and field selection.

```APIDOC
## GET /v2/invoicing/invoices

### Description
Lists invoices. Returns invoice details for the authenticated user.

### Method
GET

### Endpoint
/v2/invoicing/invoices

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number to retrieve. Default: 1.
- **page_size** (integer, 1-100) - Optional - The number of invoices per page. Default: 20.
- **total_required** (boolean) - Optional - Indicates whether the total number of items is required. Default: false.
- **fields** (string, pattern `(?i)^(all|none)$`) - Optional - The fields to include in the response. Default: "all".

### Response
#### Success Response (200)
Returns an `invoices` object containing `total_items`, `total_pages`, `items` (array of `invoice`), and `links`.

#### Response Example
```json
{
  "total_items": 1,
  "total_pages": 1,
  "items": [
    {
      "id": "INV2-XXXX"
    }
  ],
  "links": []
}
```

### Error Handling
Errors: 400, 403, 500 (default no content).
```

--------------------------------

### GET /v1/billing/subscriptions/{id}

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/subscriptions.md

Retrieves details of a specific subscription.

```APIDOC
## GET /v1/billing/subscriptions/{id}

### Description
Shows details for a specific subscription. The `fields` query parameter can be used to specify which fields to return, e.g., `plan,billing_info`.

### Method
GET

### Endpoint
/v1/billing/subscriptions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The subscription ID.

#### Query Parameters
- **fields** (string) - Optional - A comma-separated list of fields to include. Min length 1, max length 100.

### Response
#### Success Response (200)
- **subscription** (object) - The subscription details.

#### Error Responses
401, 403, 404, 500.
```

--------------------------------

### Generate Java client for Orders API

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/README.md

Generates a Java client for the Orders API from the OpenAPI specification, then builds and installs the resulting artifact into the local Maven repository. Requires Node.js and Maven.

```bash
npm run codegen-java -- openapi/checkout_orders_v2.json --artifact-id orders
```

```bash
cd generated/java
```

```bash
mvn clean install
```

--------------------------------

### curl -X POST /v3/vault/payment-tokens

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/payment-method-tokens.md

Example curl command to create a payment token with a card payment source. Uses sandbox URL and Bearer token. The request body includes customer id and card details with billing address and experience context.

```bash
curl -sS -X POST https://api-m.sandbox.paypal.com/v3/vault/payment-tokens \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "customer": { "id": "customer-12345" },
    "payment_source": { "card": {
        "number": "4111111111111111", "expiry": "2027-01",
        "name": "Ada Lovelace",
        "billing_address": { "address_line_1": "123 Main St", "admin_area_2": "Austin",
                             "admin_area_1": "TX", "postal_code": "78701", "country_code": "US" },
        "experience_context": { "return_url": "https://example.com/return", "cancel_url": "https://example.com/cancel" } } }
  }'
```

--------------------------------

### GET /v2/payments/captures/{capture_id}

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/payments.md

Shows captured payment details.

```APIDOC
## GET /v2/payments/captures/{capture_id}

### Description
Shows captured payment details.

### Method
GET

### Endpoint
/v2/payments/captures/{capture_id}

### Parameters
#### Path Parameters
- **capture_id** (string) - Required - The ID of the captured payment.

### Response
#### Success Response (200)
Returns the capture object.

#### Response Example
{
  "id": "CAPTURE_ID",
  "status": "COMPLETED"
}

### Error Handling
- **401/403/404/500** - No content.
```

--------------------------------

### Generate Java client with codegen-java

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/configuration.md

Runs the codegen-java script with a spec file and artifact ID, then builds the generated Java client with Maven. The trailing spec file argument is required for scripts ending in -i and codegen-* scripts.

```bash
npm run codegen-java -- openapi/checkout_orders_v2.json --artifact-id orders
cd generated/java && mvn clean install
```

--------------------------------

### GET /v2/payments/authorizations/{authorization_id}

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/payments.md

Retrieves details of an authorization by its ID.

```APIDOC
## GET /v2/payments/authorizations/{authorization_id}

### Description
Retrieves details of an authorization by its ID.

### Method
GET

### Endpoint
/v2/payments/authorizations/{authorization_id}

### Parameters
#### Path Parameters
- **authorization_id** (string) - Required - The ID of the authorization. Max length 2147483647, pattern `^[\S\s]*$`.

#### Header Parameters
- **Authorization** (string) - Optional - Bearer token.
- **PayPal-Auth-Assertion** (string) - Optional - JWT assertion.

### Response
#### Success Response (200)
Returns `authorization-2` schema with fields: `status` (enum: `CREATED`, `CAPTURED`, `DENIED`, `PARTIALLY_CAPTURED`, `VOIDED`, `PENDING`), `status_details`, `id`, `amount`, `invoice_id`, `custom_id`, `seller_protection`, `expiration_time`, `links`.

#### Error Responses
- `401`, `403`, `404`, `500` - No content.
```

--------------------------------

### POST /v1/billing/subscriptions

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/api-reference/subscriptions.md

Creates a subscription with the specified plan and optional details.

```APIDOC
## POST /v1/billing/subscriptions

### Description
Creates a subscription. The request body must include a `plan_id`. Optional fields include `start_time`, `quantity`, `shipping_amount`, `subscriber`, `custom_id`, `application_context`, `payment_source`, and `plan`. Returns a `subscription` object with `id`, `status`, `create_time`, and `links`.

### Method
POST

### Endpoint
/v1/billing/subscriptions

### Parameters
#### Headers
- **Prefer** (string) - Optional - Preferred response format.
- **PayPal-Request-Id** (string) - Optional - A unique identifier for the request.

#### Request Body
- **plan_id** (string) - Required - The ID of the plan to subscribe to.
- **start_time** (string) - Optional - The start time of the subscription.
- **quantity** (string) - Optional - The quantity of the subscription.
- **shipping_amount** (object) - Optional - The shipping amount.
- **subscriber** (object) - Optional - The subscriber details.
- **custom_id** (string) - Optional - A custom ID.
- **application_context** (object) - Optional - Application context.
- **payment_source** (object) - Optional - Payment source.
- **plan** (object) - Optional - Plan details.

### Response
#### Success Response (200, 201)
- **id** (string) - Subscription ID.
- **status** (string) - Subscription status.
- **create_time** (string) - Creation time.
- **links** (array) - HATEOAS links.

#### Error Responses
400, 401, 403, 422, 500, default.
```

--------------------------------

### GET /v1/notifications/webhooks-lookup/{webhook_lookup_id}

Source: https://github.com/paypal/paypal-rest-api-specifications/blob/main/_autodocs/endpoints.md

Retrieves details of a webhook lookup by its ID.

```APIDOC
## GET /v1/notifications/webhooks-lookup/{webhook_lookup_id}

### Description
Shows details for a webhook lookup, by ID.

### Method
GET

### Endpoint
/v1/notifications/webhooks-lookup/{webhook_lookup_id}

### Parameters
#### Path Parameters
- **webhook_lookup_id** (string) - Required - The ID of the webhook lookup.

### Response
#### Success Response (200)
- **200** - OK

```
Tokens:
Raw