Skip to main content

PUT/payment_policy/{payment_policy_id}

This method updates an existing payment policy. Specify the policy you want to update using the payment_policy_id path parameter. Supply a complete policy payload with the updates you want to make; this call overwrites the existing policy with the new details specified in the payload.

Input

Resource URI (production)

PUT https://api.ebay.com/sell/account/v1/payment_policy/{payment_policy_id}

URI parameters

ParameterTypeDescription
payment_policy_idstringThis path parameter specifies the ID of the payment policy you want to update.

Occurrence: Required

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

In addition, this method requires you to include the Content-Type header and its value should be set to "application/json". See HTTP request headers- opens rest request components page for details.

OAuth scope

This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/sell.account

See OAuth access tokens for more information.

Request payload

Copy complete valid JSON to clipboard

Request fields

Input container/fieldTypeDescription
categoryTypesarray of CategoryType

This container is used to specify whether the payment business policy applies to motor vehicle listings, or if it applies to non-motor vehicle listings.

Occurrence: Required

categoryTypes.defaultboolean

Note: This field has been deprecated and is no longer used.

  • Do not include this field in any create or update method.
  • This field may be returned within the payload of a get method, but it can be ignored.

Occurrence: Optional

categoryTypes.nameCategoryTypeEnum

The category type to which the policy applies (motor vehicles or non-motor vehicles).

The MOTORS_VEHICLES category type is not valid for return policies. eBay flows do not support the return of motor vehicles.

Occurrence: Required

depositDeposit

This container is used if the seller wants to require an initial deposit on a motor vehicle listing. In this container, the seller sets the deposit amount and the due date for the deposit.

Because eBay controls all electronic payment methods, sellers do not need to specify a payment method and the deposit.paymentMethods array is not needed.

Note: The 'due date' specified in the deposit container will be overridden if the payment business policy requires immediate payment (in this case, for the deposit), and the buyer commits to purchase the motor vehicle through a fixed-price listing or through the 'Buy it Now' option of an auction listing.

Occurrence: Optional

deposit.amountAmount

This value indicates the initial deposit amount required from the buyer in order to purchase a motor vehicle. This value can be as high as $2,000.00 if immediate payment is not required, and up to $500.00 if immediate payment is required.

Max: 2000.0

Occurrence: Conditional

deposit.amount.currencyCurrencyCodeEnum

The base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Conditional

deposit.amount.valuestring

The monetary amount in the specified currency.

Occurrence: Conditional

deposit.dueInTimeDuration

This value indicates the number of hours that the buyer has (after they commit to buy) to pay the initial deposit on a motor vehicle. Valid dueIn times are 24, 48, and 72 hours. HOUR is set as the unit value, and 24, 48 or 72 are set in the value field.

Note: The dueIn value is overridden if the seller has set the motor vehicle listing to require immediate payment. If the listing requires immediate payment, the buyer must pay the deposit immediately in order to be eligible to purchase the motor vehicle.

Min=24 (hours)Max=72 (hours), Default=48 (hours)

Occurrence: Conditional

deposit.dueIn.unitTimeDurationUnitEnum

These enum values represent the time measurement unit, such as DAY. A span of time is defined when you apply the value specified in the value field to the value specified for unit.

See TimeDurationUnitEnum for a complete list of possible time-measurement units.

Occurrence: Conditional

deposit.dueIn.valueinteger

An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.

Occurrence: Conditional

deposit.paymentMethodsarray of PaymentMethod

This array is no longer applicable and should not be used since eBay now manages the electronic payment options available to buyers to pay the deposit.

Occurrence: Optional

deposit.paymentMethods.brandsarray of PaymentInstrumentBrandEnum

Note: This array is no longer applicable and should not be used. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods, including any credit card brands accepted.

Occurrence: Conditional

deposit.paymentMethods.paymentMethodTypePaymentMethodTypeEnum

eBay now controls all electronic payment methods available for a marketplace, so only offline payment method enum values may be used in this field, and offline payment methods will only be applicable to listings that require or support offline payments. See the PaymentMethodTypeEnum type for supported offline payment method enum values.

Occurrence: Optional

deposit.paymentMethods.recipientAccountReferenceRecipientAccountReference

Note: This container is no longer applicable and should not be used. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods, including PayPal.

Occurrence: Conditional

deposit.paymentMethods.recipientAccountReference.referenceIdstring

Note: DO NOT USE THIS FIELD. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods.

Occurrence: Optional

deposit.paymentMethods.recipientAccountReference.referenceTypeRecipientAccountReferenceTypeEnum

Note: DO NOT USE THIS FIELD. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods.

Occurrence: Optional

descriptionstring

A seller-defined description of the payment business policy. This description is only for the seller's use, and is not exposed on any eBay pages.

Max length: 250

Occurrence: Optional

fullPaymentDueInTimeDuration

This container is used to specify the number of days that a buyer has to make their full payment to the seller and close the remaining balance on a motor vehicle transaction. This container must be specified for motor vehicles listings.

The period starts when the buyer commits to buy. The valid values, as specified with TimeDuration, are:

  • 3 DAYS
  • 7 DAYS (the default)
  • 10 DAYS
  • 14 DAYS
In order for a buyer to make a full payment on a motor vehicle, at least one of the following paymentMethods values must be specified for the corresponding payment business policy:
  • CASH_ON_PICKUP
  • CASHIER_CHECK
  • MONEY_ORDER
  • PERSONAL_CHECK
Default: 7 DAYS

Occurrence: Conditional

fullPaymentDueIn.unitTimeDurationUnitEnum

These enum values represent the time measurement unit, such as DAY. A span of time is defined when you apply the value specified in the value field to the value specified for unit.

See TimeDurationUnitEnum for a complete list of possible time-measurement units.

Occurrence: Conditional

fullPaymentDueIn.valueinteger

An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.

Occurrence: Conditional

immediatePayboolean

This field should be included and set to true if the seller wants to require immediate payment from the buyer for:

  • A fixed-price item
  • An auction item where the buyer is using the 'Buy it Now' option
  • A deposit for a motor vehicle listing

Default: False

Occurrence: Optional

marketplaceIdMarketplaceIdEnum

The ID of the eBay marketplace to which this payment business policy applies.

Occurrence: Required

namestring

A seller-defined name for this payment business policy. Names must be unique for policies assigned to the same marketplace.

Max length: 64

Occurrence: Required

paymentInstructionsstring

Note: DO NOT USE THIS FIELD. Payment instructions are no longer supported by payment business policies.

A free-form string field that allows sellers to add detailed payment instructions to their listings.

Occurrence: Optional

paymentMethodsarray of PaymentMethod

Note: This field applies only when the seller needs to specify one or more offline payment methods. eBay now manages the electronic payment options available to buyers to pay for the item.

This array is used to specify one or more offline payment methods that will be accepted for payment that occurs off of eBay's platform.

Occurrence: Conditional

paymentMethods.brandsarray of PaymentInstrumentBrandEnum

Note: This array is no longer applicable and should not be used. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods, including any credit card brands accepted.

Occurrence: Conditional

paymentMethods.paymentMethodTypePaymentMethodTypeEnum

eBay now controls all electronic payment methods available for a marketplace, so only offline payment method enum values may be used in this field, and offline payment methods will only be applicable to listings that require or support offline payments. See the PaymentMethodTypeEnum type for supported offline payment method enum values.

Occurrence: Optional

paymentMethods.recipientAccountReferenceRecipientAccountReference

Note: This container is no longer applicable and should not be used. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods, including PayPal.

Occurrence: Conditional

paymentMethods.recipientAccountReference.referenceIdstring

Note: DO NOT USE THIS FIELD. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods.

Occurrence: Optional

paymentMethods.recipientAccountReference.referenceTypeRecipientAccountReferenceTypeEnum

Note: DO NOT USE THIS FIELD. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods.

Occurrence: Optional

Output

HTTP response headers

This call has no response headers.

Response payload

{ /* SetPaymentPolicyResponse */
"name" : "string",
}

Response fields

Output container/fieldTypeDescription
categoryTypesarray of CategoryType

This container indicates whether the payment business policy applies to motor vehicle listings, or if it applies to non-motor vehicle listings.

Occurrence: Always

categoryTypes.defaultboolean

Note: This field has been deprecated and is no longer used.

  • Do not include this field in any create or update method.
  • This field may be returned within the payload of a get method, but it can be ignored.

Occurrence: Conditional

categoryTypes.nameCategoryTypeEnum

The category type to which the policy applies (motor vehicles or non-motor vehicles).

The MOTORS_VEHICLES category type is not valid for return policies. eBay flows do not support the return of motor vehicles.

Occurrence: Always

depositDeposit

This container is only returned if the seller just created or updated a motor vehicles payment business policy and requires buyers to pay an initial deposit after they commit to buying a motor vehicle.

Occurrence: Conditional

deposit.amountAmount

This value indicates the initial deposit amount required from the buyer in order to purchase a motor vehicle. This value can be as high as $2,000.00 if immediate payment is not required, and up to $500.00 if immediate payment is required.

Max: 2000.0

Occurrence: Conditional

deposit.amount.currencyCurrencyCodeEnum

The base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Conditional

deposit.amount.valuestring

The monetary amount in the specified currency.

Occurrence: Conditional

deposit.dueInTimeDuration

This value indicates the number of hours that the buyer has (after they commit to buy) to pay the initial deposit on a motor vehicle. Valid dueIn times are 24, 48, and 72 hours. HOUR is set as the unit value, and 24, 48 or 72 are set in the value field.

Note: The dueIn value is overridden if the seller has set the motor vehicle listing to require immediate payment. If the listing requires immediate payment, the buyer must pay the deposit immediately in order to be eligible to purchase the motor vehicle.

Min=24 (hours)Max=72 (hours), Default=48 (hours)

Occurrence: Conditional

deposit.dueIn.unitTimeDurationUnitEnum

These enum values represent the time measurement unit, such as DAY. A span of time is defined when you apply the value specified in the value field to the value specified for unit.

See TimeDurationUnitEnum for a complete list of possible time-measurement units.

Occurrence: Conditional

deposit.dueIn.valueinteger

An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.

Occurrence: Conditional

deposit.paymentMethodsarray of PaymentMethod

This array is no longer applicable and should not be used since eBay now manages the electronic payment options available to buyers to pay the deposit.

Occurrence: Conditional

deposit.paymentMethods.brandsarray of PaymentInstrumentBrandEnum

Note: This array is no longer applicable and should not be used. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods, including any credit card brands accepted.

Occurrence: Conditional

deposit.paymentMethods.paymentMethodTypePaymentMethodTypeEnum

eBay now controls all electronic payment methods available for a marketplace, so only offline payment method enum values may be used in this field, and offline payment methods will only be applicable to listings that require or support offline payments. See the PaymentMethodTypeEnum type for supported offline payment method enum values.

Occurrence: Conditional

deposit.paymentMethods.recipientAccountReferenceRecipientAccountReference

Note: This container is no longer applicable and should not be used. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods, including PayPal.

Occurrence: Conditional

deposit.paymentMethods.recipientAccountReference.referenceIdstring

Note: DO NOT USE THIS FIELD. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods.

Occurrence: Conditional

deposit.paymentMethods.recipientAccountReference.referenceTypeRecipientAccountReferenceTypeEnum

Note: DO NOT USE THIS FIELD. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods.

Occurrence: Conditional

descriptionstring

A seller-defined description of the payment business policy. This description is only for the seller's use, and is not exposed on any eBay pages. This field is returned if set for the policy.

Max length: 250

Occurrence: Conditional

fullPaymentDueInTimeDuration

The number of days (after the buyer commits to buy) that a buyer has to pay the remaining balance of a motor vehicle transaction. Sellers can set this value to 3, 7, 10, or 14 days.

Note: This value is always returned if categoryTypes is set to MOTORS_VEHICLES.

Occurrence: Conditional

fullPaymentDueIn.unitTimeDurationUnitEnum

These enum values represent the time measurement unit, such as DAY. A span of time is defined when you apply the value specified in the value field to the value specified for unit.

See TimeDurationUnitEnum for a complete list of possible time-measurement units.

Occurrence: Conditional

fullPaymentDueIn.valueinteger

An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.

Occurrence: Conditional

immediatePayboolean

The value returned in this field will reflect the value set by the seller in the immediatePay request field. A value of true indicates that immediate payment is required from the buyer for:

  • A fixed-price item
  • An auction item where the buyer is using the 'Buy it Now' option
  • A deposit for a motor vehicle listing

It is possible for the seller to set this field as true in the payment business policy, but it will not apply in some scenarios. For example, immediate payment is not applicable for auction listings that have a winning bidder, for buyer purchases that involve the Best Offer feature, or for transactions that happen offline between the buyer and seller.

Occurrence: Always

marketplaceIdMarketplaceIdEnum

The ID of the eBay marketplace to which this payment business policy applies.

Occurrence: Always

namestring

A seller-defined name for this payment business policy. Names must be unique for policies assigned to the same marketplace.

Max length: 64

Occurrence: Always

paymentInstructionsstring

Note: NO LONGER SUPPORTED. Although this field may be returned for some older payment business policies, payment instructions are no longer supported by payment business policies. If this field is returned, it can be ignored and these payment instructions will not appear in any listings that use the corresponding business policy.

A free-form string field that allows sellers to add detailed payment instructions to their listings.

Occurrence: Conditional

paymentMethodsarray of PaymentMethod

This array shows the available payment methods that the seller has set for the payment business policy.

Sellers do not have to specify any electronic payment methods for listings, so this array will often be returned empty unless the payment business policy is intended for motor vehicle listings or other items in categories where offline payments are required or supported.

Occurrence: Always

paymentMethods.brandsarray of PaymentInstrumentBrandEnum

Note: This array is no longer applicable and should not be used. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods, including any credit card brands accepted.

Occurrence: Conditional

paymentMethods.paymentMethodTypePaymentMethodTypeEnum

eBay now controls all electronic payment methods available for a marketplace, so only offline payment method enum values may be used in this field, and offline payment methods will only be applicable to listings that require or support offline payments. See the PaymentMethodTypeEnum type for supported offline payment method enum values.

Occurrence: Conditional

paymentMethods.recipientAccountReferenceRecipientAccountReference

Note: This container is no longer applicable and should not be used. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods, including PayPal.

Occurrence: Conditional

paymentMethods.recipientAccountReference.referenceIdstring

Note: DO NOT USE THIS FIELD. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods.

Occurrence: Conditional

paymentMethods.recipientAccountReference.referenceTypeRecipientAccountReferenceTypeEnum

Note: DO NOT USE THIS FIELD. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods.

Occurrence: Conditional

paymentPolicyIdstring

A unique eBay-assigned ID for a payment business policy. This ID is generated when the policy is created.

Occurrence: Always

warningsarray of ErrorDetailV3

An array of one or more errors or warnings that were generated during the processing of the request. If there were no issues with the request, this array will return empty.

Occurrence: Always

warnings.categorystring

The category type for this error or warning. It is a string that can have one of three values:

  • Application: Indicates an exception or error occurred in the application code or at runtime. Examples include catching an exception in a service's business logic, system failures, or request errors from a dependency.
  • Business: Used when your service or a dependent service refused to continue processing on the resource because of a business rule violation such as "Seller does not ship item to Antarctica" or "Buyer ineligible to purchase an alcoholic item". Business errors are not syntactical input errors.
  • Request: Used when there is anything wrong with the request, such as authentication, syntactical errors, rate limiting or missing headers, bad HTTP header values, and so on.

Occurrence: Conditional

warnings.domainstring

Name of the domain ,or primary system, of the service or application where the error occurred.

Occurrence: Conditional

warnings.errorIdinteger

A positive integer that uniquely identifies the specific error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.

Occurrence: Conditional

warnings.inputRefIdsarray of string

Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation.

Occurrence: Conditional

warnings.longMessagestring

A more detailed explanation of the error than given in the message error field.

Occurrence: Conditional

warnings.messagestring

Information on how to correct the problem, in the end user's terms and language where applicable. Its value is at most 50 characters long. If applicable, the value is localized in the end user's requested locale.

Occurrence: Conditional

warnings.outputRefIdsarray of string

Identifies specific response elements associated with the error, if any. Path format is the same as inputRefId.

Occurrence: Conditional

warnings.parametersarray of ErrorParameterV3

This optional list of name/value pairs that contain context-specific ErrorParameter objects, with each item in the list being a parameter (or input field name) that caused an error condition. Each ErrorParameter object consists of two fields, a name and a value.

Occurrence: Conditional

warnings.parameters.namestring

Name of the parameter that caused the error.

Occurrence: Conditional

warnings.parameters.valuestring

The value of the parameter that caused the error.

Occurrence: Conditional

warnings.subdomainstring

If present, indicates the subsystem in which the error occurred.

Occurrence: Conditional

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

StatusMeaning
200OK
400Bad Request
404Not Found
500Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
20400API_ACCOUNTREQUESTInvalid request. {additionalInfo}
20401API_ACCOUNTREQUESTMissing field {fieldName}. {additionalInfo}
20402API_ACCOUNTREQUESTInvalid input. {additionalInfo}
20403API_ACCOUNTREQUESTInvalid {fieldName}. {additionalInfo}
20404API_ACCOUNTREQUEST{fieldName} not found.
20405API_ACCOUNTREQUESTInvalid payment method. {fieldName}
20500API_ACCOUNTAPPLICATIONSystem error.
20501API_ACCOUNTAPPLICATIONService unavailable. Please try again in next 24 hours.

Warnings

For more on warnings, plus the codes of other common warnings, see Handling errors.

CodeDomainCategoryMeaning
20200API_ACCOUNTBUSINESSWarning. {additionalInfo}

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Update a Payment Policy

This example updates an existing payment policy.

Input

This example updates the categoryTypes field in a payment policy, changing it to be the default policy for the ALL_EXCLUDING_MOTORS_VEHICLES category. Note that when you make this update, eBay changes the default status of the existing default policy from true to false.

When updating an existing policy, be sure to provide the entire policy object in your request payload with the changes made to the fields that you want to update. To obtain the existing policy object, call getPaymentPolicy using the ID of the policy you want to update. Use this same policy ID value in the paymentPolicyId path parameter of the PUT request.

Note that you cannot update all the fields in the policy object; for example, you cannot update the policy ID value.

PUThttps://api.sandbox.ebay.com/sell/account/v1/payment_policy/5********0

Output

A successful call returns an HTTP status code of 200 OK and a response body containing the updated payment policy.