{"files":{"SKILL.md":"---\nname: orders\ndescription: \"Orders API skill. Use when working with Orders for checkout. Covers 9 endpoints.\"\nversion: 1.0.0\ngenerator: lapsh\n---\n\n# Orders\nAPI version: 2.32\n\n## Auth\nOAuth2\n\n## Base URL\nhttps://api-m.paypal.com\n\n## Setup\n1. Configure auth: OAuth2\n2. GET /v2/checkout/orders/{id} -- show order details\n3. POST /v2/checkout/orders -- create first order\n\n## Endpoints\n9 endpoints across 1 group. See references/api-spec.lap for full details.\n\n### Checkout\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /v2/checkout/orders | Create order |\n| GET | /v2/checkout/orders/{id} | Show order details |\n| PATCH | /v2/checkout/orders/{id} | Update order |\n| POST | /v2/checkout/orders/{id}/confirm-payment-source | Confirm the Order |\n| POST | /v2/checkout/orders/{id}/authorize | Authorize payment for order |\n| POST | /v2/checkout/orders/{id}/capture | Capture payment for order |\n| POST | /v2/checkout/orders/{id}/track | Add tracking information for an Order. |\n| PATCH | /v2/checkout/orders/{id}/trackers/{tracker_id} | Update or cancel tracking information for an order |\n| POST | /v2/checkout/orders/order-update-callback | Receive updated order information via callback URL |\n\n## Common Questions\nMatch user requests to endpoints in references/api-spec.lap. Key patterns:\n- \"Create a order?\" -> POST /v2/checkout/orders\n- \"Get order details?\" -> GET /v2/checkout/orders/{id}\n- \"Partially update a order?\" -> PATCH /v2/checkout/orders/{id}\n- \"Create a confirm-payment-source?\" -> POST /v2/checkout/orders/{id}/confirm-payment-source\n- \"Create a authorize?\" -> POST /v2/checkout/orders/{id}/authorize\n- \"Create a capture?\" -> POST /v2/checkout/orders/{id}/capture\n- \"Create a track?\" -> POST /v2/checkout/orders/{id}/track\n- \"Partially update a tracker?\" -> PATCH /v2/checkout/orders/{id}/trackers/{tracker_id}\n- \"Create a order-update-callback?\" -> POST /v2/checkout/orders/order-update-callback\n- \"How to authenticate?\" -> See Auth section above\n\n## Response Tips\n- Check response schemas in references/api-spec.lap for field details\n- Create/update endpoints return the modified resource on success\n- Error responses include status codes and descriptions in the spec\n\n## References\n- Full spec: See references/api-spec.lap for complete endpoint details, parameter tables, and response schemas\n\n> Generated from the official API spec by [LAP](https://lap.sh)\n","references/api-spec.lap":"@lap v0.3\n# Machine-readable API spec. Each @endpoint block is one API call.\n@api Orders\n@base https://api-m.paypal.com\n@version 2.32\n@auth OAuth2\n@common_fields {Authorization: str # Holds authorization information for external API calls.}\n@endpoints 9\n@toc checkout(9)\n\n@endpoint POST /v2/checkout/orders\n@desc Create order\n@required {intent: str(CAPTURE/AUTHORIZE) # The intent to either capture payment immediately or authorize a payment for an order after order creation., purchase_units: [any] # An array of purchase units. Each purchase unit establishes a contract between a payer and the payee. Each purchase unit represents either a full or partial order that the payer intends to purchase from the payee.}\n@optional {PayPal-Request-Id: str # The server stores keys for 6 hours. The API callers can request the times to up to 72 hours by speaking to their Account Manager. It is mandatory for all single-step create order calls (E.g. Create Order Request with payment source information like Card, PayPal.vault_id, PayPal.billing_agreement_id, etc)., PayPal-Partner-Attribution-Id: str # PayPal Partner can send a PayPal-Partner-Attribution-Id request header with the value that they have been assigned by the PayPal Partner program. This value is known as a BN Code. In order to reward such partners (through partner programs), all the activities (including API calls) that they are doing on behalf of the merchants need to be tracked., PayPal-Client-Metadata-Id: str # A GUID value originating from Fraudnet and Dyson passed from external API clients via HTTP header. The value is used by Risk decisions to correlate calls which, in turn, might result in lower decline rates.., Prefer: str=return=minimal # The preferred server response upon successful completion of the request. Value is:return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.return=representation. The server returns a complete resource representation, including the current state of the resource., PayPal-Auth-Assertion: str # Header for an API client-provided JWT assertion that identifies the merchant. Establishing the consent to act-on-behalf of a merchant is a prerequisite for using this header., payer: any, payment_source: map{card: map, token: map, paypal: any, bancontact: any, blik: any, eps: any, giropay: any, ideal: any, mybank: any, p24: any, sofort: any, trustly: any, apple_pay: any, google_pay: any, venmo: any, crypto: any} # The payment source definition., application_context: any}\n@returns(200) A successful response to an idempotent request returns the HTTP `200 OK` status code with a JSON response body that shows order details.\n@returns(201) A successful request returns the HTTP `201 Created` status code and a JSON response body that includes by default a minimal response with the ID, status, and HATEOAS links. If you require the complete order resource representation, you must pass the Prefer: return=representation request header. This header value is not the default.\n@returns(202) The request has been accepted for processing, but the processing has not been completed yet. The server returns the HTTP `202 Accepted` status code to indicate that the request is valid and will be handled asynchronously.\n@errors {400: Request is not well-formed, syntactically incorrect, or violates schema., 401: Unauthorized., 403: Forbidden., 422: The requested action could not be performed, semantically incorrect, or failed business validation., 500: Internal Server Error.}\n@example_request {\"payment_source\":{\"paypal\":{\"experience_context\":{\"payment_method_preference\":\"IMMEDIATE_PAYMENT_REQUIRED\",\"landing_page\":\"LOGIN\",\"shipping_preference\":\"GET_FROM_FILE\",\"user_action\":\"PAY_NOW\",\"return_url\":\"https://example.com/returnUrl\",\"cancel_url\":\"https://example.com/cancelUrl\"}}},\"purchase_units\":[{\"invoice_id\":\"90210\",\"amount\":{\"currency_code\":\"USD\",\"value\":\"230.00\",\"breakdown\":{\"item_total\":{\"currency_code\":\"USD\",\"value\":\"220.00\"},\"shipping\":{\"currency_code\":\"USD\",\"value\":\"10.00\"}}},\"items\":[{\"name\":\"T-Shirt\",\"description\":\"Super Fresh Shirt\",\"unit_amount\":{\"currency_code\":\"USD\",\"value\":\"20.00\"},\"quantity\":\"1\",\"category\":\"PHYSICAL_GOODS\",\"sku\":\"sku01\",\"image_url\":\"https://example.com/static/images/items/1/tshirt_green.jpg\",\"url\":\"https://example.com/url-to-the-item-being-purchased-1\",\"upc\":{\"type\":\"UPC-A\",\"code\":\"123456789012\"}},{\"name\":\"Shoes\",\"description\":\"Running, Size 10.5\",\"sku\":\"sku02\",\"unit_amount\":{\"currency_code\":\"USD\",\"value\":\"100.00\"},\"quantity\":\"2\",\"category\":\"PHYSICAL_GOODS\",\"image_url\":\"https://example.com/static/images/items/1/shoes_running.jpg\",\"url\":\"https://example.com/url-to-the-item-being-purchased-2\",\"upc\":{\"type\":\"UPC-A\",\"code\":\"987654321012\"}}]}]}\n\n@endpoint GET /v2/checkout/orders/{id}\n@desc Show order details\n@required {id: str # The ID of the order for which to show details.}\n@optional {PayPal-Auth-Assertion: str # Header for an API client-provided JWT assertion that identifies the merchant. Establishing the consent to act-on-behalf of a merchant is a prerequisite for using this header., fields: str # A comma-separated list of fields that should be returned for the order. Valid filter field is `payment_source`.}\n@returns(200) A successful request returns the HTTP `200 OK` status code and a JSON response body that shows order details.\n@errors {401: Unauthorized., 403: Forbidden., 404: Not Found., 500: Internal Server Error.}\n\n@endpoint PATCH /v2/checkout/orders/{id}\n@desc Update order\n@required {id: str # The ID of the order to update.}\n@optional {PayPal-Auth-Assertion: str # Header for an API client-provided JWT assertion that identifies the merchant. Establishing the consent to act-on-behalf of a merchant is a prerequisite for using this header.}\n@returns(204) No Content.\n@errors {400: Request is not well-formed, syntactically incorrect, or violates schema., 401: Unauthorized., 403: Forbidden., 404: Not Found., 422: The requested action could not be performed, semantically incorrect, or failed business validation., 500: Internal Server Error.}\n@example_request [{\"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\"}}]\n\n@endpoint POST /v2/checkout/orders/{id}/confirm-payment-source\n@desc Confirm the Order\n@required {id: str # The ID of the order for which the payer confirms their intent to pay., payment_source: map{card: map, token: map, paypal: any, bancontact: any, blik: any, eps: any, giropay: any, ideal: any, mybank: any, p24: any, sofort: any, trustly: any, apple_pay: any, google_pay: any, venmo: any, crypto: any} # The payment source definition.}\n@optional {PayPal-Client-Metadata-Id: str # A GUID value originating from Fraudnet and Dyson passed from external API clients via HTTP header. The value is used by Risk decisions to correlate calls which, in turn, might result in lower decline rates.., PayPal-Auth-Assertion: str # Header for an API client-provided JWT assertion that identifies the merchant. Establishing the consent to act-on-behalf of a merchant is a prerequisite for using this header., Prefer: str=return=minimal # The preferred server response upon successful completion of the request. Value is:return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.return=representation. The server returns a complete resource representation, including the current state of the resource., application_context: map{brand_name: str, locale: any, return_url: str(uri), cancel_url: str(uri), stored_payment_source: map} # Customizes the payer confirmation experience.}\n@returns(200) A successful request indicates that the payment source was added to the Order. A successful request returns the HTTP `200 OK` status code with a JSON response body that shows order details.\n@errors {400: Request is not well-formed, syntactically incorrect, or violates schema., 401: Unauthorized., 403: Forbidden., 422: The requested action could not be performed, semantically incorrect, or failed business validation., 500: Internal Server Error.}\n@example_request {\"payment_source\":{\"paypal\":{\"name\":{\"given_name\":\"John\",\"surname\":\"Doe\"},\"email_address\":\"customer@example.com\",\"experience_context\":{\"payment_method_preference\":\"IMMEDIATE_PAYMENT_REQUIRED\",\"brand_name\":\"EXAMPLE INC\",\"locale\":\"en-US\",\"landing_page\":\"LOGIN\",\"shipping_preference\":\"SET_PROVIDED_ADDRESS\",\"user_action\":\"PAY_NOW\",\"return_url\":\"https://example.com/returnUrl\",\"cancel_url\":\"https://example.com/cancelUrl\"}}}}\n\n@endpoint POST /v2/checkout/orders/{id}/authorize\n@desc Authorize payment for order\n@required {id: str # The ID of the order for which to authorize.}\n@optional {PayPal-Request-Id: str # The server stores keys for 6 hours. The API callers can request the times to up to 72 hours by speaking to their Account Manager. It is mandatory for all single-step create order calls (E.g. Create Order Request with payment source information like Card, PayPal.vault_id, PayPal.billing_agreement_id, etc)., Prefer: str=return=minimal # The preferred server response upon successful completion of the request. Value is:return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.return=representation. The server returns a complete resource representation, including the current state of the resource., PayPal-Client-Metadata-Id: str # A GUID value originating from Fraudnet and Dyson passed from external API clients via HTTP header. The value is used by Risk decisions to correlate calls which, in turn, might result in lower decline rates.., PayPal-Auth-Assertion: str # Header for an API client-provided JWT assertion that identifies the merchant. Establishing the consent to act-on-behalf of a merchant is a prerequisite for using this header., payment_source: any}\n@returns(200) A successful response to an idempotent request returns the HTTP `200 OK` status code with a JSON response body that shows authorized payment details.\n@returns(201) A successful response to a non-idempotent request returns the HTTP `201 Created` status code with a JSON response body that shows authorized payment details. If a duplicate response is retried, returns the HTTP `200 OK` status code. By default, the response is minimal. If you need the complete resource representation, you must pass the Prefer: return=representation request header.\n@returns(202) The request has been accepted for processing, but the processing has not been completed yet. The server returns the HTTP `202 Accepted` status code to indicate that the request is valid and will be handled asynchronously.\n@returns(207) The request was successfully processed, but the result contains mixed outcomes. When an order includes multiple purchase units, the server returns the HTTP `207 Multi-Status` code to indicate that one or more purchase units were processed successfully while others failed. The response body provides the processing result for each purchase unit.\n@errors {400: Request is not well-formed, syntactically incorrect, or violates schema., 401: Unauthorized., 403: Forbidden., 404: Not Found., 409: The request could not be completed due to a conflict with the current state of the resource. The HTTP `409 Conflict` status code is returned when the requested operation is not allowed because the order or one or more purchase units are in a state that prevents the operation., 422: The requested action could not be performed, semantically incorrect, or failed business validation., 500: Internal Server Error.}\n@example_request {}\n\n@endpoint POST /v2/checkout/orders/{id}/capture\n@desc Capture payment for order\n@required {id: str # The ID of the order for which to capture a payment.}\n@optional {PayPal-Request-Id: str # The server stores keys for 6 hours. The API callers can request the times to up to 72 hours by speaking to their Account Manager. It is mandatory for all single-step create order calls (E.g. Create Order Request with payment source information like Card, PayPal.vault_id, PayPal.billing_agreement_id, etc)., Prefer: str=return=minimal # The preferred server response upon successful completion of the request. Value is:return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.return=representation. The server returns a complete resource representation, including the current state of the resource., PayPal-Client-Metadata-Id: str # A GUID value originating from Fraudnet and Dyson passed from external API clients via HTTP header. The value is used by Risk decisions to correlate calls which, in turn, might result in lower decline rates.., PayPal-Auth-Assertion: str # Header for an API client-provided JWT assertion that identifies the merchant. Establishing the consent to act-on-behalf of a merchant is a prerequisite for using this header., payment_source: any}\n@returns(200) A successful response to an idempotent request returns the HTTP `200 OK` status code with a JSON response body that shows captured payment details.\n@returns(201) A successful response to a non-idempotent request returns the HTTP `201 Created` status code with a JSON response body that shows captured payment details. If a duplicate response is retried, returns the HTTP `200 OK` status code. By default, the response is minimal. If you need the complete resource representation, pass the Prefer: return=representation request header.\n@returns(202) The request has been accepted for processing, but the processing has not been completed yet. The server returns the HTTP `202 Accepted` status code to indicate that the request is valid and will be handled asynchronously.\n@returns(207) The request was successfully processed, but the result contains mixed outcomes. When an order includes multiple purchase units, the server returns the HTTP `207 Multi-Status` code to indicate that one or more purchase units were processed successfully while others failed. The response body provides the processing result for each purchase unit.\n@errors {400: Request is not well-formed, syntactically incorrect, or violates schema., 401: Unauthorized., 403: Forbidden., 404: Not Found., 409: The request could not be completed due to a conflict with the current state of the resource. The HTTP `409 Conflict` status code is returned when the requested operation is not allowed because the order or one or more purchase units are in a state that prevents the operation., 422: The requested action could not be performed, semantically incorrect, or failed business validation., 500: Internal Server Error.}\n@example_request {}\n\n@endpoint POST /v2/checkout/orders/{id}/track\n@desc Add tracking information for an Order.\n@required {id: str # The ID of the order that the tracking information is associated with.}\n@optional {PayPal-Auth-Assertion: str # Header for an API client-provided JWT assertion that identifies the merchant. Establishing the consent to act-on-behalf of a merchant is a prerequisite for using this header.}\n@returns(200) A successful response to an idempotent request returns the HTTP `200 OK` status code with a JSON response body that shows tracker details.\n@returns(201) A successful response to a non-idempotent request returns the HTTP `201 Created` status code with a JSON response body that shows tracker details. If a duplicate response is retried, returns the HTTP `200 OK` status code.\n@errors {400: Request is not well-formed, syntactically incorrect, or violates schema., 401: Unauthorized., 403: Forbidden., 404: Not Found., 422: The requested action could not be performed, semantically incorrect, or failed business validation., 500: Internal Server Error.}\n@example_request {\"capture_id\":\"8MC585209K746392H\",\"tracking_number\":\"443844607820\",\"notify_payer\":false,\"items\":[{\"name\":\"T-Shirt\",\"sku\":\"sku02\",\"quantity\":\"1\",\"upc\":{\"type\":\"UPC-A\",\"code\":\"012345678901\"},\"image_url\":\"https://www.example.com/example.jpg\",\"url\":\"https://www.example.com/example\"}]}\n\n@endpoint PATCH /v2/checkout/orders/{id}/trackers/{tracker_id}\n@desc Update or cancel tracking information for an order\n@required {id: str # The ID of the order that the tracking information is associated with., tracker_id: str # The order tracking ID.}\n@optional {PayPal-Auth-Assertion: str # Header for an API client-provided JWT assertion that identifies the merchant. Establishing the consent to act-on-behalf of a merchant is a prerequisite for using this header.}\n@returns(204) No Content.\n@errors {400: Request is not well-formed, syntactically incorrect, or violates schema., 401: Unauthorized., 403: Forbidden., 404: Not Found., 422: The requested action could not be performed, semantically incorrect, or failed business validation., 500: Internal Server Error.}\n@example_request [{\"op\":\"add\",\"path\":\"/notify_payer\",\"value\":true}]\n\n@endpoint POST /v2/checkout/orders/order-update-callback\n@desc Receive updated order information via callback URL\n@required {purchase_units: [any] # An array of purchase units. At present only 1 purchase_unit is supported. Each purchase unit establishes a contract between a payer and the payee. Each purchase unit represents either a full or partial order that the payer intends to purchase from the payee.}\n@optional {id: str # The ID of the order., shipping_address: any, shipping_option: any}\n@returns(200) {id: str} # The callback to merchant was successful.\n@errors {400: The request is not well-formed, is syntactically incorrect, or violates the schema., 401: Unauthorized., 403: Forbidden., 422: The requested action could not be completed, was semantically incorrect, or failed business validation., 500: Internal Server Error.}\n@example_request {\"id\":\"5O190127TN364715T\",\"shipping_address\":{\"country_code\":\"US\",\"admin_area_1\":\"TX\",\"admin_area_2\":\"Dallas\",\"postal_code\":\"75001\"},\"purchase_units\":[{\"reference_id\":\"d9f80740-38f0-11e8-b467-0ed5f89f718b\",\"amount\":{\"currency_code\":\"USD\",\"value\":\"100.00\",\"breakdown\":{\"item_total\":{\"currency_code\":\"USD\",\"value\":\"90.00\"},\"tax_total\":{\"currency_code\":\"USD\",\"value\":\"10.00\"},\"shipping\":{\"currency_code\":\"USD\",\"value\":\"0.00\"}}},\"items\":[{\"name\":\"T-Shirt\",\"description\":\"Green XL\",\"sku\":\"sku01\",\"unit_amount\":{\"currency_code\":\"USD\",\"value\":\"90.00\"},\"tax\":{\"currency_code\":\"USD\",\"value\":\"10.00\"},\"quantity\":\"1\",\"category\":\"PHYSICAL_GOODS\"}]}]}\n\n@end\n"}}