On this page
No Headings
Comprehensive cart pricing breakdown calculated by merchant and returned in all cart responses. All fields are merchant-owned and calculated based on business logic, inventory, shipping rules, and tax regulations.
Merchant Responsibility:
Field Calculation Guidelines:
PayPal Orders API Integration: When creating PayPal orders, custom_charges are typically rolled into the handling field or added as separate line items. The total amount must match the PayPal order total for successful payment capture. Fields map to PayPal Orders API breakdown structure where supported.
objectsubtotalobjectSum of all item prices multiplied by quantities before any discounts are applied. This represents the base cost of all products in the cart.
Calculation: Σ(item.price.value × item.quantity) for all items
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
discountobjectTotal amount saved from all applied discounts, coupons, and promotions. This should be a positive value representing savings to the customer.
Includes: Coupon discounts, promotional offers, loyalty program savings, bulk discounts
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
shippingobjectCost of shipping the order to the customer's shipping address. Based on selected shipping method, package weight/dimensions, and destination.
Calculation factors: Shipping method, distance, package size, delivery speed
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
taxobjectSales tax, VAT, or other applicable taxes based on billing/shipping jurisdiction. Calculated according to local tax regulations and product tax categories.
Tax basis: Usually applied to (subtotal - discount + shipping) depending on local laws
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
handlingobjectProcessing fees, packaging costs, or handling charges for order fulfillment.
PayPal Orders API: Maps directly to the handling field in PayPal's order breakdown. Common uses: Processing fees, packaging materials, order handling costs
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
insuranceobjectOptional shipping insurance costs to protect against loss or damage during transit.
PayPal Orders API: Maps directly to the insurance field in PayPal's order breakdown. Typical usage: High-value orders, fragile items, international shipping
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
shipping_discountobjectDiscounts applied specifically to shipping costs (free shipping promotions, etc.). This should be a positive value representing shipping savings to the customer.
PayPal Orders API: Maps directly to the shipping_discount field in PayPal's order breakdown. Examples: Free shipping promotions, reduced shipping rates, shipping coupons
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
custom_chargesobjectSum of all custom charges (gift wrap, processing fees, expedited handling, etc.).
PayPal Orders API Note: This field doesn't map directly to PayPal Orders API breakdown. When creating PayPal orders, these charges are typically:
Merchants should ensure the total amount includes custom_charges for payment accuracy.
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
totalrequiredobjectFinal amount the customer will pay. This is the sum of all charges minus all discounts.
Formula: subtotal - discount + shipping + tax + handling + insurance - shipping_discount + custom_charges PayPal Orders API: Must match the total amount in the PayPal order for successful payment capture. Critical: This is the amount that will be charged to the customer's payment method.
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.