| Attribute or object | Operations |
|---|---|
description | replace |
payment_preferences.auto_bill_outstanding | replace |
taxes.percentage | replace |
payment_preferences.payment_failure_threshold | replace |
payment_preferences.setup_fee | replace |
payment_preferences.setup_fee_failure_action | replace |
name | replace |
ACTIVE or SUSPENDED status. You can override plan level default attributes by providing customised values for plan path in the patch request.| Attribute or object | Operations |
|---|---|
billing_info.outstanding_balance | replace |
custom_id | add,replace |
plan.billing_cycles[@sequence==n]. | add,replace |
plan.billing_cycles[@sequence==n]. | replace |
plan.billing_cycles[@sequence==n]. | replace |
plan.payment_preferences. | replace |
plan.payment_preferences. | replace |
plan.taxes.inclusive | add,replace |
plan.taxes.percentage | add,replace |
shipping_amount | add,replace |
start_time | replace |
subscriber.shipping_address | add,replace |
subscriber.payment_source (for subscriptions funded | replace |
gross_amount minus the paypal_fee.",
"readOnly": true,
"$ref": "#/components/schemas/money"
}
},
"required": ["gross_amount"]
},
"application_context": {
"title": "Application Context",
"description": "The application context, which customizes the payer experience during the subscription approval process with PayPal.",
"type": "object",
"properties": {
"brand_name": {
"type": "string",
"description": "The label that overrides the business name in the PayPal account on the PayPal site.",
"minLength": 1,
"maxLength": 127,
"pattern": "^.*$"
},
"locale": {
"description": "The BCP 47-formatted locale of pages that the PayPal payment experience shows. PayPal supports a five-character code. For example, `da-DK`, `he-IL`, `id-ID`, `ja-JP`, `no-NO`, `pt-BR`, `ru-RU`, `sv-SE`, `th-TH`, `zh-CN`, `zh-HK`, or `zh-TW`.",
"$ref": "#/components/schemas/language"
},
"shipping_preference": {
"type": "string",
"description": "The location from which the shipping address is derived.",
"minLength": 1,
"maxLength": 24,
"pattern": "^[A-Z_]+$",
"default": "GET_FROM_FILE",
"x-enumDescriptions": [
{
"value": "GET_FROM_FILE",
"description": "Get the customer-provided shipping address on the PayPal site.",
"default": true
},
{
"value": "NO_SHIPPING",
"description": "Redacts the shipping address from the PayPal site. Recommended for digital goods."
},
{
"value": "SET_PROVIDED_ADDRESS",
"description": "Get the merchant-provided address. The customer cannot change this address on the PayPal site. If merchant does not pass an address, customer can choose the address on PayPal pages."
}
],
"enum": ["GET_FROM_FILE", "NO_SHIPPING", "SET_PROVIDED_ADDRESS"]
},
"user_action": {
"type": "string",
"description": "Configures the label name to `Continue` or `Subscribe Now` for subscription consent experience.",
"minLength": 1,
"maxLength": 24,
"pattern": "^[A-Z_]+$",
"default": "SUBSCRIBE_NOW",
"x-enumDescriptions": [
{
"value": "CONTINUE",
"description": "After you redirect the customer to the PayPal subscription consent page, a Continue button appears. Use this option when you want to control the activation of the subscription and do not want PayPal to activate the subscription.",
"default": true
},
{
"value": "SUBSCRIBE_NOW",
"description": "After you redirect the customer to the PayPal subscription consent page, a Subscribe Now button appears. Use this option when you want PayPal to activate the subscription."
}
],
"enum": ["CONTINUE", "SUBSCRIBE_NOW"]
},
"payment_method": {
"description": "The customer and merchant payment preferences.",
"type": "object",
"title": "Payment Method",
"properties": {
"payee_preferred": {
"$ref": "#/components/schemas/payee_payment_method_preference"
}
}
},
"return_url": {
"type": "string",
"format": "uri",
"description": "The URL where the customer is redirected after the customer approves the payment.",
"minLength": 10,
"maxLength": 4000
},
"cancel_url": {
"type": "string",
"format": "uri",
"description": "The URL where the customer is redirected after the customer cancels the payment.",
"minLength": 10,
"maxLength": 4000
}
},
"required": ["return_url", "cancel_url"]
},
"authentication_response": {
"type": "object",
"title": "Authentication Response",
"description": "Results of Authentication such as 3D Secure.",
"properties": {
"liability_shift": {
"$ref": "#/components/schemas/liability_shift"
},
"three_d_secure": {
"$ref": "#/components/schemas/three_d_secure_authentication_response"
}
}
},
"billing_cycle": {
"title": "Billing Cycle",
"description": "The billing cycle details.",
"type": "object",
"properties": {
"pricing_scheme": {
"description": "The active pricing scheme for this billing cycle. A free trial billing cycle does not require a pricing scheme.",
"$ref": "#/components/schemas/pricing_scheme"
},
"frequency": {
"description": "The frequency details for this billing cycle.",
"$ref": "#/components/schemas/frequency"
},
"tenure_type": {
"type": "string",
"description": "The tenure type of the billing cycle. In case of a plan having trial cycle, only 2 trial cycles are allowed per plan.",
"minLength": 1,
"maxLength": 24,
"pattern": "^[A-Z_]+$",
"x-enumDescriptions": [
{
"value": "REGULAR",
"description": "A regular billing cycle."
},
{
"value": "TRIAL",
"description": "A trial billing cycle."
}
],
"enum": ["REGULAR", "TRIAL"]
},
"sequence": {
"type": "integer",
"description": "The order in which this cycle is to run among other billing cycles. For example, a trial billing cycle has a `sequence` of `1` while a regular billing cycle has a `sequence` of `2`, so that trial cycle runs before the regular cycle.",
"minimum": 1,
"maximum": 99
},
"total_cycles": {
"type": "integer",
"description": "The number of times this billing cycle gets executed. Trial billing cycles can only be executed a finite number of times (value between 1 and 999 for total_cycles). Regular billing cycles can be executed infinite times (value of 0 for total_cycles) or a finite number of times (value between 1 and 999 for total_cycles).",
"minimum": 0,
"maximum": 999,
"default": 1
}
},
"required": ["frequency", "tenure_type", "sequence"]
},
"billing_cycle_list": {
"type": "array",
"description": "An array of billing cycles for trial billing and regular billing. A plan can have at most two trial cycles and only one regular cycle.",
"minItems": 1,
"maxItems": 12,
"items": {
"$ref": "#/components/schemas/billing_cycle"
}
},
"billing_cycle_override": {
"title": "Billing Cycle Override",
"description": "The billing cycle details to override at subscription level. The subscription billing cycle definition has to adhere to the plan billing cycle definition.",
"type": "object",
"properties": {
"pricing_scheme": {
"description": "The active pricing scheme for this billing cycle. A free trial billing cycle does not require a pricing scheme.",
"$ref": "#/components/schemas/pricing_scheme"
},
"sequence": {
"type": "integer",
"description": "The order in which this cycle is to run among other billing cycles. For example, a trial billing cycle has a `sequence` of `1` while a regular billing cycle has a `sequence` of `2`, so that trial cycle runs before the regular cycle.",
"minimum": 1,
"maximum": 99
},
"total_cycles": {
"type": "integer",
"description": "The number of times this billing cycle gets executed. Trial billing cycles can only be executed a finite number of times (value between 1 and 999 for total_cycles). Regular billing cycles can be executed infinite times (value of 0 for total_cycles) or a finite number of times (value between 1 and 999 for total_cycles).",
"minimum": 0,
"maximum": 999
}
},
"required": ["sequence"]
},
"billing_cycle_override_list": {
"type": "array",
"description": "An array of billing cycles for trial billing and regular billing. The subscription billing cycle definition has to adhere to the plan billing cycle definition.",
"minItems": 1,
"maxItems": 12,
"items": {
"$ref": "#/components/schemas/billing_cycle_override"
}
},
"bin_details": {
"type": "object",
"title": "Bin Details",
"description": "Bank Identification Number (BIN) details used to fund a payment.",
"properties": {
"bin": {
"type": "string",
"description": "The Bank Identification Number (BIN) signifies the number that is being used to identify the granular level details (except the PII information) of the card.",
"pattern": "^[0-9]+$",
"maxLength": 25,
"minLength": 1
},
"issuing_bank": {
"type": "string",
"description": "The issuer of the card instrument.",
"minLength": 1,
"maxLength": 64
},
"bin_country_code": {
"description": "The [two-character ISO-3166-1 country code](/docs/integration/direct/rest/country-codes/) of the bank.",
"$ref": "#/components/schemas/country_code-2"
},
"products": {
"$ref": "#/components/schemas/products_list"
}
}
},
"card_attributes": {
"type": "object",
"title": "Card Attributes",
"description": "Additional attributes associated with the use of this card.",
"properties": {
"customer": {
"$ref": "#/components/schemas/customer"
},
"vault": {
"description": "Instruction to vault the card based on the specified strategy.",
"$ref": "#/components/schemas/vault_instruction_base"
},
"verification": {
"description": "Instruction to optionally verify the card based on the specified strategy.",
"$ref": "#/components/schemas/card_verification"
}
}
},
"card_attributes_response": {
"type": "object",
"title": "Card Attributes Response",
"description": "Additional attributes associated with the use of this card.",
"properties": {
"vault": {
"$ref": "#/components/schemas/vault_response"
}
}
},
"card_brand": {
"type": "string",
"title": "Card Brand",
"description": "The card network or brand. Applies to credit, debit, gift, and payment cards.",
"minLength": 1,
"maxLength": 255,
"pattern": "^[A-Z_]+$",
"x-enumDescriptions": [
{
"value": "VISA",
"description": "Visa card."
},
{
"value": "MASTERCARD",
"description": "Mastecard card."
},
{
"value": "DISCOVER",
"description": "Discover card."
},
{
"value": "AMEX",
"description": "American Express card."
},
{
"value": "SOLO",
"description": "Solo debit card."
},
{
"value": "JCB",
"description": "Japan Credit Bureau card."
},
{
"value": "STAR",
"description": "Military Star card."
},
{
"value": "DELTA",
"description": "Delta Airlines card."
},
{
"value": "SWITCH",
"description": "Switch credit card."
},
{
"value": "MAESTRO",
"description": "Maestro credit card."
},
{
"value": "CB_NATIONALE",
"description": "Carte Bancaire (CB) credit card."
},
{
"value": "CONFIGOGA",
"description": "Configoga credit card."
},
{
"value": "CONFIDIS",
"description": "Confidis credit card."
},
{
"value": "ELECTRON",
"description": "Visa Electron credit card."
},
{
"value": "CETELEM",
"description": "Cetelem credit card."
},
{
"value": "CHINA_UNION_PAY",
"description": "China union pay credit card."
},
{
"value": "DINERS",
"description": "The Diners Club International banking and payment services capability network owned by Discover Financial Services (DFS), one of the most recognized brands in US financial services."
},
{
"value": "ELO",
"description": "The Brazilian Elo card payment network."
},
{
"value": "HIPER",
"description": "The Hiper - Ingenico ePayment network."
},
{
"value": "HIPERCARD",
"description": "The Brazilian Hipercard payment network that's widely accepted in the retail market."
},
{
"value": "RUPAY",
"description": "The RuPay payment network."
},
{
"value": "GE",
"description": "The GE Credit Union 3Point card payment network."
},
{
"value": "SYNCHRONY",
"description": "The Synchrony Financial (SYF) payment network."
},
{
"value": "UNKNOWN",
"description": "UNKNOWN payment network."
}
],
"enum": [
"VISA",
"MASTERCARD",
"DISCOVER",
"AMEX",
"SOLO",
"JCB",
"STAR",
"DELTA",
"SWITCH",
"MAESTRO",
"CB_NATIONALE",
"CONFIGOGA",
"CONFIDIS",
"ELECTRON",
"CETELEM",
"CHINA_UNION_PAY",
"DINERS",
"ELO",
"HIPER",
"HIPERCARD",
"RUPAY",
"GE",
"SYNCHRONY",
"UNKNOWN"
]
},
"card_brand_list": {
"type": "array",
"description": "Array of brands or networks associated with the card.",
"readOnly": true,
"minItems": 1,
"maxItems": 256,
"items": {
"$ref": "#/components/schemas/card_brand"
}
},
"card_from_request": {
"type": "object",
"title": "Card from Request",
"description": "Representation of card details as received in the request.",
"properties": {
"expiry": {
"description": "The card expiration year and month, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6).",
"$ref": "#/components/schemas/date_year_month"
},
"last_digits": {
"type": "string",
"description": "The last digits of the payment card.",
"pattern": "[0-9]{2,}",
"minLength": 2,
"maxLength": 4,
"readOnly": true
}
}
},
"card_response": {
"type": "object",
"title": "Card Response",
"description": "The payment card to use to fund a payment. Card can be a credit or debit card.",
"properties": {
"name": {
"type": "string",
"description": "The card holder's name as it appears on the card.",
"minLength": 2,
"maxLength": 300
},
"last_digits": {
"type": "string",
"description": "The last digits of the payment card.",
"pattern": "[0-9]{2,}",
"readOnly": true
},
"brand": {
"description": "The card brand or network. Typically used in the response.",
"readOnly": true,
"$ref": "#/components/schemas/card_brand"
},
"available_networks": {
"$ref": "#/components/schemas/card_brand_list"
},
"type": {
"description": "The payment card type.",
"$ref": "#/components/schemas/card_type"
},
"authentication_result": {
"$ref": "#/components/schemas/authentication_response"
},
"attributes": {
"$ref": "#/components/schemas/card_attributes_response"
},
"from_request": {
"$ref": "#/components/schemas/card_from_request"
},
"expiry": {
"description": "The card expiration year and month, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6).",
"$ref": "#/components/schemas/date_year_month"
},
"bin_details": {
"description": "Bank Identification Number (BIN) details used to fund a payment.",
"$ref": "#/components/schemas/bin_details"
}
}
},
"card_response_with_billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/card_response"
},
{
"properties": {
"name": {
"type": "string",
"description": "The card holder's name as it appears on the card.",
"minLength": 2,
"maxLength": 300
},
"billing_address": {
"description": "The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute).",
"type": "object",
"title": "Portable Postal Address (Medium-Grained)",
"properties": {
"address_line_1": {
"type": "string",
"description": "The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address.",
"maxLength": 300
},
"address_line_2": {
"type": "string",
"description": "The second line of the address, for example, a suite or apartment number.",
"maxLength": 300
},
"admin_area_2": {
"type": "string",
"description": "A city, town, or village. Smaller than `admin_area_level_1`.",
"maxLength": 120
},
"admin_area_1": {
"type": "string",
"description": "The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is:Note: The country code for Great Britain is", "format": "ppaas_common_country_code_v2", "maxLength": 2, "minLength": 2, "pattern": "^([A-Z]{2}|C2)$" }, "country_code-2": { "type": "string", "description": "The [two-character ISO 3166-1 code](/api/rest/reference/country-codes/) that identifies the country or region.GBand notUKas used in the top-level domain names for that country. Use the `C2` country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
Note: The country code for Great Britain is", "format": "ppaas_common_country_code_v2", "maxLength": 2, "minLength": 2, "pattern": "^([A-Z]{2}|C2)$" }, "currency_code": { "description": "The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency.", "type": "string", "format": "ppaas_common_currency_code_v2", "minLength": 3, "maxLength": 3 }, "customer": { "type": "object", "title": "Customer Information", "description": "The details about a customer in PayPal's system of record.", "properties": { "id": { "$ref": "#/components/schemas/merchant_partner_customer_id" }, "email_address": { "description": "Email address of the buyer as provided to the merchant or on file with the merchant. Email Address is required if you are processing the transaction using PayPal Guest Processing which is offered to select partners and merchants. For all other use cases we do not expect partners/merchant to send email_address of their customer.", "$ref": "#/components/schemas/email" }, "phone": { "description": "The phone number of the buyer as provided to the merchant or on file with the merchant. The `phone.phone_number` supports only `national_number`.", "$ref": "#/components/schemas/phone_with_type" } } }, "cycle_execution": { "title": "Billing Cycle Execution Details", "description": "The regular and trial execution details for a billing cycle.", "type": "object", "properties": { "tenure_type": { "type": "string", "description": "The type of the billing cycle.", "minLength": 1, "maxLength": 24, "pattern": "^[A-Z_]+$", "x-enumDescriptions": [ { "value": "REGULAR", "description": "A regular billing cycle." }, { "value": "TRIAL", "description": "A trial billing cycle." } ], "readOnly": true, "enum": ["REGULAR", "TRIAL"] }, "sequence": { "type": "integer", "description": "The order in which to run this cycle among other billing cycles.", "minimum": 0, "maximum": 99 }, "cycles_completed": { "type": "integer", "description": "The number of billing cycles that have completed.", "minimum": 0, "maximum": 9999, "readOnly": true }, "cycles_remaining": { "type": "integer", "description": "For a finite billing cycle, cycles_remaining is the number of remaining cycles. For an infinite billing cycle, cycles_remaining is set as 0.", "minimum": 0, "maximum": 9999, "readOnly": true }, "current_pricing_scheme_version": { "type": "integer", "description": "The active pricing scheme version for the billing cycle.", "minimum": 1, "maximum": 99, "readOnly": true }, "total_cycles": { "type": "integer", "description": "The number of times this billing cycle gets executed. Trial billing cycles can only be executed a finite number of times (value betweenGBand notUKas used in the top-level domain names for that country. Use the `C2` country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
1 and 999 for total_cycles). Regular billing cycles can be executed infinite times (value of 0 for total_cycles) or a finite number of times (value between 1 and 999 for total_cycles).",
"minimum": 0,
"maximum": 999,
"readOnly": true
}
},
"required": ["tenure_type", "sequence", "cycles_completed"]
},
"cycle_execution_list": {
"type": "array",
"description": "The trial and regular billing executions.",
"minItems": 0,
"maxItems": 3,
"items": {
"$ref": "#/components/schemas/cycle_execution"
},
"readOnly": true
},
"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.Note: The regular expression provides guidance but does not reject all invalid dates.", "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})$" }, "date_year_month": { "type": "string", "description": "The year and month, in ISO-8601 `YYYY-MM` date format. See [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "minLength": 7, "maxLength": 7, "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$" }, "definitions-link_description_list": { "type": "array", "description": "An array of request-related HATEOAS links.", "readOnly": true, "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/link_description" } }, "email": { "type": "string", "description": "The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the", "format": "merchant_common_email_address_v2", "maxLength": 254, "minLength": 3, "pattern": "(?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*|(?:[\\x01-\\x08\\x0b\\x0c\\x0e-\\x1f\\x21\\x23-\\x5b\\x5d-\\x7f]|\\[\\x01-\\x09\\x0b\\x0c\\x0e-\\x7f])*\")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\\x01-\\x08\\x0b\\x0c\\x0e-\\x1f\\x21-\\x5a\\x53-\\x7f]|\\[\\x01-\\x09\\x0b\\x0c\\x0e-\\x7f])+)\\])" }, "email_address": { "type": "string", "description": "The internationalized email address.@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the", "format": "ppaas_common_email_address_v2", "minLength": 3, "maxLength": 254, "pattern": "^(?:[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*|\"(?:[\\x01-\\x08\\x0b\\x0c\\x0e-\\x1f\\x21\\x23-\\x5b\\x5d-\\x7f]|\\\\[\\x01-\\x09\\x0b\\x0c\\x0e-\\x7f])*\")@(?:(?:[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\\.)+[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?|\\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[A-Za-z0-9-]*[A-Za-z0-9]:(?:[\\x01-\\x08\\x0b\\x0c\\x0e-\\x1f\\x21-\\x5a\\x53-\\x7f]|\\\\[\\x01-\\x09\\x0b\\x0c\\x0e-\\x7f])+)\\])$" }, "enrolled": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[0-9A-Z_]+$", "description": "Status of Authentication eligibility.", "x-enumDescriptions": [ { "value": "Y", "description": "Yes. The bank is participating in 3-D Secure protocol and will return the ACSUrl." }, { "value": "N", "description": "No. The bank is not participating in 3-D Secure protocol." }, { "value": "U", "description": "Unavailable. The DS or ACS is not available for authentication at the time of the request." }, { "value": "B", "description": "Bypass. The merchant authentication rule is triggered to bypass authentication." } ], "enum": ["Y", "N", "U", "B"] }, "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" } }, "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_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_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_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" }, "failed_payment_details": { "title": "Failed Payment Details", "description": "The details for the failed payment of the subscription.", "type": "object", "properties": { "amount": { "description": "The failed payment amount.", "readOnly": true, "$ref": "#/components/schemas/money" }, "time": { "description": "The date and time when the failed payment was made, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "readOnly": true, "$ref": "#/components/schemas/date_time" }, "reason_code": { "type": "string", "description": "The reason code for the payment failure.", "minLength": 1, "maxLength": 120, "pattern": "^[A-Z_]+$", "x-enumDescriptions": [ { "value": "PAYMENT_DENIED", "description": "PayPal declined the payment due to one or more customer issues." }, { "value": "INTERNAL_SERVER_ERROR", "description": "An internal server error has occurred." }, { "value": "PAYEE_ACCOUNT_RESTRICTED", "description": "The payee account is not in good standing and cannot receive payments." }, { "value": "PAYER_ACCOUNT_RESTRICTED", "description": "The payer account is not in good standing and cannot make payments." }, { "value": "PAYER_CANNOT_PAY", "description": "Payer cannot pay for this transaction." }, { "value": "SENDING_LIMIT_EXCEEDED", "description": "The transaction exceeds the payer's sending limit." }, { "value": "TRANSACTION_RECEIVING_LIMIT_EXCEEDED", "description": "The transaction exceeds the receiver's receiving limit." }, { "value": "CURRENCY_MISMATCH", "description": "The transaction is declined due to a currency mismatch." } ], "readOnly": true, "enum": [ "PAYMENT_DENIED", "INTERNAL_SERVER_ERROR", "PAYEE_ACCOUNT_RESTRICTED", "PAYER_ACCOUNT_RESTRICTED", "PAYER_CANNOT_PAY", "SENDING_LIMIT_EXCEEDED", "TRANSACTION_RECEIVING_LIMIT_EXCEEDED", "CURRENCY_MISMATCH" ] }, "next_payment_retry_time": { "description": "The time when the retry attempt for the failed payment occurs, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "readOnly": true, "$ref": "#/components/schemas/date_time" } }, "required": ["amount", "time"] }, "frequency": { "title": "Billing Cycle Frequency", "description": "The frequency of the billing cycle.", "type": "object", "properties": { "interval_unit": { "type": "string", "description": "The interval at which the subscription is charged or billed.", "minLength": 1, "maxLength": 24, "pattern": "^[A-Z_]+$", "x-enumDescriptions": [ { "value": "DAY", "description": "A daily billing cycle." }, { "value": "WEEK", "description": "A weekly billing cycle." }, { "value": "MONTH", "description": "A monthly billing cycle." }, { "value": "YEAR", "description": "A yearly billing cycle." } ], "enum": ["DAY", "WEEK", "MONTH", "YEAR"] }, "interval_count": { "type": "integer", "description": "The number of intervals after which a subscriber is billed. For example, if the `interval_unit` is `DAY` with an `interval_count` of `2`, the subscription is billed once every two days. The following table lists the maximum allowed values for the `interval_count` for each `interval_unit`:@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
Interval unit | Maximum interval count |
|---|---|
DAY | 365 |
WEEK | 52 |
MONTH | 12 |
YEAR | 1 |
value parameter defines the value to add. For more information, see 4.1. add."
},
{
"value": "remove",
"description": "Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove."
},
{
"value": "replace",
"description": "Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace."
},
{
"value": "move",
"description": "Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move."
},
{
"value": "copy",
"description": "Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy."
},
{
"value": "test",
"description": "Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:| Type | Considered equal if both values |
|---|---|
| strings | Contain the same number of Unicode characters and their code points are byte-by-byte equal. |
| numbers | Are numerically equal. |
| arrays | Contain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules. |
| objects | Contain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules). |
literals (false, true, and null) | Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant. |
remove, copy, and move operations do not require a value. Since JSON Patch allows any type for value, the type property is not specified."
},
"from": {
"type": "string",
"description": "The JSON Pointer to the target document location from which to move the value. Required for the move operation."
}
},
"required": ["op"]
},
"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"
}
},
"payee_payment_method_preference": {
"type": "string",
"description": "The merchant-preferred payment methods.",
"minLength": 1,
"maxLength": 255,
"pattern": "^[0-9A-Z_]+$",
"default": "UNRESTRICTED",
"x-enumDescriptions": [
{
"value": "UNRESTRICTED",
"description": "Accepts any type of payment from the customer.",
"default": true
},
{
"value": "IMMEDIATE_PAYMENT_REQUIRED",
"description": "Accepts only immediate payment from the customer. For example, credit card, PayPal balance, or instant ACH. Ensures that at the time of capture, the payment does not have the `pending` status."
}
],
"enum": ["UNRESTRICTED", "IMMEDIATE_PAYMENT_REQUIRED"]
},
"payer_base": {
"type": "object",
"title": "Payer Base",
"description": "The customer who approves and pays for the order. The customer is also known as the payer.",
"properties": {
"email_address": {
"description": "The email address of the payer.",
"$ref": "#/components/schemas/email"
},
"payer_id": {
"description": "The PayPal-assigned ID for the payer.",
"readOnly": true,
"$ref": "#/components/schemas/account_id"
}
}
},
"payment_preferences": {
"title": "Payment Preferences",
"description": "The payment preferences for a subscription.",
"type": "object",
"properties": {
"auto_bill_outstanding": {
"type": "boolean",
"description": "Indicates whether to automatically bill the outstanding amount in the next billing cycle.",
"default": true
},
"setup_fee": {
"description": "The initial set-up fee for the service.",
"$ref": "#/components/schemas/money"
},
"setup_fee_failure_action": {
"type": "string",
"description": "The action to take on the subscription if the initial payment for the setup fails.",
"minLength": 1,
"maxLength": 24,
"pattern": "^[A-Z_]+$",
"default": "CANCEL",
"x-enumDescriptions": [
{
"value": "CONTINUE",
"description": "Continues the subscription if the initial payment for the setup fails."
},
{
"value": "CANCEL",
"description": "Cancels the subscription if the initial payment for the setup fails."
}
],
"enum": ["CONTINUE", "CANCEL"]
},
"payment_failure_threshold": {
"type": "integer",
"description": "The maximum number of payment failures before a subscription is suspended. For example, if `payment_failure_threshold` is `2`, the subscription automatically updates to the `SUSPEND` state if two consecutive payments fail.",
"minimum": 0,
"maximum": 999,
"default": 0
}
}
},
"payment_preferences_override": {
"title": "Payment Preferences Override",
"description": "The payment preferences to override at subscription level.",
"type": "object",
"properties": {
"auto_bill_outstanding": {
"type": "boolean",
"description": "Indicates whether to automatically bill the outstanding amount in the next billing cycle."
},
"setup_fee": {
"description": "The initial set-up fee for the service.",
"$ref": "#/components/schemas/money"
},
"setup_fee_failure_action": {
"type": "string",
"description": "The action to take on the subscription if the initial payment for the setup fails.",
"minLength": 1,
"maxLength": 24,
"pattern": "^[A-Z_]+$",
"x-enumDescriptions": [
{
"value": "CONTINUE",
"description": "Continues the subscription if the initial payment for the setup fails."
},
{
"value": "CANCEL",
"description": "Cancels the subscription if the initial payment for the setup fails."
}
],
"enum": ["CONTINUE", "CANCEL"]
},
"payment_failure_threshold": {
"type": "integer",
"description": "The maximum number of payment failures before a subscription is suspended. For example, if `payment_failure_threshold` is `2`, the subscription automatically updates to the `SUSPEND` state if two consecutive payments fail.",
"minimum": 0,
"maximum": 999
}
}
},
"payment_source": {
"type": "object",
"title": "Payment Source",
"description": "The payment source definition. To be eligible to create subscription using debit or credit card, you will need to sign up here (https://www.paypal.com/bizsignup/entry/product/ppcp). Please note, its available only for non-3DS cards and for merchants in US and AU regions.",
"properties": {
"card": {
"type": "object",
"title": "Card",
"description": "The payment card to use to fund a payment. Can be a credit or debit card.",
"properties": {
"name": {
"type": "string",
"description": "The card holder's name as it appears on the card.",
"maxLength": 300,
"minLength": 1,
"pattern": "^.{1,300}$"
},
"number": {
"type": "string",
"description": "The primary account number (PAN) for the payment card.",
"pattern": "^[0-9]{13,19}$",
"minLength": 13,
"maxLength": 19
},
"expiry": {
"description": "The card expiration year and month, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6).",
"$ref": "#/components/schemas/date_year_month"
},
"security_code": {
"type": "string",
"description": "The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID. This parameter cannot be present in the request when `payment_initiator=MERCHANT`.",
"pattern": "^[0-9]{3,4}$",
"minLength": 3,
"maxLength": 4
},
"type": {
"description": "The payment card type.",
"$ref": "#/components/schemas/card_type"
},
"brand": {
"description": "The card brand or network. Typically used in the response.",
"$ref": "#/components/schemas/card_brand"
},
"billing_address": {
"description": "The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute).",
"type": "object",
"title": "Portable Postal Address (Medium-Grained)",
"properties": {
"address_line_1": {
"type": "string",
"description": "The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address.",
"maxLength": 300
},
"address_line_2": {
"type": "string",
"description": "The second line of the address, for example, a suite or apartment number.",
"maxLength": 300
},
"admin_area_2": {
"type": "string",
"description": "A city, town, or village. Smaller than `admin_area_level_1`.",
"maxLength": 120
},
"admin_area_1": {
"type": "string",
"description": "The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is:status.details."
},
{
"value": "REFUNDED",
"description": "An amount greater than or equal to this captured payment's amount was refunded to the payer."
},
{
"value": "FAILED",
"description": "There was an error while capturing payment."
}
],
"readOnly": true,
"enum": [
"COMPLETED",
"DECLINED",
"PARTIALLY_REFUNDED",
"PENDING",
"REFUNDED",
"FAILED"
]
},
"id": {
"type": "string",
"description": "The PayPal-generated transaction ID.",
"minLength": 3,
"maxLength": 50,
"readOnly": true
},
"amount_with_breakdown": {
"$ref": "#/components/schemas/amount_with_breakdown"
},
"payer_name": {
"description": "The name of the customer.",
"readOnly": true,
"$ref": "#/components/schemas/name"
},
"payer_email": {
"description": "The email ID of the customer.",
"readOnly": true,
"$ref": "#/components/schemas/email_address"
},
"time": {
"description": "The date and time when the transaction was processed, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).",
"readOnly": true,
"$ref": "#/components/schemas/date_time"
}
},
"required": ["id", "amount_with_breakdown", "time"]
},
"transaction_list": {
"type": "array",
"description": "An array of transactions.",
"minItems": 0,
"maxItems": 32767,
"items": {
"$ref": "#/components/schemas/transaction"
}
},
"transactions_list": {
"title": "List Transactions",
"description": "The list transactions for a subscription request details.",
"type": "object",
"properties": {
"transactions": {
"$ref": "#/components/schemas/transaction_list"
},
"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": {
"$ref": "#/components/schemas/link_description_list"
}
}
},
"update_pricing_scheme_request": {
"title": "Update Pricing Scheme",
"description": "The update pricing scheme request details.",
"type": "object",
"properties": {
"billing_cycle_sequence": {
"type": "integer",
"description": "The billing cycle sequence.",
"minimum": 1,
"maximum": 99
},
"pricing_scheme": {
"$ref": "#/components/schemas/pricing_scheme"
}
},
"required": ["billing_cycle_sequence", "pricing_scheme"]
},
"update_pricing_scheme_request_list": {
"type": "array",
"description": "An array of pricing schemes.",
"minItems": 1,
"maxItems": 99,
"items": {
"$ref": "#/components/schemas/update_pricing_scheme_request"
}
},
"update_pricing_schemes_list_request": {
"title": "Update Pricing Scheme Request",
"description": "The update pricing scheme request details.",
"type": "object",
"properties": {
"pricing_schemes": {
"$ref": "#/components/schemas/update_pricing_scheme_request_list"
}
},
"required": ["pricing_schemes"]
},
"vault_instruction_base": {
"type": "object",
"title": "Vault Instruction Base",
"description": "Basic vault instruction specification that can be extended by specific payment sources that supports vaulting.",
"properties": {
"store_in_vault": {
"$ref": "#/components/schemas/store_in_vault_instruction"
}
}
},
"vault_response": {
"type": "object",
"title": "Vault Response",
"description": "The details about a saved payment source.",
"properties": {
"id": {
"type": "string",
"description": "The PayPal-generated ID for the saved payment source.",
"minLength": 1,
"maxLength": 255
},
"status": {
"title": "Vault Status",
"type": "string",
"description": "The vault status.",
"minLength": 1,
"maxLength": 255,
"pattern": "^[0-9A-Z_]+$",
"x-enumDescriptions": [
{
"value": "VAULTED",
"description": "The payment source has been saved in your customer's vault. This vault status reflects `/v3/vault` status."
},
{
"value": "CREATED",
"description": "DEPRECATED. The payment source has been saved in your customer's vault. This status applies to deprecated integration patterns and will not be returned for v3/vault integrations."
},
{
"value": "APPROVED",
"description": "Customer has approved the action of saving the specified payment_source into their vault. Use v3/vault/payment-tokens with given setup_token to save the payment source in the vault"
}
],
"deprecated": true,
"enum": ["VAULTED", "CREATED", "APPROVED"]
},
"customer": {
"type": "object",
"title": "Customer Information",
"description": "The details about a customer in PayPal's system of record.",
"properties": {
"id": {
"$ref": "#/components/schemas/merchant_partner_customer_id"
}
}
},
"links": {
"$ref": "#/components/schemas/definitions-link_description_list"
}
}
}
},
"parameters": {
"prefer": {
"name": "Prefer",
"in": "header",
"description": "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.