openapi: 3.0.3
info:
title: Paypal Subscriptions Authorizations Trackers API
description: You can use billing plans and subscriptions to create subscriptions that process recurring PayPal payments for physical or digital goods, or services. A plan includes pricing and billing cycle information that defines the amount and frequency of charge for a subscription. You can also define a fixed plan, such as a $5 basic plan or a volume- or graduated-based plan with pricing tiers based on the quantity purchased. For more information, see <a href="/docs/subscriptions/">Subscriptions Overview</a>.
version: '1.6'
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: Trackers
description: Use the `/trackers` resource to update and retrieve tracking information for PayPal orders.
paths:
/v2/checkout/orders/{id}/trackers/{tracker_id}:
patch:
summary: Update or cancel tracking information for a PayPal order
description: Updates or cancels the tracking information for a PayPal order, by ID. Updatable attributes or objects:<br/><br/><table><thead><th>Attribute</th><th>Op</th><th>Notes</th></thead><tbody></tr><tr><td><code>items</code></td><td>replace</td><td>Using replace op for <code>items</code> will replace the entire <code>items</code> object with the value sent in request.</td></tr><tr><td><code>notify_payer</code></td><td>replace, add</td><td></td></tr><tr><td><code>status</code></td><td>replace</td><td>Only patching status to CANCELLED is currently supported.</td></tr></tbody></table>
operationId: orders.trackers.patch
responses:
'204':
description: A successful request returns the HTTP `204 No Content` status code with an empty object in the JSON response body.
'400':
description: Request is not well-formed, syntactically incorrect, or violates schema.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_400'
- $ref: '#/components/schemas/orders.trackers.patch-400'
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_403'
- $ref: '#/components/schemas/orders.trackers.patch-403'
'404':
description: The specified resource does not exist.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_404'
- $ref: '#/components/schemas/orders.trackers.patch-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/orders.trackers.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/id'
- $ref: '#/components/parameters/tracker_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/patch_request'
examples:
orders_patch_request:
value:
- op: replace
path: /purchase_units/@reference_id=='PUHF'/shipping/address
value:
address_line_1: 2211 N First Street
address_line_2: Building 17
admin_area_2: San Jose
admin_area_1: CA
postal_code: '95131'
country_code: US
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment
tags:
- Trackers
/v1/shipping/trackers:
post:
summary: Add tracking information for PayPal transaction
description: Adds tracking information for a PayPal transaction.
operationId: trackers.post
responses:
'200':
description: A successful request returns the HTTP 200 OK status code and a JSON response body that shows tracking information.
content:
application/json:
schema:
$ref: '#/components/schemas/tracker_identifier_collection'
default:
description: The error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
requestBody:
$ref: '#/components/requestBodies/tracker_collection'
security:
- Oauth2:
- https://uri.paypal.com/services/shipping/trackers/readwrite
tags:
- Trackers
get:
summary: Paypal List tracking information
description: Lists tracking information that meet search criteria. The tracking ID is required but the tracking number is optional.
operationId: trackers-batch.get
responses:
'200':
description: A successful request returns the HTTP 200 OK status code and a JSON response body that lists tracking information that meets search criteria.
content:
application/json:
schema:
$ref: '#/components/schemas/tracker'
default:
description: The error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
parameters:
- $ref: '#/components/parameters/transaction_id'
- $ref: '#/components/parameters/tracking_number'
- $ref: '#/components/parameters/account_id'
security:
- Oauth2:
- https://uri.paypal.com/services/shipping/trackers/read
tags:
- Trackers
/v1/shipping/trackers/{id}:
put:
summary: Update or cancel tracking information for PayPal transaction
description: Updates or cancels the tracking information for a PayPal transaction, by ID. To cancel tracking information, call this method and set the status to CANCELLED. For more information, see <a href="/docs/tracking/integrate/#update-or-cancel-tracking-information">Update or cancel tracking information</a>.
operationId: trackers.put
responses:
'204':
description: A successful request returns the HTTP 204 OK status code with no JSON response body.
default:
description: The error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
parameters:
- $ref: '#/components/parameters/id_2'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/tracker'
security:
- Oauth2:
- https://uri.paypal.com/services/shipping/trackers/readwrite
tags:
- Trackers
get:
summary: Paypal Show tracking information
description: Shows tracking information, by tracker ID, for a PayPal transaction.
operationId: trackers.get
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows tracking information.
content:
application/json:
schema:
$ref: '#/components/schemas/tracker'
default:
description: The error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
parameters:
- $ref: '#/components/parameters/id_2'
- $ref: '#/components/parameters/account_id'
security:
- Oauth2:
- https://uri.paypal.com/services/shipping/trackers/read
tags:
- Trackers
components:
schemas:
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'
tracker:
type: object
title: Tracker
description: The tracking information for a shipment.
properties:
transaction_id:
type: string
description: The PayPal transaction ID.
minLength: 1
maxLength: 50
pattern: ^[a-zA-Z0-9]*$
tracking_number:
type: string
description: The tracking number for the shipment.
minLength: 1
maxLength: 64
tracking_number_type:
description: The type of tracking number.
$ref: '#/components/schemas/tracking_number_type'
status:
$ref: '#/components/schemas/tracking_status'
shipment_date:
$ref: '#/components/schemas/date_no_time'
description: The date when the shipment occurred, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
carrier:
$ref: '#/components/schemas/carrier'
carrier_name_other:
type: string
description: The name of the carrier for the shipment. Provide this value only if the carrier parameter is OTHER.
minLength: 1
maxLength: 64
postage_payment_id:
type: string
description: The postage payment ID.
readOnly: true
minLength: 1
maxLength: 64
notify_buyer:
type: boolean
description: If true , sends an email notification to the buyer of the PayPal transaction. The email contains the tracking information that was uploaded through the API.
default: false
quantity:
type: integer
description: The quantity of items shipped.
readOnly: true
minimum: 1
maximum: 22
tracking_number_validated:
type: boolean
description: Indicates whether the carrier validated the tracking number.
readOnly: true
last_updated_time:
$ref: '#/components/schemas/date_time'
description: The date and time when the tracking information was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
shipment_direction:
type: string
description: To denote whether the shipment is sent forward to the receiver or returned back.
minLength: 1
maxLength: 50
enum:
- FORWARD
- RETURN
shipment_uploader:
readOnly: true
type: string
description: To denote which party uploaded the shipment tracking info.
minLength: 1
maxLength: 50
enum:
- MERCHANT
- CONSUMER
- PARTNER
account_id:
type: string
description: Encrypted PayPal Account ID of the buyer or seller.
readOnly: true
minLength: 13
maxLength: 13
pattern: ^[2-9A-HJ-NP-Z]{13}$
tracking_url:
type: string
format: uri
minLength: 1
maxLength: 250
description: Tracking Link of the shipment.
links:
type: array
description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).
readOnly: true
items:
$ref: '#/components/schemas/link_description'
readOnly: true
required:
- transaction_id
- status
tracking_status:
type: string
title: Tracking Status
description: The status of the item shipment. For allowed values, see <a href="/docs/tracking/reference/shipping-status/">Shipping Statuses</a>.
minLength: 1
maxLength: 64
enum:
- CANCELLED
- DELIVERED
- LOCAL_PICKUP
- ON_HOLD
- SHIPPED
- SHIPMENT_CREATED
- DROPPED_OFF
- IN_TRANSIT
- RETURNED
- LABEL_PRINTED
- ERROR
- UNCONFIRMED
- PICKUP_FAILED
- DELIVERY_DELAYED
- DELIVERY_SCHEDULED
- DELIVERY_FAILED
- INRETURN
- IN_PROCESS
- NEW
- VOID
- PROCESSED
- NOT_SHIPPED
- COMPLETED
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'
orders.trackers.patch-422:
properties:
details:
type: array
items:
anyOf:
- title: INVALID_JSON_POINTER_FORMAT
properties:
issue:
type: string
enum:
- INVALID_JSON_POINTER_FORMAT
description:
type: string
enum:
- Path should be a valid [JSON Pointer](https://tools.ietf.org/html/rfc6901) that references a location within the request where the operation is performed.
- title: NOT_PATCHABLE
properties:
issue:
type: string
enum:
- NOT_PATCHABLE
description:
type: string
enum:
- Cannot be patched.
- title: PATCH_VALUE_REQUIRED
properties:
issue:
type: string
enum:
- PATCH_VALUE_REQUIRED
description:
type: string
enum:
- Specify a `value` for the field being patched.
- title: PATCH_PATH_REQUIRED
properties:
issue:
type: string
enum:
- PATCH_PATH_REQUIRED
description:
type: string
enum:
- Specify a `value` for the field in which the operation needs to be performed.
- title: ITEM_SKU_MISMATCH
properties:
issue:
type: string
enum:
- ITEM_SKU_MISMATCH
description:
type: string
enum:
- Item sku must match one of the items sku that was provided during order creation.
tracker_identifier_collection:
type: object
title: Tracker Identifier Collection
description: The add tracking information for a PayPal transaction response details.
properties:
tracker_identifiers:
type: array
description: An array of tracking IDs.
items:
$ref: '#/components/schemas/tracker_identifier'
minItems: 1
maxItems: 100
links:
type: array
description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).
readOnly: true
items:
$ref: '#/components/schemas/link_description'
readOnly: true
link_description:
type: object
title: Link Description
description: A request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links).
required:
- href
- rel
properties:
href:
type: string
description: The complete target URL. To make the related call, combine the method with this link, in [URI template format](https://tools.ietf.org/html/rfc6570). Include the `$`, `(`, and `)` characters for pre-processing. 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
patch:
type: object
title: Patch
description: The JSON patch object to apply partial updates to resources.
properties:
op:
type: string
description: The operation.
enum:
- add
- remove
- replace
- move
- copy
- test
path:
type: string
description: The <a href="https://tools.ietf.org/html/rfc6901">JSON Pointer</a> to the target document location at which to complete the operation.
value:
title: Patch Value
description: The value to apply. The <code>remove</code>, <code>copy</code>, and <code>move</code> operations do not require a value. Since <a href="https://www.rfc-editor.org/rfc/rfc69021">JSON Patch</a> allows any type for <code>value</code>, the <code>type</code> property is not specified.
from:
type: string
description: The <a href="https://tools.ietf.org/html/rfc6901">JSON Pointer</a> to the target document location from which to move the value. Required for the <code>move</code> operation.
required:
- op
date_no_time:
type: string
description: The stand-alone date, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard `date_time` type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.
format: ppaas_date_notime_v2
minLength: 10
maxLength: 10
pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$
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_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_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
tracker_identifier:
type: object
title: Tracking Identifier
description: The tracking identifiers for a shipment.
properties:
transaction_id:
type: string
description: The PayPal transaction ID.
minLength: 1
maxLength: 50
pattern: ^[a-zA-Z0-9]*$
tracking_number:
type: string
description: The tracking number for the shipment.
minLength: 1
maxLength: 64
links:
type: array
description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).
readOnly: true
items:
$ref: '#/components/schemas/link_description'
readOnly: true
required:
- transaction_id
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
tracking_number_type:
type: string
title: Tracking Number Type
description: The tracking number type.
minLength: 1
maxLength: 64
enum:
- CARRIER_PROVIDED
- E2E_PARTNER_PROVIDED
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_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
patch_request:
type: array
title: Patch Request
description: An array of JSON patch objects to apply partial updates to resources.
items:
$ref: '#/components/schemas/patch'
link_description-2:
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
orders.trackers.patch-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.
error:
type: object
title: Error
description: The error details.
properties:
name:
type: string
description: The human-readable, unique name of the error.
message:
type: string
description: The message that describes the error.
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
information_link:
type: string
description: The information link, or URI, that shows detailed information about this error for the developer.
readOnly: true
details:
type: array
description: An array of additional details about the error.
items:
$ref: '#/components/schemas/error_details-2'
links:
type: array
description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).
readOnly: true
items:
$ref: '#/components/schemas/link_description-2'
readOnly: true
required:
- name
- message
- debug_id
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
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'
orders.trackers.patch-400:
properties:
details:
type: array
items:
anyOf:
- title: FIELD_NOT_PATCHABLE
properties:
issue:
type: string
enum:
- FIELD_NOT_PATCHABLE
description:
type: string
enum:
- Field cannot be patched.
- title: INVALID_PARAMETER_VALUE
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_VALUE
description:
type: string
enum:
- The value of a field is invalid.
- title: MISSING_REQUIRED_PARAMETER
properties:
issue:
type: string
enum:
- MISSING_REQUIRED_PARAMETER
description:
type: string
enum:
- A required field or parameter is missing.
- title: INVALID_STRING_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_LENGTH
description:
type: string
enum:
- The value of a field is either too short or too long.
- title: INVALID_PATCH_OPERATION
properties:
issue:
type: string
enum:
- INVALID_PATCH_OPERATION
description:
type: string
enum:
- The operation cannot be honored. Cannot add a property that's already present, use replace. Cannot remove a property thats not pr
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-trackers-api-openapi.yml