PayPal Catalog Products API
The PayPal Catalog Products API lets merchants create and manage product definitions used across orders, subscriptions, and invoicing.
OpenAPI Specification
openapi: 3.0.3
info:
title: Paypal Catalog Products
description: Merchants can use the Catalog Products API to create products, which are goods and services.
version: '1.0'
contact: {}
servers:
- url: https://api-m.sandbox.paypal.com
description: PayPal Sandbox Environment
- url: https://api-m.paypal.com
description: PayPal Live Environment
tags:
- name: Products
description: Use `/products` resource to create and manage products.
externalDocs:
url: https://developer.paypal.com/docs/api/catalog-products/v1/
paths:
"/v1/catalogs/products":
post:
summary: Paypal Create product
description: Creates a product.
operationId: products.create
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows product details.
content:
application/json:
schema:
"$ref": "#/components/schemas/product"
'201':
description: A successful request returns the HTTP `201 Created` status code and a JSON response body that shows product details.
content:
application/json:
schema:
"$ref": "#/components/schemas/product"
'400':
description: Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_400"
- "$ref": "#/components/schemas/products.create-400"
'401':
description: Authentication failed due to missing authorization header, or invalid authentication credentials.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_401"
- "$ref": "#/components/schemas/401"
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_403"
- "$ref": "#/components/schemas/403"
'422':
description: The requested action could not be performed, semantically incorrect, or failed business validation.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_422"
- "$ref": "#/components/schemas/422"
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
"$ref": "#/components/schemas/error_500"
default:
"$ref": "#/components/responses/default"
parameters:
- "$ref": "#/components/parameters/prefer"
- "$ref": "#/components/parameters/paypal_request_id"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/product_request_POST"
examples:
product_request_POST:
value:
name: Video Streaming Service
description: Video streaming service
type: SERVICE
category: SOFTWARE
image_url: https://example.com/streaming.jpg
home_url: https://example.com/home
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
tags:
- Products
get:
summary: Paypal List products
description: Lists products.
operationId: products.list
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that lists products with details.
content:
application/json:
schema:
"$ref": "#/components/schemas/product_collection"
'400':
description: Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_400"
- "$ref": "#/components/schemas/400"
'401':
description: Authentication failed due to missing authorization header, or invalid authentication credentials.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_401"
- "$ref": "#/components/schemas/401"
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_403"
- "$ref": "#/components/schemas/403"
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
"$ref": "#/components/schemas/error_500"
default:
"$ref": "#/components/responses/default"
parameters:
- "$ref": "#/components/parameters/page_size"
- "$ref": "#/components/parameters/page"
- "$ref": "#/components/parameters/total_required"
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
tags:
- Products
"/v1/catalogs/products/{product_id}":
get:
summary: Paypal Show product details
description: Shows details for a product, by ID.
operationId: products.get
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows product details.
content:
application/json:
schema:
"$ref": "#/components/schemas/product"
'401':
description: Authentication failed due to missing authorization header, or invalid authentication credentials.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_401"
- "$ref": "#/components/schemas/401"
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_403"
- "$ref": "#/components/schemas/403"
'404':
description: The specified resource does not exist.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_404"
- "$ref": "#/components/schemas/404"
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
"$ref": "#/components/schemas/error_500"
default:
"$ref": "#/components/responses/default"
parameters:
- "$ref": "#/components/parameters/product_id"
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
tags:
- Products
patch:
summary: Paypal Update product
description: Updates a product, by ID. You can patch these attributes and objects:<table><thead><tr><th>Attribute or object</th><th>Operations</th></tr></thead><tbody><tr><td><code>description</code></td><td>add, replace, remove</td></tr><tr><td><code>category</code></td><td>add, replace, remove</td></tr><tr><td><code>image_url</code></td><td>add, replace, remove</td></tr><tr><td><code>home_url</code></td><td>add, replace, remove</td></tr></tbody></table>
operationId: products.patch
responses:
'204':
description: A successful request returns the HTTP `204 No Content` status code with no JSON response body.
'400':
description: Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_400"
- "$ref": "#/components/schemas/products.patch-400"
'401':
description: Authentication failed due to missing authorization header, or invalid authentication credentials.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_401"
- "$ref": "#/components/schemas/401"
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_403"
- "$ref": "#/components/schemas/403"
'404':
description: The specified resource does not exist.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_404"
- "$ref": "#/components/schemas/404"
'422':
description: The requested action could not be performed, semantically incorrect, or failed business validation.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_422"
- "$ref": "#/components/schemas/products.patch-422"
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
"$ref": "#/components/schemas/error_500"
default:
"$ref": "#/components/responses/default"
parameters:
- "$ref": "#/components/parameters/product_id"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/patch_request"
examples:
patch_request:
value:
- op: replace
path: "/description"
value: Premium video streaming service
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
tags:
- Products
components:
securitySchemes:
Oauth2:
type: oauth2
description: Oauth 2.0 authentication
flows:
clientCredentials:
tokenUrl: "/v1/oauth2/token"
scopes:
https://uri.paypal.com/services/subscriptions: Create and manage products
responses:
default:
description: The default response.
content:
application/json:
schema:
"$ref": "#/components/schemas/error_default"
schemas:
'400':
properties:
details:
type: array
items:
anyOf:
- title: INVALID_PARAMETER_VALUE
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_VALUE
description:
type: string
enum:
- The value of a field is invalid.
'401':
properties:
details:
type: array
items:
anyOf:
- title: INVALID_ACCOUNT_STATUS
properties:
issue:
type: string
enum:
- INVALID_ACCOUNT_STATUS
description:
type: string
enum:
- Account validations failed for the user.
'403':
properties:
details:
type: array
items:
anyOf:
- title: PERMISSION_DENIED
properties:
issue:
type: string
enum:
- PERMISSION_DENIED
description:
type: string
enum:
- You do not have permission to access or perform operations on this resource.
'404':
properties:
details:
type: array
items:
anyOf:
- title: INVALID_RESOURCE_ID
properties:
issue:
type: string
enum:
- INVALID_RESOURCE_ID
description:
type: string
enum:
- Specified resource ID does not exist. Please check the resource ID and try again.
'422':
properties:
details:
type: array
items:
anyOf:
- title: USER_ACCOUNT_CLOSED
properties:
issue:
type: string
enum:
- USER_ACCOUNT_CLOSED
description:
type: string
enum:
- User account locked or closed.
- title: DUPLICATE_RESOURCE_IDENTIFIER
properties:
issue:
type: string
enum:
- DUPLICATE_RESOURCE_IDENTIFIER
description:
type: string
enum:
- Identifier must be unique.
- title: COUNTRY_NOT_SUPPORTED
properties:
issue:
type: string
enum:
- COUNTRY_NOT_SUPPORTED
description:
type: string
enum:
- This merchant country is not currently supported.
error_details:
title: Error Details
type: object
description: The error details. Required for client-side `4XX` errors.
properties:
field:
type: string
description: The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
value:
type: string
description: The value of the field that caused the error.
location:
"$ref": "#/components/schemas/error_location"
issue:
type: string
description: The unique, fine-grained application-level error code.
description:
type: string
description: The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.
required:
- issue
error_location:
type: string
description: The location of the field that caused the error. Value is `body`, `path`, or `query`.
enum:
- body
- path
- query
default: body
error_default:
description: The default error response.
oneOf:
- "$ref": "#/components/schemas/error_400"
- "$ref": "#/components/schemas/error_401"
- "$ref": "#/components/schemas/error_403"
- "$ref": "#/components/schemas/error_404"
- "$ref": "#/components/schemas/error_409"
- "$ref": "#/components/schemas/error_415"
- "$ref": "#/components/schemas/error_422"
- "$ref": "#/components/schemas/error_500"
- "$ref": "#/components/schemas/error_503"
error_link_description:
title: Link Description
description: The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information.
type: object
required:
- href
- rel
properties:
href:
description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
type: string
minLength: 0
maxLength: 20000
pattern: "^.*$"
rel:
description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
type: string
minLength: 0
maxLength: 100
pattern: "^.*$"
method:
description: The HTTP method required to make the related call.
type: string
minLength: 3
maxLength: 6
pattern: "^[A-Z]*$"
enum:
- GET
- POST
- PUT
- DELETE
- PATCH
error_400:
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:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_401:
type: object
title: Unauthorized Error
description: Authentication failed due to missing Authorization header, or invalid authentication credentials.
properties:
name:
type: string
enum:
- AUTHENTICATION_FAILURE
message:
type: string
enum:
- Authentication failed due to missing authorization header, or invalid authentication credentials.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_403:
type: object
title: Not Authorized Error
description: 'The client is not authorized to access this resource, although it may have valid credentials. '
properties:
name:
type: string
enum:
- NOT_AUTHORIZED
message:
type: string
enum:
- Authorization failed due to insufficient permissions.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_404:
type: object
title: Not found Error
description: The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available.
properties:
name:
type: string
enum:
- RESOURCE_NOT_FOUND
message:
type: string
enum:
- The specified resource does not exist.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_409:
type: object
title: Resource Conflict Error
description: The server has detected a conflict while processing this request.
properties:
name:
type: string
enum:
- RESOURCE_CONFLICT
message:
type: string
enum:
- The server has detected a conflict while processing this request.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_415:
type: object
title: Unsupported Media Type Error
description: The server does not support the request payload's media type.
properties:
name:
type: string
enum:
- UNSUPPORTED_MEDIA_TYPE
message:
type: string
enum:
- The server does not support the request payload's media type.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_422:
type: object
title: Unprocessable Entity Error
description: 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 response in that there are no systemic problems limiting the API from performing the request.
properties:
name:
type: string
enum:
- UNPROCESSABLE_ENTITY
message:
type: string
enum:
- The requested action could not be performed, semantically incorrect, or failed business validation.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_500:
type: object
title: Internal Server Error
description: This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server.
properties:
name:
type: string
enum:
- INTERNAL_SERVER_ERROR
message:
type: string
enum:
- An internal server error occurred.
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
example:
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
error_503:
type: object
title: Service Unavailable Error
description: The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime.
properties:
name:
type: string
enum:
- SERVICE_UNAVAILABLE
message:
type: string
enum:
- Service Unavailable.
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
example:
name: SERVICE_UNAVAILABLE
message: Service Unavailable.
debug_id: 90957fca61718
information_link: https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE
date_time:
type: string
description: The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.<blockquote><strong>Note:</strong> The regular expression provides guidance but does not reject all invalid dates.</blockquote>
format: ppaas_date_time_v3
minLength: 20
maxLength: 64
pattern: "^[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})$"
link_description:
type: object
title: Link Description
description: The request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) information.
required:
- href
- rel
properties:
href:
type: string
description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
rel:
type: string
description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
method:
type: string
description: The HTTP method required to make the related call.
enum:
- GET
- POST
- PUT
- DELETE
- HEAD
- CONNECT
- OPTIONS
- PATCH
product_collection_element:
title: Product Element
description: The details for a product in the collection response.
type: object
properties:
id:
type: string
description: The ID of the product.
minLength: 6
maxLength: 50
readOnly: true
name:
type: string
description: The product name.
minLength: 1
maxLength: 127
description:
type: string
description: The product description.
minLength: 1
maxLength: 256
create_time:
description: The date and time when the product was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
readOnly: true
"$ref": "#/components/schemas/date_time"
links:
type: array
description: An array of request-related [HATEOAS links](/docs/api/overview/#hateoas-links).
readOnly: true
items:
"$ref": "#/components/schemas/link_description"
readOnly: true
product_collection:
title: Product Collection
description: The list of products, with details.
type: object
properties:
products:
type: array
description: An array of products.
minItems: 1
maxItems: 32767
items:
"$ref": "#/components/schemas/product_collection_element"
total_items:
type: integer
description: The total number of items.
minimum: 0
maximum: 500000000
total_pages:
type: integer
description: The total number of pages.
minimum: 0
maximum: 100000000
links:
type: array
description: An array of request-related [HATEOAS links](/docs/api/overview/#hateoas-links).
readOnly: true
items:
"$ref": "#/components/schemas/link_description"
readOnly: true
product_category:
type: string
description: The product category.
title: Product Category
minLength: 4
maxLength: 256
pattern: "^[A-Z_]+$"
enum:
- AC_REFRIGERATION_REPAIR
- ACADEMIC_SOFTWARE
- ACCESSORIES
- ACCOUNTING
- ADULT
- ADVERTISING
- AFFILIATED_AUTO_RENTAL
- AGENCIES
- AGGREGATORS
- AGRICULTURAL_COOPERATIVE_FOR_MAIL_ORDER
- AIR_CARRIERS_AIRLINES
- AIRLINES
- AIRPORTS_FLYING_FIELDS
- ALCOHOLIC_BEVERAGES
- AMUSEMENT_PARKS_CARNIVALS
- ANIMATION
- ANTIQUES
- APPLIANCES
- AQUARIAMS_SEAQUARIUMS_DOLPHINARIUMS
- ARCHITECTURAL_ENGINEERING_AND_SURVEYING_SERVICES
- ART_AND_CRAFT_SUPPLIES
- ART_DEALERS_AND_GALLERIES
- ARTIFACTS_GRAVE_RELATED_AND_NATIVE_AMERICAN_CRAFTS
- ARTS_AND_CRAFTS
- ARTS_CRAFTS_AND_COLLECTIBLES
- AUDIO_BOOKS
- AUTO_ASSOCIATIONS_CLUBS
- AUTO_DEALER_USED_ONLY
- AUTO_RENTALS
- AUTO_SERVICE
- AUTOMATED_FUEL_DISPENSERS
- AUTOMOBILE_ASSOCIATIONS
- AUTOMOTIVE
- AUTOMOTIVE_REPAIR_SHOPS_NON_DEALER
- AUTOMOTIVE_TOP_AND_BODY_SHOPS
- AVIATION
- BABIES_CLOTHING_AND_SUPPLIES
- BABY
- BANDS_ORCHESTRAS_ENTERTAINERS
- BARBIES
- BATH_AND_BODY
- BATTERIES
- BEAN_BABIES
- BEAUTY
- BEAUTY_AND_FRAGRANCES
- BED_AND_BATH
- BICYCLE_SHOPS_SALES_AND_SERVICE
- BICYCLES_AND_ACCESSORIES
- BILLIARD_POOL_ESTABLISHMENTS
- BOAT_DEALERS
- BOAT_RENTALS_AND_LEASING
- BOATING_SAILING_AND_ACCESSORIES
- BOOKS
- BOOKS_AND_MAGAZINES
- BOOKS_MANUSCRIPTS
- BOOKS_PERIODICALS_AND_NEWSPAPERS
- BOWLING_ALLEYS
- BULLETIN_BOARD
- BUS_LINE
- BUS_LINES_CHARTERS_TOUR_BUSES
- BUSINESS
- BUSINESS_AND_SECRETARIAL_SCHOOLS
- BUYING_AND_SHOPPING_SERVICES_AND_CLUBS
- CABLE_SATELLITE_AND_OTHER_PAY_TELEVISION_AND_RADIO_SERVICES
- CABLE_SATELLITE_AND_OTHER_PAY_TV_AND_RADIO
- CAMERA_AND_PHOTOGRAPHIC_SUPPLIES
- CAMERAS
- CAMERAS_AND_PHOTOGRAPHY
- CAMPER_RECREATIONAL_AND_UTILITY_TRAILER_DEALERS
- CAMPING_AND_OUTDOORS
- CAMPING_AND_SURVIVAL
- CAR_AND_TRUCK_DEALERS
- CAR_AND_TRUCK_DEALERS_USED_ONLY
- CAR_AUDIO_AND_ELECTRONICS
- CAR_RENTAL_AGENCY
- CATALOG_MERCHANT
- CATALOG_RETAIL_MERCHANT
- CATERING_SERVICES
- CHARITY
- CHECK_CASHIER
- CHILD_CARE_SERVICES
- CHILDREN_BOOKS
- CHIROPODISTS_PODIATRISTS
- CHIROPRACTO
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-catalog-products-openapi-original.yml