{"data":{"id":"orders-api/how-it-works","type":"route","relationships":{"page":{"data":{"id":"CU5gIgymJFByAqhSH8v0f","type":"doc-page"}}}},"included":[{"id":"6zcP4ecFNM2f6GXXixBLHE","type":"markdown-block","attributes":{"name":"Orders API : How It Works : Intro","markdown":"Take a deeper look at the Orders API.\n\n{TOC depth=h3}","programming-language":"All","platform":"All"},"relationships":{"constant-sets":{"data":[]}}},{"id":"4UkKLkk9395WJIFV93vWJj","type":"markdown-block","attributes":{"name":"Orders API : How it Works : Data model","markdown":"## Orders objects and data types\n\n### Orders\n\nThe entire Orders API is built around the `Order` object. Line items, taxes, discounts, and fulfillments are all defined at the order level. \n\n```json copy_code\n{\n \"idempotency_key\": \"UNIQUE_REQUEST_KEY\",\n \"reference_id\": \"my-coffee-order-001\",\n \"line_items\": [\n {\n \"name\": \"Coffee\",\n \"quantity\": \"1\",\n \"base_price_money\": {\n \"amount\": 200,\n \"currency\": \"USD\"\n }\n }\n ],\n \"fulfillments\": [\n {\n \"type\": \"PICKUP\",\n \"state\": \"PROPOSED\",\n \"pickup_details\": {\n \"recipient\": {\n \"display_name\": \"Amelia Earhart\",\n \"email_address\": \"Amelia.Earhart@example.com\",\n \"phone_number\": \"1-212-555-4240\"\n },\n \"expires_at\": \"2019-02-14T20:21:54.859Z\",\n \"auto_complete_duration\": \"P0DT1H0S\",\n \"schedule_type\": \"SCHEDULED\",\n \"pickup_at\": \"2019-02-14T19:21:54.859Z\",\n \"pickup_window_duration\": \"PT1H0S\",\n \"prep_time_duration\": \"PT20M\",\n \"note\": \"Pour over coffee\"\n }\n }\n ]\n }'\n```\n\n### Line items\n\nLine items can be built in two ways:\n\n* By referencing a catalog item ID.\n* By defining the line item ad hoc.\n\nYou can define line items by simply referencing a catalog item by its `catalog_object_id`. Referencing the `catalog_object_id` automatically pulls details about the catalog item into your order and automatically updates your inventory when the order is closed or charged. \n\nYou can also create a line item ad hoc (for example, if you do not have a `catalog_id` to reference). You need to define line item details, such as the name and price. Note that this does not create a catalog item. \n\nUsing existing catalog items means that you can track your inventory and more easily manage your catalog. You should start by [setting up your catalog.](/catalog-api/what-it-does)\n\n### Fulfillments \n\nFulfillment orders are a type of order that can track additional fulfillment details required to close the order. Currently, Square supports two types of fulfillment orders:\n\n* A shipment order, which can track a customer's address where the order should be shipped. \n* A pickup order, which can track delivery details, whether the order has been picked up, and other related details. \n\nFulfillment orders appear in the Square Point of Sale application after they are charged. Note that fulfillment orders must have `delay_capture` set to `true`.\n\n### Taxes and discounts\n\nTaxes and discounts are price modifiers that you can use to modify the total cost of an order or a line item. You have two options for creating line items for your orders:\n\n* Referencing catalog object IDs. \n* Defining line items ad hoc. \n\nYou can specify whether the price modifier is a percentage of the total or a sum subtracted from the total. You can apply a discount or tax with an order scope at the order level, where it applies to the entire order total, or with a line item scope at the line item level, where it applies to the individual line item's price. \n\n### Versions\n\nEach `Order` object has a version number to track, which is the most recent version of the order. Orders begin with a version value of 1 and each time an order is updated, the version number gains +1. When issuing an update request, the version is required and it needs to match the latest version number.\n\nThis helps protect you from operating on a stale version of an order.\n\n### UIDs\n\nEach object within the `Order` object has ID fields to uniquely identify it and to provide a key for specifying one message in a list. \n\nObject IDs can be specified as part of any `CreateOrder` or `UpdateOrder` request. If left unset, they are generated by the server and included in the response. Any update to an existing field must include the ID on request. \n\nID fields are limited to 60 characters and are limited to letters, numbers, hyphens, underscores, and periods.\n","programming-language":"All","platform":"All"},"relationships":{"constant-sets":{"data":[]}}},{"id":"DEVELOPERS_URL_ROOT","type":"constant","attributes":{"value":"https://developer.{{SQUARE_DOMAIN}}"}},{"id":"SQUARE_URL_ROOT","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}"}},{"id":"DOCS_URL_ROOT","type":"constant","attributes":{"value":"https://developer.{{SQUARE_DOMAIN}}/docs"}},{"id":"SQUARE_HELP_URL_ROOT","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/help"}},{"id":"SQUARE_LOGIN","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/login"}},{"id":"SQUARE_SIGNUP","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/signup?v=developers"}},{"id":"ACTIVATE_ACCOUNT","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/activate"}},{"id":"APP_DASHBOARD","type":"constant","attributes":{"value":"https://developer.{{SQUARE_DOMAIN}}/apps"}},{"id":"SQUARE_DASHBOARD","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/dashboard"}},{"id":"CONNECT_TECH_REF","type":"constant","attributes":{"value":"https://developer.{{SQUARE_DOMAIN}}/docs/api/connect/v2"}},{"id":"PAYMENT_FORM_TECH_REF","type":"constant","attributes":{"value":"https://developer.{{SQUARE_DOMAIN}}/docs/api/paymentform"}},{"id":"AUTHZ_TECH_REF","type":"constant","attributes":{"value":"https://developer.{{SQUARE_DOMAIN}}/docs/api/oauth"}},{"id":"READER_SDK_TECH_REF","type":"constant","attributes":{"value":"https://developer.{{SQUARE_DOMAIN}}/docs/api/reader"}},{"id":"POS_API_TECH_REF","type":"constant","attributes":{"value":"https://developer.{{SQUARE_DOMAIN}}/docs/api/point-of-sale"}},{"id":"IAP_TECH_REF","type":"constant","attributes":{"value":"https://developer.{{SQUARE_DOMAIN}}/docs/api/in-app-payment"}},{"id":"PHP_GITHUB_URL","type":"constant","attributes":{"value":"https://github.com/square/square-php-sdk"}},{"id":"NODEJS_GITHUB_URL","type":"constant","attributes":{"value":"https://github.com/square/square-nodejs-sdk"}},{"id":"RUBY_GITHUB_URL","type":"constant","attributes":{"value":"https://github.com/square/square-ruby-sdk"}},{"id":"PYTHON_GITHUB_URL","type":"constant","attributes":{"value":"https://github.com/square/square-python-sdk"}},{"id":"JAVA_GITHUB_URL","type":"constant","attributes":{"value":"https://github.com/square/connect-java-sdk"}},{"id":"DOTNET_GITHUB_URL","type":"constant","attributes":{"value":"https://github.com/square/connect-csharp-sdk"}},{"id":"POS_ANDROID_GITHUB_URL","type":"constant","attributes":{"value":"https://github.com/square/point-of-sale-android-sdk"}},{"id":"POS_IOS_GITHUB_URL","type":"constant","attributes":{"value":"https://github.com/square/SquarePointOfSaleSDK-iOS"}},{"id":"IAP_IOS_GITHUB_URL","type":"constant","attributes":{"value":"https://github.com/square/in-app-payments-ios"}},{"id":"SQUARE_HELP_ACCEPTED_CARDS","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/help/article/5085"}},{"id":"SQUARE_HELP_CHARGEBACKS","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/help/article/5394"}},{"id":"SQUARE_HELP_CONTACT","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/help/contact?prefill=developer_api"}},{"id":"SQUARE_HELP_CONTACTLESS_READER","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/help/article/5639"}},{"id":"SQUARE_HELP_DEPOSIT_SCHEDULE","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/help/article/5438"}},{"id":"SQUARE_HELP_FEES","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/help/article/5068"}},{"id":"SQUARE_HELP_OFFLINE_MODE","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/help/article/5095"}},{"id":"SQUARE_HELP_POS_COF","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/help/article/5770"}},{"id":"SQUARE_HELP_PROCESS_REFUNDS","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/help/article/6116"}},{"id":"SQUARE_HELP_REFUND_OVERVIEW","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/help/article/5060"}},{"id":"SQUARE_HELP_SPLIT_TENDER","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/help/article/5097"}},{"id":"INSOMNIA_URL","type":"constant","attributes":{"value":"https://insomnia.rest"}},{"id":"PAW_URL","type":"constant","attributes":{"value":"https://paw.cloud"}},{"id":"POSTMAN_URL","type":"constant","attributes":{"value":"https://www.getpostman.com"}},{"id":"POSTMAN_BUTTON","type":"constant","attributes":{"value":"https://run.pstmn.io/button.svg"}},{"id":"POSTMAN_COLLECTION_URL","type":"constant","attributes":{"value":"https://app.getpostman.com/run-collection/5236465-5827b5b7-4b61-4003-8044-8fc0254dd547-SVYxovAy"}},{"id":"CONNECT_EXAMPLES_GITHUB_URL","type":"constant","attributes":{"value":"https://github.com/square/connect-api-examples/tree/master"}},{"id":"READER_SDK_RN_GITHUB_URL","type":"constant","attributes":{"value":"https://github.com/square/react-native-square-reader-sdk"}},{"id":"READER_SDK_FLUTTER_GITHUB_URL","type":"constant","attributes":{"value":"https://github.com/square/reader-sdk-flutter-plugin"}},{"id":"IAP_SDK_FLUTTER_GITHUB_URL","type":"constant","attributes":{"value":"https://github.com/square/in-app-payments-flutter-plugin"}},{"id":"IAP_SDK_REACT_NATIVE_PLUGIN_GITHUB_URL","type":"constant","attributes":{"value":"https://github.com/square/in-app-payments-react-native-plugin"}},{"id":"POS_ANDROID_SDK_GITHUB_URL","type":"constant","attributes":{"value":"https://github.com/square/point-of-sale-android-sdk"}},{"id":"POS_IOS_SDK_GITHUB_URL","type":"constant","attributes":{"value":"https://github.com/square/SquarePointOfSaleSDK-iOS"}},{"id":"BUY_SQUARE_READER","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/shop/hardware/products/chip-credit-card-reader-with-nfc"}},{"id":"FREE_MAGSTRIPE_READER","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/shop/hardware/products/free-credit-card-reader"}},{"id":"BUY_SQUARE_READER_IN_PERSON","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/where-to-buy"}},{"id":"MARKETPLACE_URL","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/us/en/app-marketplace"}},{"id":"IAP_SDK_FLUTTER_PLUGIN_GITHUB_URL","type":"constant","attributes":{"value":"https://github.com/square/in-app-payments-flutter-plugin"}},{"id":"SQUARE_GIFT_CARDS","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/gift-cards"}},{"id":"ANDROID_DEV_BASICS","type":"constant","attributes":{"value":"https://developer.android.com/training/basics"}},{"id":"ANDROID_DEV","type":"constant","attributes":{"value":"https://developer.android.com"}},{"id":"GITHUB_CONNECT_V2_EXAMPLES","type":"constant","attributes":{"value":"https://github.com/square/connect-api-examples/tree/master/connect-examples/v2"}},{"id":"GITHUB_CONNECT_V1_EXAMPLES","type":"constant","attributes":{"value":"https://github.com/square/connect-api-examples/tree/master/connect-examples/v1"}},{"id":"IAP_TECH_REF_ANDROID","type":"constant","attributes":{"value":"https://developer.{{SQUARE_DOMAIN}}/docs/api/in-app-payment/android"}},{"id":"IAP_TECH_REF_IOS","type":"constant","attributes":{"value":"https://developer.{{SQUARE_DOMAIN}}/docs/api/in-app-payment/ios"}},{"id":"SLACK_URL","type":"constant","attributes":{"value":"https://squ.re/2Hks3YE"}},{"id":"SQUARE_TECH_REF","type":"constant","attributes":{"value":"https://developer.{{SQUARE_DOMAIN}}/reference/square"}},{"id":"OLD_TECH_REF","type":"constant","attributes":{"value":"https://developer.{{SQUARE_DOMAIN}}/docs/api/connect/v2/2019-05-08"}},{"id":"NODEJS_SDK_TECH_REF_URL","type":"constant","attributes":{"value":"https://github.com/square/square-nodejs-sdk/blob/master/README.md"}},{"id":"PHP_SDK_TECH_REF_URL","type":"constant","attributes":{"value":"https://github.com/square/square-php-sdk/blob/master/README.md"}},{"id":"DOTNET_SDK_TECH_REF_URL","type":"constant","attributes":{"value":"https://github.com/square/square-dotnet-sdk/blob/master/README.md"}},{"id":"JAVA_SDK_TECH_REF_URL","type":"constant","attributes":{"value":"https://github.com/square/square-java-sdk/blob/master/README.md"}},{"id":"PYTHON_SDK_TECH_REF_URL","type":"constant","attributes":{"value":"https://github.com/square/square-python-sdk/blob/master/README.md"}},{"id":"RUBY_SDK_TECH_REF_URL","type":"constant","attributes":{"value":"https://github.com/square/square-ruby-sdk/blob/master/README.md"}},{"id":"TEST-CONSTANT","type":"constant","attributes":{"value":"some value2"}},{"id":"BUY_SQUARE_STAND","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/shop/hardware/products/ipad-pos-stand-credit-card-reader\n"}},{"id":"BUY_SQUARE_TERMINAL","type":"constant","attributes":{"value":"https://{{SQUARE_DOMAIN}}/shop/hardware/us/en/products/terminal-credit-card-machine"}},{"id":"API_EXPLORER_GA","type":"constant","attributes":{"value":"https://developer.{{SQUARE_DOMAIN}}/explorer/square"}},{"id":"NODEJS_SDK_NAME","type":"constant","attributes":{"value":"Square Node.js SDK"}},{"id":"SQUARE_SDK_REF","type":"constant","attributes":{"value":"https://developer.{{SQUARE_DOMAIN}}/reference/sdks"}},{"id":"SQUARE_TECH_ROOT","type":"constant","attributes":{"value":"https://developer.{{SQUARE_DOMAIN}}/reference"}},{"id":"DEVELOPERS_URLS","type":"constant-set","relationships":{"constants":{"data":[{"id":"DEVELOPERS_URL_ROOT","type":"constant"},{"id":"SQUARE_URL_ROOT","type":"constant"},{"id":"DOCS_URL_ROOT","type":"constant"},{"id":"SQUARE_HELP_URL_ROOT","type":"constant"},{"id":"SQUARE_LOGIN","type":"constant"},{"id":"SQUARE_SIGNUP","type":"constant"},{"id":"ACTIVATE_ACCOUNT","type":"constant"},{"id":"APP_DASHBOARD","type":"constant"},{"id":"SQUARE_DASHBOARD","type":"constant"},{"id":"CONNECT_TECH_REF","type":"constant"},{"id":"PAYMENT_FORM_TECH_REF","type":"constant"},{"id":"AUTHZ_TECH_REF","type":"constant"},{"id":"READER_SDK_TECH_REF","type":"constant"},{"id":"POS_API_TECH_REF","type":"constant"},{"id":"IAP_TECH_REF","type":"constant"},{"id":"PHP_GITHUB_URL","type":"constant"},{"id":"NODEJS_GITHUB_URL","type":"constant"},{"id":"RUBY_GITHUB_URL","type":"constant"},{"id":"PYTHON_GITHUB_URL","type":"constant"},{"id":"JAVA_GITHUB_URL","type":"constant"},{"id":"DOTNET_GITHUB_URL","type":"constant"},{"id":"POS_ANDROID_GITHUB_URL","type":"constant"},{"id":"POS_IOS_GITHUB_URL","type":"constant"},{"id":"IAP_IOS_GITHUB_URL","type":"constant"},{"id":"SQUARE_HELP_ACCEPTED_CARDS","type":"constant"},{"id":"SQUARE_HELP_CHARGEBACKS","type":"constant"},{"id":"SQUARE_HELP_CONTACT","type":"constant"},{"id":"SQUARE_HELP_CONTACTLESS_READER","type":"constant"},{"id":"SQUARE_HELP_DEPOSIT_SCHEDULE","type":"constant"},{"id":"SQUARE_HELP_FEES","type":"constant"},{"id":"SQUARE_HELP_OFFLINE_MODE","type":"constant"},{"id":"SQUARE_HELP_POS_COF","type":"constant"},{"id":"SQUARE_HELP_PROCESS_REFUNDS","type":"constant"},{"id":"SQUARE_HELP_REFUND_OVERVIEW","type":"constant"},{"id":"SQUARE_HELP_SPLIT_TENDER","type":"constant"},{"id":"INSOMNIA_URL","type":"constant"},{"id":"PAW_URL","type":"constant"},{"id":"POSTMAN_URL","type":"constant"},{"id":"POSTMAN_BUTTON","type":"constant"},{"id":"POSTMAN_COLLECTION_URL","type":"constant"},{"id":"CONNECT_EXAMPLES_GITHUB_URL","type":"constant"},{"id":"READER_SDK_RN_GITHUB_URL","type":"constant"},{"id":"READER_SDK_FLUTTER_GITHUB_URL","type":"constant"},{"id":"IAP_SDK_FLUTTER_GITHUB_URL","type":"constant"},{"id":"IAP_SDK_REACT_NATIVE_PLUGIN_GITHUB_URL","type":"constant"},{"id":"POS_ANDROID_SDK_GITHUB_URL","type":"constant"},{"id":"POS_IOS_SDK_GITHUB_URL","type":"constant"},{"id":"BUY_SQUARE_READER","type":"constant"},{"id":"FREE_MAGSTRIPE_READER","type":"constant"},{"id":"BUY_SQUARE_READER_IN_PERSON","type":"constant"},{"id":"MARKETPLACE_URL","type":"constant"},{"id":"IAP_SDK_FLUTTER_PLUGIN_GITHUB_URL","type":"constant"},{"id":"SQUARE_GIFT_CARDS","type":"constant"},{"id":"ANDROID_DEV_BASICS","type":"constant"},{"id":"ANDROID_DEV","type":"constant"},{"id":"GITHUB_CONNECT_V2_EXAMPLES","type":"constant"},{"id":"GITHUB_CONNECT_V1_EXAMPLES","type":"constant"},{"id":"IAP_TECH_REF_ANDROID","type":"constant"},{"id":"IAP_TECH_REF_IOS","type":"constant"},{"id":"SLACK_URL","type":"constant"},{"id":"SQUARE_TECH_REF","type":"constant"},{"id":"OLD_TECH_REF","type":"constant"},{"id":"NODEJS_SDK_TECH_REF_URL","type":"constant"},{"id":"PHP_SDK_TECH_REF_URL","type":"constant"},{"id":"DOTNET_SDK_TECH_REF_URL","type":"constant"},{"id":"JAVA_SDK_TECH_REF_URL","type":"constant"},{"id":"PYTHON_SDK_TECH_REF_URL","type":"constant"},{"id":"RUBY_SDK_TECH_REF_URL","type":"constant"},{"id":"TEST-CONSTANT","type":"constant"},{"id":"BUY_SQUARE_STAND","type":"constant"},{"id":"BUY_SQUARE_TERMINAL","type":"constant"},{"id":"API_EXPLORER_GA","type":"constant"},{"id":"NODEJS_SDK_NAME","type":"constant"},{"id":"SQUARE_SDK_REF","type":"constant"},{"id":"SQUARE_TECH_ROOT","type":"constant"}]}}},{"id":"5rwdfEisYtZX0m0Ee0sKme","type":"markdown-block","attributes":{"name":"Orders API : How It Works : Process Flow","markdown":"## Orders API process flow\n\nIn general, manually creating an order and linking it to a [payment](${CONNECT_TECH_REF}#type-payment) involves\nthe following steps:\n\n1. The application backend gathers order details and builds an `CreateOrder`\nrequest object.\n1. The application backend sends the `CreateOrder` request object to the\n`CreateOrder` endpoint.\n1. The `CreateOrder` endpoint creates an `Order` object and calculates a final\npurchase price based on the order details.\n1. Square returns the `Order` object to the application backend.\n1. The application backend extracts the order ID and creates a payment request object using the order ID.\n\n ![A diagram showing the Orders API process flow for manually creating an order and linking it to a payment.](https://images.ctfassets.net/1nw4q0oohfju/4KbphDNMXpXxxqZCYLTp0u/6254d3a9b65ecd78bd7a8c6536d31d98/diagram-orders-4_2x.png)\n\n !!!important\n\n Managing the order state is critical to ensure that customers are properly charged. When an `Order` object is created, Square takes a snapshot of the state of the objects included and uses that snapshot to process the transaction. Even if the price of the item changes before the transaction completes, the Orders API uses that original price to calculate the total.\n\n You should create `Order` objects immediately before processing the transaction. Otherwise, you need to create a new `Order` object to capture any changes that occur.\n\n !!!","programming-language":"All","platform":"All"},"relationships":{"constant-sets":{"data":[{"id":"DEVELOPERS_URLS","type":"constant-set"}]}}},{"id":"1aIwlCX2r9wQhuGbvIoAp7","type":"markdown-block","attributes":{"name":"Orders API : How It Works : How totals are calculated","markdown":"## How totals are calculated\n\nThe Orders API calculates and applies all discounts and taxes as line item price adjustments. Price adjustments defined as the item level are applied directly to the applicable line item and order-level price adjustments are distributed across all line item subtotals.\n\nThe final purchase amount is calculated as follows:\n\n1. Calculate a starting gross price for each line item from the base price and quantity.\n1. Apply item-level percent discounts to the applicable line item totals.\n1. Convert and apply order-level percent discounts to all line item totals.\n1. Apply item-level fixed-amount discounts to the applicable line item totals.\n1. Convert and distribute order-level fixed-amount discounts to all line item totals. The amount distributed to each line item is relative to the amount that item contributes to the order subtotal.\n1. Apply item-level and order-level taxes to all line item totals.\n\nAs an example, consider an online order at Raphael's Puppy-Care Emporium for two packages of Tendon pinwheel, one handmade sweater, and three packages of Chewy trainers, which includes the following discounts:\n\n* A item-level percent discount on the Tendon pinwheels: \"7% OFF — Discontinued item\".\n* A item-level fixed-amount discount on the Tendon pinwheels: \"$3.00 OFF — Customer Loyalty Discount\".\n* A item-level fixed-amount discount on the Chewy trainers: \"$11.00 OFF — Customer Loyalty Discount\".\n* An order-level percent discount: \"12% OFF — National Puppy Day Sale\".\n* An order-level fixed-amount discount: \"$55 OFF — Global Sale\".\n\nThe following taxes apply:\n\n* A line-item percent tax on sweaters: \"Fair Trade Tax: 5%\".\n* An order-level percent tax: \"State Sales Tax: 8.5%\"\n\n#### Rounding\n\nThe Orders API uses \"round half to even\" rules, known as bankers rounding, to\ncalculate taxes and discounts. Under normal rounding rules, half-values round\nto the next closest integer. For example:\n\n* 0.505 becomes 0.51\n* 0.715 becomes 0.72\n* 0.085 becomes 0.09\n\nHowever, under bankers rounding rules, half-values round to the closest even integer, which has the effect of pulling even numbers down while leaving odd numbers unchanged. For example:\n\n* 0.505 becomes 0.50 (pulled down from 0.51)\n* 0.715 becomes 0.72 (unchanged from normal rounding)\n* 0.085 becomes 0.08 (pulled down from 0.09)\n\nFor more information about rounding at Square, see [Understanding Fee Rounding](https://squareup.com/help/us/en/article/5092-rounding).\n\n### Step 1: Calculate line-item gross totals\n\nThe Orders API calculates the gross totals for each line item according to the base price and quantity for the item.\n\n\n\n\n\n \n \n \n \n\n\n\n\n \n \n \n \n\n\n \n \n \n \n\n\n \n \n \n \n\n\n \n \n\n\n

Quantity	Description	Base Price	\n Starting Item Total \n (Quantity * Base Price)\n
2	Chicken Treats — Tendon pinwheel	15.00 USD	30.00 USD
1	Handmade Sweater — Blue	50.00 USD	50.00 USD
3	Chicken Treats — Chewy trainers	12.00 USD	36.00 USD
ORDER SUBTOTAL	$116.00

\n\n\n\n### Step 2: Apply item-level percent discounts\n\nThe Orders API applies item-level percent discounts to the applicable line\nitems. Note that the Tendon pinwheel line item is the only item to receive 7% off.\n\n\n\n\n \n \n \n\n\n\n\n \n \n \n\n\n \n \n \n\n\n \n \n\n\n \n \n \n\n\n \n \n\n\n \n \n \n\n\n \n \n\n\n \n \n\n\n

Item	Item Amount	Final Amount
Chicken Treats — Tendon pinwheel	30.00 USD
\n 7% OFF — Discontinued item\n (30.00 x 0.07 = −2.10 USD) \n	27.90 USD
Tendon pinwheel subtotal	27.90 USD
Handmade Sweater — Blue	50.00 USD
Handmade sweater subtotal	50.00 USD
Chicken Treats — Chewy trainers	36.00 USD
Chewy trainers subtotal	36.00 USD
ORDER SUBTOTAL	113.90 USD

\n\n\n### Step 3: Convert and apply order-level percent discounts\n\nThe Orders API applies order-level percent discounts to each individual line\nitem. In this example, that means every line item takes 12% off for a National\nPuppy Day Sale.\n\n\n\n\n \n \n \n\n\n\n\n \n \n \n\n\n \n \n \n\n\n \n \n\n\n \n \n \n\n\n \n \n \n\n\n \n \n\n\n \n \n \n\n\n \n \n \n\n\n \n \n\n\n \n \n\n\n

Item	Item Amount	Final Amount
Chicken Treats — Tendon pinwheel	27.90 USD
\n 12% OFF — National Puppy Day Sale\n (27.90 x 0.12 = −3.35 USD) \n	24.55 USD
Tendon pinwheel subtotal	24.55 USD
Handmade Sweater — Blue	50.00 USD
\n 12% OFF — National Puppy Day Sale\n (50.00 x 0.12 = −6.00 USD) \n	44.00 USD
Handmade sweater subtotal	44.00 USD
Chicken Treats — Chewy trainers	36.00 USD
\n 12% OFF — National Puppy Day Sale\n (36.00 x 0.12 = −4.32 USD) \n	31.68 USD
Chicken treats subtotal	31.68 USD
ORDER SUBTOTAL	100.23 USD

\n\n\n### Step 4: Apply item-level fixed-amount discounts\n\nThe Orders API applies item-level fixed-amount discounts to the applicable line items. In this example, that means the Tendon pinwheels and the Chewy trainers receive a fixed-amount discount.\n\n\n\n\n \n \n \n\n\n\n\n \n \n \n\n\n \n \n \n\n\n \n \n\n\n \n \n \n\n\n \n \n\n\n \n \n \n\n\n \n \n \n\n\n \n \n\n\n \n \n\n\n

Item	Item Amount	Final Amount
Chicken Treats — Tendon pinwheel	24.55 USD
$3.00 OFF — Customer Loyalty Discount (−3.00 USD)	21.55 USD
Chicken Treats subtotal	21.55 USD
Handmade Sweater — Blue	44.00 USD
Handmade sweater subtotal	44.00 USD
Chicken Treats — Chewy trainers	31.68 USD
$11.00 OFF — Customer Loyalty Discount (−11.00 USD)	20.68 USD
Chewy trainers subtotal	20.68 USD
ORDER SUBTOTAL	86.23 USD

\n\n\n### Step 5: Convert and apply order-level fixed-amount discounts\n\nFixed-amount order-level discounts are converted to the equivalent item-level discount based on the relative portion that the line item contributes to the most recent subtotal using the following formula:\n\n

\n $$\\displaystyle{\\left(\\frac{\\text{Current Item Subtotal}}{\\text{Current Order Subtotal}}\\right)}\\times\\text{Order-Level Fixed Discount}=\\text{Applicable Line Item Discount}$$\n

\n
\n\nIn this example, the order-level fixed discount is 55.00 USD and distributed\nacross three line items based on a subtotal of 86.23 USD:\n\n\n\n\n \n \n \n\n\n\n\n \n \n \n\n\n \n \n \n\n\n \n \n\n\n \n \n \n\n\n \n \n \n\n\n \n \n\n\n \n \n \n\n\n \n \n \n\n\n \n \n\n\n \n \n\n\n\n

Item	Item Amount	Final Amount
Chicken Treats — Tendon pinwheel	21.55 USD
\n $55 OFF — Global Sales\n \n $$\\displaystyle{\\left(\\frac{21.55}{{86.23}}\\right)}\\times{55.00}=-{13.75}$$\n \n	7.80 USD
Tendon pinwheel subtotal	7.80 USD
Handmade Sweater — Blue	44.00 USD
\n $55 OFF — Global Sales\n \n $$\\displaystyle{\\left(\\frac{44.00}{{86.23}}\\right)}\\times{55.00}=-{28.06}$$\n \n	15.94 USD
Handmade sweater subtotal	15.94 USD
Chicken Treats — Chewy trainers	20.68 USD
\n $55 OFF — Global Sales\n \n $$\\displaystyle{\\left(\\frac{20.68}{{86.23}}\\right)}\\times{55.00}=-{13.19}$$\n \n	7.49 USD
Chewy trainers subtotal	7.49 USD
ORDER SUBTOTAL	31.23 USD

\n\n\n### Step 6: Apply order-level and item-level taxes\n\nThe last step is to apply all applicable taxes. Item-level taxes are applied first and then order-level taxes are distributed to each line item in the order.\n\n\n\n\n \n \n \n\n\n\n\n \n \n \n\n\n \n \n \n\n\n \n \n\n\n \n \n \n\n\n \n \n \n\n\n \n \n\n\n \n \n \n\n\n \n \n \n\n\n \n \n \n\n\n \n \n\n\n \n \n\n\n

Item	Item Amount	Final Amount
Chicken Treats — Tendon pinwheel	7.80 USD
\n State Sales Tax: 8.5%\n \n $$\\displaystyle{\\left({7.80}\\times{0.085}\\right)}=+{0.66}$$\n \n	8.46 USD
Tendon pinwheel subtotal	8.46 USD
Handmade Sweater — Blue	15.94 USD
\n State Sales Tax: 8.5%\n \n $$\\displaystyle{\\left({15.94}\\times{0.085}\\right)}=+{1.35}$$\n \n	17.29
Handmade sweater subtotal	17.29 USD
Chicken Treats — Chewy trainers	7.49 USD
\n Fair Trade Tax: 5%\n \n $$\\displaystyle{\\left({7.49}\\times{0.05}\\right)}=+{0.37}$$\n \n	7.86 USD
\n State Sales Tax: 8.5%\n \n $$\\displaystyle{\\left({7.49}\\times{0.085}\\right)}=+{0.64}$$\n \n	8.50 USD
Chewy trainers subtotal	8.50 USD
ORDER SUBTOTAL	34.25 USD

\n\n\n### Calculating order-level taxes and discounts\n\nTo calculate order-level taxes and discounts:\n1. Add up the total cost of all order items.\n1. Calculate the tax or discount for that item total.\n1. Distribute the tax or discount proportionally to each item.\n\nIf the tax or discount for the total cost of the group equals an odd number, the remainder is applied to one of the items in the group. This way, the total cost of the entire order remains accurate.\n\n\n#### Tax example\n\nFor example, suppose you apply a 9.25% sales tax to three dog collars that cost\n3.50 USD each:\n\n* Red Dog Collar: 3.50 USD with a 9.25% sales tax\n* Blue Dog Collar: 3.50 USD with a 9.25% sales tax\n* Yellow Dog Collar: 3.50 USD with a 9.25% sales tax\n\nFirst, you add up the total cost of the items:\n\n* 3.50 USD + 3.50 USD + 3.50 USD = 10.50 USD\n\nNext, you calculate the total tax for the combined cost and use bankers rounding to round to the nearest even amount:\n\n* 10.50 USD x 0.0925 = 0.97125 USD\n\n* 0.97125 USD rounds to 0.97 USD\n\nFinally, distribute the tax proportionally to each individual item. Because the\ntotal tax amount does not divide evenly by the total number of items, apply the\nremainder (0.01 USD) to one of the items:\n\n* Red Dog Collar: 3.50 USD + 0.32 USD = 3.82 USD\n* Blue Dog Collar: 3.50 USD + 0.32 USD = 3.82 USD\n* Yellow Dog Collar: 3.50 USD + 0.33 USD = 3.83 USD\n\n#### Discount example\n\nSuppose you want to calculate a 15% discount for three dog treats that cost 4.50 USD each:\n\n* Dog Cookie: 4.50 USD with a 15% Discount\n* Dog Bone: 4.50 USD with a 15% Discount\n* Dog Banana: 4.50 USD with a 15% Discount\n\nFirst, you add up the total cost of the items:\n\n* 4.50 USD + 4.50 USD + 4.50 USD = 13.50 USD\n\nNext, you calculate the total discount for the combined cost and use bankers rounding to round to the nearest even amount:\n\n* 13.50 USD x –0.15 = –2.025 USD\n\n* –2.025 USD rounds to –2.02 USD\n\nFinally, distribute the discount proportionally to each individual item. Because the total discount amount does not divide evenly by the total number of items, apply the remainder (–0.01 USD) to one of the items:\n\n* Dog Cookie: 4.50 USD – 0.67 USD = 3.83 USD\n* Dog Bone: 4.50 USD – 0.67 USD = 3.83 USD\n* Dog Banana: 4.50 USD – 0.68 USD = 3.84 USD","programming-language":"All","platform":"All"},"relationships":{"constant-sets":{"data":[{"id":"DEVELOPERS_URLS","type":"constant-set"}]}}},{"id":"6afBYscFAOsxAI8WI1AqMd","type":"markdown-block","attributes":{"name":"Orders API : How It Works : Reporting on Orders","markdown":"## Reporting on orders\n\nAll order details are available through the [BatchRetrieveOrders](${CONNECT_TECH_REF}#endpoint-orders-batchretrieveorders) and [SearchOrders](${CONNECT_TECH_REF}#endpoint-orders-searchorders) endpoints. \n\nFulfillment orders only appear in the Square Seller Dashboard after they are charged. Note that fulfillment orders must have `delay_capture` set to `true`.\n\n## Related topics\n\n* [Create Orders](orders-api/create-orders)\n* [Pay for Orders](orders-api/pay-for-orders)\n* [Manage Orders](orders-api/manage-orders)","programming-language":"All","platform":"All"},"relationships":{"constant-sets":{"data":[{"id":"DEVELOPERS_URLS","type":"constant-set"}]}}},{"id":"CU5gIgymJFByAqhSH8v0f","type":"doc-page","attributes":{"slug":"orders-api/how-it-works","heading":{"id":"56bW7NKq3Uf8fV0jJFVZYk","title":"How It Works","eyebrow":"Orders API","summary":null,"browser_title":"Orders API: How It Works","release_status":"PUBLIC"},"environments":null,"related-pages":null,"search-summary":"Learn how the Orders API processes and returns information.","languages-supported":["All"],"platforms":["All"]},"relationships":{"content":{"data":[{"id":"6zcP4ecFNM2f6GXXixBLHE","type":"markdown-block"},{"id":"4UkKLkk9395WJIFV93vWJj","type":"markdown-block"},{"id":"5rwdfEisYtZX0m0Ee0sKme","type":"markdown-block"},{"id":"1aIwlCX2r9wQhuGbvIoAp7","type":"markdown-block"},{"id":"6afBYscFAOsxAI8WI1AqMd","type":"markdown-block"}]},"constant-sets":{"data":[]}}}]}

How It Works

On this page