Glossary

Stripe Shipping Rate

A Stripe shipping rate is a standalone, reusable object that prices delivery, carrying its own name, fixed amount, tax behaviour and tax code, which an invoice or Checkout Session then points at rather than storing the charge as one of its line items.

Also called: shipping rate, ShippingRate, shipping cost, delivery charge

Start a free trial View Pricing

Definition

The useful thing to understand about a shipping rate is that it is a catalogue entry, not a number.

When you charge 12 dollars for ground shipping, Stripe does not write 12 dollars onto the invoice the way it writes a product line. It creates, or reuses, a ShippingRate object with its own ID, and the invoice records a pointer to it. Stripe describes the invoice field that holds it as "The details of the cost of shipping, including the ShippingRate applied on the invoice", and the pointer inside it as "The ID of the ShippingRate for this invoice".

That is the same relationship a Price has to a Product. A shipping rate is something you define once and apply many times, which is why it carries a flag for whether it is still offered rather than a flag for whether this particular sale shipped.

Everything people find surprising about shipping in Stripe follows from that one design decision. Shipping money is not in the lines collection, so anything that reads line items cannot see it. Shipping tax is decided on the rate rather than on the goods, so it can differ from everything else on the same document. And retiring a shipping option is a change to a catalogue, not a change to any invoice that already used it.

Key points

+A shipping rate is a reusable object with its own ID. An invoice points at one rather than storing the charge as a line.
+Stripe documents exactly one calculation type, fixed_amount, described as "The shipping rate is a fixed amount."
+On active: "Whether the shipping rate can be used for new purchases. Defaults to true."
+It carries its own tax_behavior: "whether the rate is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified".
+It carries its own tax code, and Stripe publishes one: "The Shipping tax code is txcd_92010001."
+The money sits in a top-level invoice field, amount_shipping, "the sum of all the shipping amounts", outside the lines collection.
+Stripe splits the shipping money three ways: amount_subtotal before tax, amount_tax, and amount_total after tax.
+Stripe has a taxability reason written specifically for shipping: a rate "calculated as a weighted average of the other line items’ rates, weighted by their amounts".
+display_name and delivery_estimate are customer-facing strings, both documented as appearing on Checkout Sessions.
+shipping_details is the delivery address, not the delivery charge. They are different fields with different jobs.

A catalogue entry, not a number on one invoice

The clearest evidence that a shipping rate is a catalogue object is the field Stripe gives it for retirement.

Stripe documents active as "Whether the shipping rate can be used for new purchases. Defaults to true." Read that carefully. The flag governs new purchases. It says nothing about the invoices that already reference this rate, because those are separate objects holding a pointer, and the pointer keeps resolving.

This is the same shape as archiving a price in a product catalogue. Yesterday’s orders keep their prices. Tomorrow’s cannot select the archived one.

The practical consequence for anyone reconciling: if you find a shipping charge on an old invoice at an amount you no longer offer, nothing has gone wrong. You are looking at a historical pointer to a rate that has since been deactivated. The amount is not stale data, it is the rate that was live when the sale happened.

It also explains a reporting frustration. Because the rate is a shared object rather than a per-sale figure, two invoices charging the same shipping do not merely happen to agree, they are pointing at the same record. If you want to know how many orders used expedited shipping, that question is answerable at the rate level, which is a different place from where you would ask it about a product.

One calculation type, and what that rules out

Stripe documents type as "The type of calculation to use on the shipping rate", which sounds like the beginning of a list. It is not. There is exactly one documented value, fixed_amount, defined as "The shipping rate is a fixed amount."

The companion field says the same thing from the other side: fixed_amount "Describes a fixed amount to charge for shipping. Must be present if type is fixed_amount."

So a shipping rate is a number you decided in advance. It is not a calculation performed at checkout against weight, dimensions, destination or a carrier’s live quote. If your business quotes real carrier rates, that quoting happens outside this object, and what reaches Stripe is the result: a fixed amount, possibly one created on the fly for that sale.

That matters for anyone reading the data later, because it changes what the field can tell you. A shipping rate records what was charged. It does not record how the figure was arrived at, what it cost you to ship, or which carrier moved the parcel. None of those are fields on the object. Shipping income and shipping expense meet in your accounting system, not in Stripe.

The two customer-facing fields are worth naming so they are not mistaken for calculation inputs. display_name is "The name of the shipping rate, meant to be displayable to the customer", and delivery_estimate is "The estimated range for how long shipping will take, meant to be displayable to the customer". Stripe notes that both appear on Checkout Sessions. They are labels shown to a buyer, not terms the price is derived from.

Its own tax identity, down to a weighted average

Shipping is taxed differently from goods in many places, sometimes taxed only when the goods are taxable, and sometimes not taxed at all. Stripe models that by giving the rate its own tax fields rather than inheriting the invoice’s.

tax_behavior specifies "whether the rate is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified". So shipping can be tax-inclusive on an invoice whose products are tax-exclusive. That is a supported configuration, not a misconfiguration.

tax_code is documented as "A tax code ID", and Stripe publishes a specific one for this purpose: "The Shipping tax code is txcd_92010001." Shipping is its own taxable category in Stripe’s tax model, not a variety of whatever it is delivering.

The detail that repays attention is how Stripe handles the case where shipping tax depends on the goods. Among the taxability reasons Stripe can attach to a calculated tax, there is one written specifically for this object: proportionally_rated, defined as the case where "The shipping cost tax rate is calculated as a weighted average of the other line items’ rates, weighted by their amounts."

That is worth reading twice. If an order contains a taxable item and an exempt one, the shipping tax rate can land somewhere between the two rates, weighted by the amounts. The resulting percentage may not equal any rate on any line of the invoice, and may not equal any rate published by any jurisdiction. It is derived from the mix of the basket.

Stripe also splits the shipping money for you rather than leaving you to compute it. The shipping cost object carries amount_subtotal, "Total shipping cost before any taxes are applied", amount_tax, "Total tax amount applied due to shipping costs. If no tax was applied, defaults to 0", and amount_total, "Total shipping cost after taxes are applied", alongside taxes, "The taxes applied to the shipping rate". If you need shipping income separate from shipping tax, the separation already exists in the data.

Cost and address are two different fields

An invoice carries shipping information in two unrelated places, and conflating them is a common source of configuration mistakes.

The money side is amount_shipping, documented simply as "This is the sum of all the shipping amounts", with the shipping cost object beside it holding the rate and the tax breakdown. Note where this sits: it is a top-level field on the invoice, not an entry in lines. Stripe’s own definition of the invoice subtotal enumerates "all subscriptions, invoice items, and prorations" and does not mention shipping, which is the same fact stated from the totals end.

The address side is shipping_details, documented as "Shipping details for the invoice", where "The Invoice PDF will use the shipping_details value if it is set, otherwise the PDF will render the shipping address from the customer".

One is what you charged for delivery. The other is where the parcel goes. They can be set independently, and a document can perfectly well carry one without the other: a delivery address with free shipping, or a shipping charge on something collected in person.

Keep them apart when configuring anything downstream. A setting that syncs a delivery address will never produce a shipping income figure, and a setting that breaks out shipping income will never populate an address field. They are answering different questions, and each one is useless as a substitute for the other.

What Acodei documents about shipping

Because shipping money is not a line item, nothing about it is decided by the rules that route line items. Acodei handles it with a dedicated setting instead.

The setting is Enable Shipping Cost Tracking, an admin toggle documented as breaking out Stripe shipping, naming the amount_shipping field specifically, "as its own line". Its stated purpose is to "Track shipping income separately". Two dependencies are documented alongside it: it "Needs designated ‘Shipping’ product", and it "relies on Stripe shipping field". That second one is the plainer restatement of everything above. The toggle reads the field the shipping rate populates, so if a sale carries no shipping amount there is nothing for it to break out.

A separate toggle, Enable Shipping Address Tracking, syncs the customer shipping address into the QuickBooks shipping fields and is documented as falling back to the billing address when the shipping address is missing. It is the address half, and it produces no income figure. If the question is what you earned on delivery, that is the other toggle.

One constraint carries over from mapping generally and is worth knowing before you set up the designated product: Acodei documents that "All QuickBooks products used in Acodei mapping must be marked as non-taxable", because "Making products Taxable in QBO conflicts with sales and payout math". The Shipping product is a product used in mapping, so it falls under that rule like any other.

Where the documentation stops is tax. A shipping rate carries its own tax behaviour and its own tax code, and can carry a proportionally rated tax that matches nothing else on the invoice. Acodei’s documentation covers how tax reaches QuickBooks in general, but it does not address shipping tax as a separate case, so we will not tell you what happens to it. Check what landed in QuickBooks against the shipping tax figure Stripe calculated, and treat any difference as something to resolve rather than something to assume.

Getting shipping onto an income account of its own runs through the same machinery as every other amount, which is how product mapping picks a QuickBooks item.

Want to see this on your own Stripe data?

Start a free trial

Frequently asked questions

What is a Stripe shipping rate?

It is a standalone object that prices delivery. It carries a display name, a fixed amount, a tax behaviour and a tax code, and it has its own ID. An invoice or Checkout Session points at it rather than storing the shipping charge as one of its line items.

Is shipping a line item in Stripe?

No. The shipping amount sits in a top-level invoice field, amount_shipping, documented as "the sum of all the shipping amounts", with a shipping cost object beside it holding the rate and the tax breakdown. Stripe’s definition of the invoice subtotal enumerates subscriptions, invoice items and prorations, and does not include shipping.

Can a Stripe shipping rate calculate postage by weight or carrier?

Not as part of this object. Stripe documents a single calculation type, fixed_amount, defined as "The shipping rate is a fixed amount", and the amount field must be present when that type is used. Any weight, dimension or carrier quoting happens before Stripe sees the figure.

Does shipping get taxed at the same rate as the products?

Not necessarily. The rate carries its own tax_behavior, "whether the rate is considered inclusive of taxes or exclusive of taxes", and its own tax code, with Stripe stating that "The Shipping tax code is txcd_92010001". Stripe also documents a proportionally rated case where the shipping tax rate is "calculated as a weighted average of the other line items’ rates, weighted by their amounts", which can produce a percentage matching no single line on the invoice.

What happens to old invoices if I deactivate a shipping rate?

Nothing. Stripe documents active as "Whether the shipping rate can be used for new purchases. Defaults to true", so deactivating governs what can be selected going forward. Invoices that already reference the rate keep pointing at it, and the amount they carry is the rate that was live at the time.

What is the difference between shipping_cost and shipping_details?

One is money and one is an address. Shipping cost is documented as "The details of the cost of shipping, including the ShippingRate applied on the invoice". Shipping details is documented as the shipping information the invoice PDF renders, falling back to the customer address when it is not set. Neither substitutes for the other.

How do I get Stripe shipping income into QuickBooks separately?

Acodei documents an admin toggle, Enable Shipping Cost Tracking, described as breaking out Stripe shipping, specifically the amount_shipping field, as its own line, so that shipping income is tracked separately. Its documented dependencies are a designated Shipping product and the presence of the Stripe shipping field on the transaction.

Does shipping tax sync to QuickBooks separately from product tax?

Acodei’s documentation does not address shipping tax as a separate case. It covers how tax reaches QuickBooks in general, but shipping carries its own tax behaviour and tax code in Stripe, and no documented statement covers how that specific figure is treated. Compare what landed in QuickBooks against the shipping tax Stripe calculated rather than assuming a behaviour.

What customers say about running Stripe through Acodei

★★★★★

“If you're testing out all the different Stripe/QuickBooks integration apps right now, let me save you some time. This one is the best one by far.”

RyanOwner at Indie Music Academy