Skip to main content

POST/checkout_session/{checkoutSessionId}/apply_coupon

Important!Limited Release(Limited Release) You must be whitelisted to use this method.

This method adds a coupon to an eBay checkout session and applies it to all the eligible items in the order.

The checkoutSessionId is passed in as a URI parameter and is required. The redemption code of the coupon is in the payload and is also required.

Restrictions

  • Maximum: One coupon per order
  • For a list of supported sites and other restrictions, see API Restrictions in the Order API overview.

Input

Resource URI

POST https://apix.ebay.com/buy/order/v1/checkout_session/{checkoutSessionId}/apply_coupon

This method is supported in Sandbox environment. To access the endpoint, just replace the apix.ebay.com root URI with apix.sandbox.ebay.com

URI parameters

ParameterTypeDescription
checkoutSessionIdstringThis path parameter specifies the unique eBay-assigned session identifier for a specific eBay marketplace.

This value is returned by the initiateGuestCheckoutSession method.

Note: When using this ID, the X-EBAY-C-MARKETPLACE-ID value and developer App ID must be the same as that used when this guest checkout session was created. See Checkout session restrictions in the Buy Integration Guide for details.

Occurrence: Required

HTTP request headers

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

The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.

HeaderTypeDescription
Content-TypestringThis header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers.

Occurrence: Required

X-EBAY-C-ENDUSERCTXstringThis header is used to specify the deviceId for the device/user attempting to make the call. It contains an alphanumeric string that allows a payment gateway to track an API call attempt and confirm that it is a verified payment attempt by a device/user.

Occurrence: Conditional

X-EBAY-C-MARKETPLACE-IDstringThis header identifies the eBay marketplace where the order will occur.

Note: For this method, this value must match the X-EBAY-C-MARKETPLACE-ID used when the associated checkout session was created.
See HTTP request headers for the marketplace ID values.

Occurrence: Required

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/buy.order

eBayUser

See OAuth access tokens for more information.

Request payload

Copy complete valid JSON to clipboard

Request fields

Input container/fieldTypeDescription
redemptionCodestring

The redemption code of the coupon.

Maximum: one redemption code per order

Occurrence: Required

Output

HTTP response headers

This call has no response headers.

Response payload

{ /* CheckoutSessionResponse */
"lineItems" : [
{ /* LineItem */
"image" :
{ /* Image */ },
"itemId" : "string",
}
],
}

Response fields

Output container/fieldTypeDescription
acceptedPaymentMethodsarray of PaymentMethod

The container that returns the payment methods that can be used to purchase the items.

Occurrence: Always

acceptedPaymentMethods.labelstring

Text indicating the payment type. Credit card is the only accepted payment method for Order v1. Therefore, this value will always be CC.

Occurrence: Always

acceptedPaymentMethods.logoImageImage

The URL of the image of the payment method logo.

Occurrence: Conditional

acceptedPaymentMethods.logoImage.heightinteger

Reserved for future use.

Occurrence: Conditional

acceptedPaymentMethods.logoImage.imageUrlstring

The URL of the image.

Occurrence: Always

acceptedPaymentMethods.logoImage.widthinteger

Reserved for future use.

Occurrence: Conditional

acceptedPaymentMethods.paymentMethodBrandsarray of PaymentMethodBrand

An array of credit card brands that can be used as the payment method.

Occurrence: Always

acceptedPaymentMethods.paymentMethodBrands.logoImageImage

The URL of the payment method company (brand) image.

Occurrence: Conditional

acceptedPaymentMethods.paymentMethodBrands.logoImage.heightinteger

Reserved for future use.

Occurrence: Conditional

acceptedPaymentMethods.paymentMethodBrands.logoImage.imageUrlstring

The URL of the image.

Occurrence: Always

acceptedPaymentMethods.paymentMethodBrands.logoImage.widthinteger

Reserved for future use.

Occurrence: Conditional

acceptedPaymentMethods.paymentMethodBrands.paymentMethodBrandTypePaymentMethodBrandEnum

An enumeration value that indicates the payment method company, such as Visa.

Occurrence: Always

acceptedPaymentMethods.paymentMethodMessagesarray of PaymentMethodMessage

The type that defines the fields for legal messages and buyer consent verification.

Occurrence: Conditional

acceptedPaymentMethods.paymentMethodMessages.legalMessagestring

Information that eBay is legally obligated to show to the buyer. This field can be null, in which case do nothing. But if this field is not null, the value of this field must appear on the checkout page.

Note: This field is not used for US purchases.

Occurrence: Conditional

acceptedPaymentMethods.paymentMethodMessages.privacyPolicyWebUrlstring

Reserved for future use.

Occurrence: Conditional

acceptedPaymentMethods.paymentMethodMessages.requiredForUserConfirmationboolean

Reserved for future use.

Occurrence: Conditional

acceptedPaymentMethods.paymentMethodMessages.userAgreementWebUrlstring

Reserved for future use.

Occurrence: Conditional

acceptedPaymentMethods.paymentMethodTypePaymentMethodTypeEnum

An enumeration value that indicates the method of payment, such as credit card.

Occurrence: Always

appliedCouponsarray of Coupon

The container that returns the information of the coupons that were applied in the checkout session.

Occurrence: Conditional

appliedCoupons.redemptionCodestring

The coupon redemption code.

Occurrence: Always

checkoutSessionIdstring

The checkoutSessionId submitted in the request.

Occurrence: Always

expirationDatestring

The time the checkout session will end. To purchase the items the order must be placed before this time.

Occurrence: Always

lineItemsarray of LineItem

An array of line items associated with the checkout session.

Occurrence: Always

lineItems.addonServicesarray of CheckoutAddonService

An array of add-on services for the line item.

Occurrence: Conditional

lineItems.addonServices.selectedboolean

Indicates whether the service is selected or not.

Occurrence: Conditional

lineItems.addonServices.serviceFeeAmount

The container that returns the amount and currency of the fee for an add-on service.

Occurrence: Conditional

lineItems.addonServices.serviceFee.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

lineItems.addonServices.serviceFee.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

lineItems.addonServices.serviceIdstring

The ID of the add-on service.

Occurrence: Conditional

lineItems.addonServices.serviceTaxAmount

The container that returns the amount and currency of the sales tax applied against the add-on service fee. This tax is based on the state or territory in which the buyer is located.

Occurrence: Conditional

lineItems.addonServices.serviceTax.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

lineItems.addonServices.serviceTax.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

lineItems.addonServices.serviceTypeServiceTypeEnum

The type of add-on service, such as AUTHENTICITY_GUARANTEE.

Occurrence: Conditional

lineItems.authenticityVerificationAuthenticityVerificationProgram

This container is returned for orders that are eligible for eBay's Authenticity Guarantee service. The seller ships Authenticity Guarantee service items to the authentication partner instead of the buyer. If the item is successfully authenticated, the authenticator will ship the item to the buyer.

Occurrence: Conditional

lineItems.authenticityVerification.descriptionstring

An informational message that applies to the Authenticity Guarantee program.

Occurrence: Conditional

lineItems.authenticityVerification.outcomeReasonstring

An informational message regarding the authentication outcome of an authenticity verification inspection.
Note:This field is conditionally returned when there is information that applies to the Authenticity Guarantee program.

Occurrence: Conditional

lineItems.authenticityVerification.statusAuthenticityVerificationStatusEnum

The value in this field indicates whether the order line item has passed or failed the authenticity verification inspection, or if the inspection and/or results are still pending. The possible values returned here are PENDING, PASSED, FAILED, or INELIGIBLE.
Note: This field is conditionally returned when purchase is complete.

Occurrence: Conditional

lineItems.authenticityVerification.termsWebUrlstring

The terms and conditions that apply to the Authenticity Guarantee program.

Occurrence: Conditional

lineItems.baseUnitPriceAmount

The cost of a single item in this line item. This is the starting point for computing the price during checkout session.

Note: The price includes the value-added tax (VAT) for applicable jurisdictions when requested from supported marketplaces. In this case, users must pass the X-EBAY-C-MARKETPLACE-ID request header specifying the supported marketplace (such as EBAY_GB) to see VAT-inclusive pricing. For more information on VAT, refer to VAT Obligations in the EU.

Occurrence: Always

lineItems.baseUnitPrice.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

lineItems.baseUnitPrice.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

lineItems.feesarray of Fee

A breakdown of the fees applicable to the line item.

Occurrence: Conditional

lineItems.fees.amountAmount

A container for the currency type and monetary amount of the fees associated with the line item.

Occurrence: Conditional

lineItems.fees.amount.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

lineItems.fees.amount.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

lineItems.fees.feeTypeFeeEnum

The type of fee associated with the line item.

Occurrence: Conditional

lineItems.imageImage

An eBay-assigned URL of the item image. eBay assigns the URL when the seller uploads the image.

Occurrence: Always

lineItems.image.heightinteger

Reserved for future use.

Occurrence: Conditional

lineItems.image.imageUrlstring

The URL of the image.

Occurrence: Always

lineItems.image.widthinteger

Reserved for future use.

Occurrence: Conditional

lineItems.importDutiesAmount

The total amount of import duties for this line item, which is paid by the buyer when checking out.

Note: This is applicable only for eBay International Shipping (eIS) orders, and eIS is only available to sellers on US marketplace.

For GSP orders, the import charges will be shown in the shippingOptions.importCharges container.

Occurrence: Conditional

lineItems.importDuties.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

lineItems.importDuties.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

lineItems.itemIdstring

The eBay identifier of an item. This ID is returned by the Browse and Feed API methods. The ID must be in RESTful item ID format.

For example: v1|2**********6|5**********4 or v1|1**********9|0.

For more information about item ID for RESTful APIs, see the Legacy API compatibility.

Each itemId will become a single line item. You can have a maximum of 10 itemId(s) per checkout.

Occurrence: Always

lineItems.lineItemIdstring

A unique eBay-assigned ID value that identifies a line item in a checkout session.

Occurrence: Always

lineItems.netPriceAmount

The total cost for the items in this line item taking into account the quantity and applying any seller item discounts, such as Buy 1 Get 1, and any coupon that applies to this item.

Note: This does not include any shipping discounts, shipping costs, fees, or seller adjustments.

Occurrence: Always

lineItems.netPrice.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

lineItems.netPrice.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

lineItems.promotionsarray of Promotion

An array of promotions applied to the item of this line item.

Occurrence: Conditional

lineItems.promotions.discountAmount

The container that returns the monetary value of the promotional discount.

Note: eBay Bucks are not supported.

Occurrence: Always

lineItems.promotions.discount.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

lineItems.promotions.discount.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

lineItems.promotions.discountPercentagestring

The discount percentage for the items in this line item. For example, a seller item discount, such as Buy 1 Get 1, or a coupon. Note: The purchase order methods do not support this field.

Occurrence: Conditional

lineItems.promotions.messagestring

The text for the promotion title, which describes the promotion. For example, Buy 1 Get 1.

Occurrence: Always

lineItems.promotions.promotionCodestring

An identifier of the promotion, which was generated by the system when the promotion was created.

Note: No data is returned in this field for the getPurchaseOrder method.

Occurrence: Always

lineItems.promotions.promotionTypestring

Indicates the kind of promotion. Some examples are: SellerDiscountedPromotionalOffer and COUPON.

Occurrence: Always

lineItems.quantityinteger

The number of individual items ordered for this line item.

Note: If a winning bidder is purchasing an auction item, the value of the this field will be returned as 1.

Occurrence: Always

lineItems.sellerSeller

The container that returns the information about the seller, such as their eBay user name.

Occurrence: Always

lineItems.seller.feedbackPercentagestring

The percentage of the seller's positive feedback.

Occurrence: Always

lineItems.seller.feedbackScoreinteger

The feedback score of the seller. This value is based on the ratings from eBay members that bought items from this seller.

Occurrence: Always

lineItems.seller.sellerAccountTypestring

Indicates if the seller is a business or an individual. This is determined when the seller registers with eBay. If they register for a business account, this value will be BUSINESS. If they register for a private account, this value will be INDIVIDUAL.

This designation is required by the tax laws in some countries.

This field is returned only on the following sites.

EBAY_AT, EBAY_BE, EBAY_CH, EBAY_DE, EBAY_ES, EBAY_FR, EBAY_GB, EBAY_IE, EBAY_IT, EBAY_PL

Valid values:

  • BUSINESS
  • INDIVIDUAL
Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

lineItems.seller.usernamestring

The user name created by the seller for use on eBay.

Occurrence: Always

lineItems.shippingOptionsarray of ShippingOption

An array of the shipping methods that are available for the line item. By default, the first one will be selected.

Occurrence: Always

lineItems.shippingOptions.baseDeliveryCostAmount

The shipping cost using this shipping option, for this line item, before any shipping discounts are applied.

Note: The cost includes the value-added tax (VAT) for applicable jurisdictions when requested from supported marketplaces. In this case, users must pass the X-EBAY-C-MARKETPLACE-ID request header specifying the supported marketplace (such as EBAY_GB) to see VAT-inclusive pricing. For more information on VAT, refer to VAT Obligations in the EU.

Occurrence: Always

lineItems.shippingOptions.baseDeliveryCost.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

lineItems.shippingOptions.baseDeliveryCost.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

lineItems.shippingOptions.deliveryDiscountAmount

The monetary value of any delivery discount.

Occurrence: Always

lineItems.shippingOptions.deliveryDiscount.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

lineItems.shippingOptions.deliveryDiscount.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

lineItems.shippingOptions.ebayShippingboolean

This indicates the shipping cost of the authenticated item. The cost of the shipping will be paid to eBay.

Occurrence: Conditional

lineItems.shippingOptions.importChargesAmount

The Global Shipping Program import charges for for this line item.

Note: US sellers are transitioning from GSP to eBay International Shipping (eIS), and for any seller already transitioned to eIS, import charges will be shown in the ImportDuties container instead.

Occurrence: Conditional

lineItems.shippingOptions.importCharges.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

lineItems.shippingOptions.importCharges.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

lineItems.shippingOptions.maxEstimatedDeliveryDatestring

The end of the date range in which the purchase order is expected to be delivered to the shipping address.

Occurrence: Conditional

lineItems.shippingOptions.minEstimatedDeliveryDatestring

The beginning of the date range in which the purchase order is expected to be delivered to the shipping address.

Occurrence: Conditional

lineItems.shippingOptions.selectedboolean

Indicates if the shipping method is selected.

Occurrence: Always

lineItems.shippingOptions.shippingCarrierCodestring

The shipping provider, such as FedEx, or USPS for the line item.

Occurrence: Always

lineItems.shippingOptions.shippingOptionIdstring

A unique ID for the selected shipping option/method.

Occurrence: Always

lineItems.shippingOptions.shippingServiceCodestring

A name of a shipping type. For example, Priority Mail Express (provided by USPS) or FedEx International Priority (Provided by FedEx).

Occurrence: Always

lineItems.shortDescriptionstring

This text string is derived from the item condition, item title, and the item aspects (such as size, color, capacity, model, brand, etc.).

Occurrence: Always

lineItems.taxDetailsarray of TaxDetail

A container for the tax information for the line item.

Note: The information in this container is only returned when requested from the GB marketplace, when applicable.

Occurrence: Conditional

lineItems.taxDetails.includedInPriceboolean

A field that indicates whether tax was applied for the cost of the item and its shipping.

Occurrence: Conditional

lineItems.taxDetails.taxJurisdictionTaxJurisdiction

A container that returns the tax jurisdiction information.

Occurrence: Conditional

lineItems.taxDetails.taxJurisdiction.regionRegion

The region of the tax jurisdiction.

Occurrence: Conditional

lineItems.taxDetails.taxJurisdiction.region.regionNamestring

A localized text string that indicates the name of the region. Taxes are generally charged at the state/province level or at the country level in the case of VAT tax.

Occurrence: Conditional

lineItems.taxDetails.taxJurisdiction.region.regionTypeRegionTypeEnum

An enumeration value that indicates the type of region for the tax jurisdiction.

Valid Values:

  • STATE_OR_PROVINCE - Indicates the region is a state or province within a country, such as California or New York in the US, or Ontario or Alberta in Canada.
  • COUNTRY - Indicates the region is a single country.
Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

lineItems.taxDetails.taxJurisdiction.taxJurisdictionIdstring

The identifier of the tax jurisdiction.

Occurrence: Conditional

lineItems.taxDetails.taxTypeTaxType

A field that indicates the type of tax that may be collected for the item.

Occurrence: Conditional

lineItems.titlestring

The seller created title of the item.

Occurrence: Always

pricingSummaryPricingSummary

The container that returns information about the costs of the order, such as the total cost, discounts, etc., of all the line items.

Occurrence: Always

pricingSummary.additionalSavingsAmount

The total amount of the coupon discounts in the purchase order.

Occurrence: Conditional

pricingSummary.additionalSavings.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

pricingSummary.additionalSavings.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

pricingSummary.addonServicesFeeAmount

The total amount of fees for all add-on services among all line items. If the checkout session does not include any add-on services, this value is returned as zero.

Occurrence: Conditional

pricingSummary.addonServicesFee.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

pricingSummary.addonServicesFee.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

pricingSummary.adjustmentAdjustment

The total amount of any seller adjustments. An adjustment can be a credit or debit. This is used to catch any monetary changes to the order that are not already captured in one of the other fields.

Occurrence: Always

pricingSummary.adjustment.amountAmount

The container that returns the amount and currency of an adjustment.

Occurrence: Always

pricingSummary.adjustment.amount.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

pricingSummary.adjustment.amount.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

pricingSummary.adjustment.labelstring

Text indicating what the adjustment was for.

Occurrence: Always

pricingSummary.deliveryCostAmount

The shipping cost for all of the line items after any shipping discounts are applied.

Let's say there are four line items, and the shipping cost for each line item is $5. One of the line items qualifies for free shipping. The deliveryCost value would be $15, which is the total cost for shipping all of the line items after the discount is applied.

Occurrence: Always

pricingSummary.deliveryCost.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

pricingSummary.deliveryCost.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

pricingSummary.deliveryDiscountAmount

The total amount of the order shipping discounts for all of the line items, such as free shipping.

Let's say there are four line items, and the shipping cost for each line item is $5. One of the line items qualifies for free shipping. The deliveryDiscounts value would be 5, which is the value of the free shipping discount.

Note: This will always be a negative number.

Occurrence: Always

pricingSummary.deliveryDiscount.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

pricingSummary.deliveryDiscount.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

pricingSummary.feeAmount

The total amount of any fees for all the line items, such as a recycling fee.

Occurrence: Always

pricingSummary.fee.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

pricingSummary.fee.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

pricingSummary.importChargesAmount

The sum of all the Global Shipping Program import charges for all the line items.

Note: US sellers are transitioning from GSP to eBay International Shipping (eIS), and for any seller already transitioned to eIS, import charges will be shown in the ImportDuties container instead.

Occurrence: Conditional

pricingSummary.importCharges.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

pricingSummary.importCharges.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

pricingSummary.importDutiesAmount

The total amount of import duties for all line items, which is paid by the buyer when checking out.

Note: This is applicable only for eBay International Shipping (eIS) orders, and eIS is only available to sellers on US marketplace.

For GSP orders, the import charges will be shown in the pricingSummary.importCharges container.

Occurrence: Conditional

pricingSummary.importDuties.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

pricingSummary.importDuties.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

pricingSummary.importTaxImportTax

This container provides the type of import tax applicable to the order, and the total amount of tax for all line items in the order.

Occurrence: Conditional

pricingSummary.importTax.amountAmount

The total amount of import tax for all line items of an order.

Occurrence: Conditional

pricingSummary.importTax.amount.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

pricingSummary.importTax.amount.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

pricingSummary.importTax.importTaxTypeImportTaxTypeEnum

This enumeration value indicates the type of import tax applicable to the order. Currently, the only import tax is Goods and Services Tax (indicated by GST) which applies only to Australia and New Zealand where GST is charged to buyers outside of these two countries.

Note: Canada also charges a Goods and Services Tax. However, in this case, GST does not represent an import tax, but rather a Federal Sales Tax that is charged on most items sold. ImportTax will not be returned for Canadian sales transactions.

Occurrence: Conditional

pricingSummary.priceDiscountAmount

The total amount of all the item discounts for all line items, such as Buy 1 Get 1 free.

Let's say there were 4 line items. One of the line items qualifies for free shipping, which is $5 and two items qualify for a Buy 1 Get 1 offer, which is a $6 and a $15 discount.

The priceDiscount value would be 21, which is the total of the two Buy 1 Get 1 discounts. The shipping discount in not included. It is returned in the deliveryDiscount field.

Note: This will always be a negative number.

Occurrence: Always

pricingSummary.priceDiscount.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

pricingSummary.priceDiscount.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

pricingSummary.priceSubtotalAmount

The total amount for all the line items taking into account the item quantity but before adding in taxes and shipping costs, or applying discounts, fees, and adjustments.

Note: The price includes the value-added tax (VAT) for applicable jurisdictions when requested from supported marketplaces. In this case, users must pass the X-EBAY-C-MARKETPLACE-ID request header specifying the supported marketplace (such as EBAY_GB) to see VAT-inclusive pricing. For more information on VAT, refer to VAT Obligations in the EU.

Occurrence: Always

pricingSummary.priceSubtotal.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

pricingSummary.priceSubtotal.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

pricingSummary.taxAmount

The total amount of the taxes for all the line items.

Occurrence: Always

pricingSummary.tax.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

pricingSummary.tax.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

pricingSummary.totalAmount

The total of the purchase order.

total = priceSubtotal + priceDiscount + deliveryCost + deliveryDiscounts + tax + additionalSavings + adjustment + fee + importCharges

Note: additionalSavings, deliveryDiscounts, and priceDiscount are negative numbers.

Occurrence: Always

pricingSummary.total.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

pricingSummary.total.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

providedPaymentInstrumentProvidedPaymentInstrument

The container that returns the payment methods that can be used for the checkout. This is returned only if you have used the updatePaymentInfo method to change the payment method.

Occurrence: Conditional

providedPaymentInstrument.paymentInstrumentReferencePaymentInstrumentReference

The container that returns the payment reference, such as last four digits of a credit card.

Occurrence: Conditional

providedPaymentInstrument.paymentInstrumentReference.externalReferenceIdstring

This field is deprecated.

Occurrence: Conditional

providedPaymentInstrument.paymentInstrumentReference.lastFourDigitForCreditCardstring

The last four digits of the credit card number being used to pay for the items.

Occurrence: Conditional

providedPaymentInstrument.paymentMethodBrandPaymentMethodBrand

The container that returns the name and logo of the payment company (brand), such as Visa.

Occurrence: Conditional

providedPaymentInstrument.paymentMethodBrand.logoImageImage

The URL of the payment method company (brand) image.

Occurrence: Conditional

providedPaymentInstrument.paymentMethodBrand.logoImage.heightinteger

Reserved for future use.

Occurrence: Conditional

providedPaymentInstrument.paymentMethodBrand.logoImage.imageUrlstring

The URL of the image.

Occurrence: Always

providedPaymentInstrument.paymentMethodBrand.logoImage.widthinteger

Reserved for future use.

Occurrence: Conditional

providedPaymentInstrument.paymentMethodBrand.paymentMethodBrandTypePaymentMethodBrandEnum

An enumeration value that indicates the payment method company, such as Visa.

Occurrence: Always

providedPaymentInstrument.paymentMethodTypePaymentMethodTypeEnum

An enumeration value that indicates the method of payment, such as CREDIT_CARD.

Occurrence: Conditional

shippingAddressShippingAddress

The container that returns the address where the purchase order will be shipped.

Occurrence: Always

shippingAddress.addressLine1string

The first line of the street address where the item is being shipped.

Maximum characters:

  • AU, CA, & US: 40
  • DE & GB: 35
  • All other marketplaces: 50

Occurrence: Always

shippingAddress.addressLine2string

The second line of the street address where the item is being shipped. This optional field can be used for information such as 'Suite Number' or 'Apt Number'.

Maximum characters:

  • AU, CA, & US: 40
  • DE & GB: 35
  • All other marketplaces: 50

Occurrence: Conditional

shippingAddress.citystring

The city of the address where the item is being shipped.

Occurrence: Always

shippingAddress.countryCountryCodeEnum

The two letter code representing the country of the address.

Occurrence: Always

shippingAddress.countystring

The county of the address where the item is being shipped.

Occurrence: Conditional

shippingAddress.phoneNumberstring

The phone number of the person receiving the package.

Note: It is highly recommended that when entering the phone number you include the country code.

For example, if a US phone number is 4********4 you would enter +14********4. If you do not include this code, the service will use the country specified in the country field.

You can find the country code at https://countrycode.org.

Occurrence: Always

shippingAddress.postalCodestring

The postal code of the address where the item is being shipped.

Note: This is optional when shipping to EBAY_HK - Hong Kong (ebay.com.hk).

Occurrence: Always

shippingAddress.recipientstring

The name of the person receiving the package.

Occurrence: Always

shippingAddress.stateOrProvincestring

The state or province of the address.

Note: For the US marketplace, this is a 2 character value. For a list of these, see US State and Canada Province Codes.

Occurrence: Always

taxDetailsarray of TaxDetails

Detailed tax information for items included in this order.

Occurrence: Conditional

taxDetails.amountAmount

A container for the currency type and monetary amount of the tax item.

Occurrence: Conditional

taxDetails.amount.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

taxDetails.amount.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

taxDetails.taxClassificationTaxClassificationEnum

Specifies what the tax item pertains to, such as a tangible object (ITEM_TAX), a service (SERVICE_TAX), or shipping fees (SHIPPING_TAX).

Occurrence: Conditional

taxDetails.taxClassificationDetailsarray of TaxClassificationDetail

Provides a detailed accounting, by TaxType, of taxes collected for each item within an order.

Occurrence: Conditional

taxDetails.taxClassificationDetails.amountAmount

A container for the currency type and monetary amount of the tax collected for an item.

Occurrence: Conditional

taxDetails.taxClassificationDetails.amount.currencyCurrencyCodeEnum

The currency used in the monetary transaction. Generally, this is the currency used by the country of eBay site offering the item.

Occurrence: Always

taxDetails.taxClassificationDetails.amount.valuestring

The amount of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

taxDetails.taxClassificationDetails.taxTypeTaxType

Indicates the type of tax that has been collected for the item.

Occurrence: Conditional

warningsarray of ErrorDetailV3

An array of any process errors or warnings that were generated during the method processing.

Occurrence: Conditional

warnings.categorystring

This string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors.

Occurrence: Always

warnings.domainstring

The name of the primary system where the error occurred. This is relevant for application errors.

Occurrence: Always

warnings.errorIdinteger

A unique code that identifies the particular error or warning that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.

Occurrence: Always

warnings.inputRefIdsarray of string

An array of reference IDs that identify the specific request elements most closely associated to the error or warning, if any.

Occurrence: Conditional

warnings.longMessagestring

A detailed description of the condition that caused the error or warning, and information on what to do to correct the problem.

Occurrence: Conditional

warnings.messagestring

A description of the condition that caused the error or warning.

Occurrence: Always

warnings.outputRefIdsarray of string

An array of reference IDs that identify the specific response elements most closely associated to the error or warning, if any.

Occurrence: Conditional

warnings.parametersarray of ErrorParameterV3

An array of warning and error messages that return one or more variables contextual information about the error or warning. This is often the field or value that triggered the error or warning.

Occurrence: Conditional

warnings.parameters.namestring

This is the name of input field that caused an issue with the method request.

Occurrence: Conditional

warnings.parameters.valuestring

This is the actual value that was passed in for the element specified in the name field.

Occurrence: Conditional

warnings.subdomainstring

The name of the subdomain in which the error or warning occurred.

Occurrence: NA

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
403Access Forbidden
404Resource Not Found
409Conflict
500Internal Error

Error codes

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

CodeDomainCategoryMeaning
15000API_ORDERAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
15001API_ORDERREQUESTMissing field: {fieldName}. The indicated field is required for this request. Add the field and resubmit the call.
15002API_ORDERREQUESTInvalid field: {fieldName}. The indicated field contains an invalid value. This error can be returned due to multiple scenarios. Please refer to Order API error details for assistance on troubleshooting the issue.
15003API_ORDERREQUESTThe checkout session requested does not exist.
15019API_ORDERBUSINESSTo place an order, you must have at least one line item. Use the initiateCheckoutSession call to add line items (maximum of {maxLineItems}) and create a new checkout session.
15021API_ORDERBUSINESSThis checkout session cannot be updated because the order has already been placed.
15025API_ORDERREQUESTThe App is not authorized to access this resource.
15027API_ORDERBUSINESSThe value {fieldValue} is not supported for the {fieldName}. The supported values are: {supportedValues}.
15029API_ORDERREQUESTThe X-EBAY-C-MARKETPLACE-ID value {fieldValue} is invalid for this checkout session because it is different from the X-EBAY-C-MARKETPLACE-ID header value used to create the session. For all calls in this checkout session, you must use X-EBAY-C-MARKETPLACE-ID {supportedValues}.
16000API_ORDERBUSINESSThe coupon is not valid for any of the items in the order. The coupon was ignored and no discount was applied to this order.
16001API_ORDERBUSINESSYou cannot apply multiple coupons to the same order. No discount was applied to this order.
16002API_ORDERREQUESTThe coupon does not exist. The coupon was ignored and no discount was applied to this order.
16003API_ORDERREQUESTThe coupon has expired. No discount was applied to this order.
16004API_ORDERREQUESTThe coupon has not been activated. The coupon was ignored and no discount was applied to this order.
16005API_ORDERBUSINESSThe coupon requires the buyer to spend a specific monetary amount. This threshold has not been met. The coupon was ignored and no discount was applied to this order.
16006API_ORDERREQUESTThe coupon code is invalid. The coupon was ignored and no discount was applied to this order.
16007API_ORDERBUSINESSThis coupon has already been used. The coupon was ignored and no discount was applied to this order.
16008API_ORDERBUSINESSThis coupon is no longer valid. The coupon was ignored and no discount was applied to this order.
16009API_ORDERBUSINESSThe coupon requires the buyer to spend a specific monetary amount. This threshold has not been met. The coupon was ignored and no discount was applied to this order.
16010API_ORDERBUSINESSThe coupon is not valid for the currency being used by the items. The coupon was ignored and no discount was applied to this order.
16012API_ORDERBUSINESSThe coupon is not valid for the {fieldName}. The coupon was ignored and no discount was applied to this order.
16013API_ORDERBUSINESSThe coupon is not valid for any of the item categories in the order. The coupon was ignored and no discount was applied to this order.
16014API_ORDERBUSINESSThe coupon is not valid for the selected payment method. The coupon was ignored and no discount was applied to this order.
16015API_ORDERBUSINESSThe coupon is not valid for the selected shipping option. The coupon was ignored and no discount was applied to this order.
16016API_ORDERBUSINESSThe coupon is valid only for items that are shipped domestically. The coupon was ignored and no discount was applied to this order.
16017API_ORDERBUSINESSThe coupon is valid only for items that are shipped internationally. The coupon was ignored and no discount was applied to this order.
16018API_ORDERBUSINESSThe buyer is not eligible for this coupon. The coupon was ignored and no discount was applied to this order.
16019API_ORDERBUSINESSThe coupon is not valid for guest eBay checkouts. The coupon was ignored and no discount was applied to this order.
16020API_ORDERAPPLICATIONYour application is not eligible for this coupon. The coupon was ignored and no discount was applied to this order.
16022API_ORDERREQUESTThe coupon code is invalid. The coupon was ignored and no discount was applied to this order.
16023API_ORDERBUSINESSYou cannot apply multiple coupons to the same order. The coupon was ignored and no discount was applied to this order.
16024API_ORDERREQUESTThe coupon provided could not be applied. You may proceed with this session or provide another coupon.

Warnings

This call has no warnings.

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: Applies a Coupon to an Purchase Order

This call applies a coupon to an eBay member purchase order. Coupons are applied at the cart level.

Input

The input for this call is the checkoutSessionId and the code of the coupon.

POSThttps://apix.ebay.com/buy/order/v1/checkout_session/1*************5/apply_coupon

Output

This call returns the details of the purchase order. This includes the appliedCoupons, promotions, and additionalSavings fields that contain information specific to the coupon.