--- title: "Create an order" method: POST path: "/v1/orders" tags: ["ORDERS"] --- # Create an order `POST /v1/orders` Creates a new order object. ## Headers - `User-Agent` string, required ## Request body - object - `currency` string, required — Three-letter [ISO 4217 currency code](https://www.iso.org/iso-4217-currency-codes.html). Format: Lower case Length: Max 3 - `customer` string — Displays order details for the customer placing the order. - `email` string, required — Email address of the customer placing the order. - `expand` string[] — Additional information is provided as an expanded response, for example, related objects nested within the parent. See [Use expandable fields](https://docs.clover.com/docs/expanding-fields). - `items` object[] — List of items in the order. An order can have 25 items. - `amount` integer, required — Amount of an item in the inventory. - `currency` string — Currency of the item amount. - `description` string — Description of the item. - `inventory_id` string — Universally unique identifier (UUID) of the associated object for the line item. The value is expandable if it is not null. - `parent` string — DEPRECATED. Use `inventory_id` instead of `parent`. - `quantity` integer — Unit quantity of an item. - `tax_rates` union[] — Tax rate applicable on an item. - union - TaxRatesRate — Tax rate object defining an item-level tax as a percentage (%). - `name` string — Label for the tax rate. - `rate` integer — Item-specific tax where a 10% rate is defined as `1000000`. - TaxRatesAmount — Tax rate object defining a flat item-level tax amount. - `name` string — Label for the tax rate. - `tax_amount` integer — Merchant-defined flat tax amount in cents. Format: Cents. - TaxRatesUuid — Tax rate object defining an item-level tax with a unique identifier (ID). - `name` string — Label for the item-level tax UUID. - `tax_rate_uuid` string — Item-level tax UUID. - `type` 'shipping' | 'sku' — Item type. Values: Shipping SKU - `metadata` object — Set of key-value pairs that you can attach to the object. This parameter is useful for storing additional information about the object in a structured format. Length: Maximum 500 characters - `shipping` object — Shipping details for the order. - `address` object, required — Shipping address for the order. Required, if the stock keeping unit (SKU) of an item in the order has a `shippable` value of **true**. - `city` string, required — City of the customer's address. Can include district, suburb, town, or village. - `country` string — Country code. Format: 2 letters - `line1` string, required — First line of the address. Can include the street address, PO box, or company name. - `line2` string — Second line of the address. Can include the apartment, suite, unit, or building number. - `postal_code` string, required — Postal or ZIP code of the customer's address. - `state` string, required — State of the customer's address. Can include county, province, or region. - `name` string, required — Name of the customer. - `phone` string — Phone number of the customer. ## Response `200` Successful response. An order created. - Order - `amount` integer, required — Total order amount in the smallest monetary unit of the merchant's currency. - `amount_paid` integer — Amount currently paid toward the order total. - `amount_due` integer — Amount still due toward the order total. - `tax_amount` integer — Merchant-defined flat tax amount for the order. Format: Cents - `tax_amount_paid` integer — Amount currently paid toward the tax total. - `tip_amount` integer — Amount paid in tips. This value is automatically added to the total amount when the transaction is finalized. - `partial_auth` boolean — Indicates if partial approval has occurred. - `additional_charges` AdditionalCharges — Additional surcharge or other fee applied on the transaction. - `amount` integer — Amount of the additional charges applied on the transaction. Format: Cents - `id` string — Unique identifier of the additional charge. - `rate` integer — Item-specific tax of an additonal charge where a 10% rate is defined as 1000000. - `type` 'CREDIT_SURCHARGE' — Type of the additional charge collected on the transaction. - `threeds` ThreedsValidationResult — 3DSecure validation result. - `validation_result` 'AUTHENTICATION_FAILED' | 'AUTHENTICATION_SUCCESSFUL' | 'ISSUER_DOES_NOT_PARTICIPATE' | 'ATTEMPTED_UNSUCCESSFULLY' | 'ATTEMPTED_SUCCESSFULLY' | 'NOT_POSSIBLE' — Indicates validation result of 3DSecure transaction. - `source` string — Source of the 3DSecure transaction. Example: `CLOVER` or `NON_CLOVER` - `gift_card` EcommGiftCardResponseExtra — Indicates meta data of the gift card. - `previous_balance` integer — Indicates the previous balance before the transaction was initiated. - `new_balance` integer — Indicates the updated balance after the transaction is completed. - `lock_amount` integer — Indicates the value on the card that was locked due to a balance lock transaction. - `expiration_date` string — Indicates the account expiration date. - `lock_id` integer — Unique lock number identifier for each balance lock record. The `lock_id` helps capture the authorized amount and is applicable for pre-auth and capture flow. - `number` string — Embossed card number on the gift card or the ift card number. Only applicable for virtual gift card activation. - `security_card_value` string — Gift card security code. Only applicable for virtual gift card activation. - `saved_credentials_on_file` SavedCredentialsOnFile — Data about any surcharge or other fee applied to a transaction. - `tokenType` 'TRANSARMOR' — Multi-pay token type such as TransArmor. - `value` integer — The percentage of the total assessed as a surcharge or other fee. This value is set when a merchant is boarded to Clover Percentages are defined to four decimal places. For example, the value of a 3.5% surcharge is `35000` (3.5*10000). - `ref_num` string — Identifier of additional charges. - `amount_returned` integer, nullable - `charge` string — Charge identifier. Returns the result when the order status is `paid`, `fulfilled`, or `refunded`. - `auth_code` string, nullable — Authorization code of the charge, if available. - `external_coupon_code` string — External coupon code available for this order. - `upstream_id` string — Billing address country, if provided. - `updated` integer — Time stamps when the order was last updated. - `first6` string — First 6 numbers of the primary account number. - `amount_preauthorized` integer — Displays the pre-authorized amount for the order. If any. - `ref_num` string, nullable — If available, the reference number returned from the payment gateway if the transaction is successful. - `warning_message` string, nullable — Detailed warning information about the order or associated charge (for example, missing original transaction id for c-token). - `ecomind` 'ecom' | 'moto' | 'retail' — Indicates who entered the card data used for a charge - customer (ecom) or merchant (moto). - `created` integer, required — Displays results based on the object's created field. Values: String with a Unix timestamp (in milliseconds) or Dictionary of multiple options describing a time range. - `currency` string, required — Three-letter ISO 4217 currency code. - `customer` string — Customer identifier. - `email` string, nullable — Email address of the customer placing the order. - `external_reference_id` string — An identifier such as an invoice or PO number, passed to the merchant's gateway and ultimately appears in settlement records. Note: Applicable for US customers, spaces are allowed in the reference number. Length: Max 12 (including alphanumeric characters) - `external_customer_reference` string — Customer reference number from the merchant's order management system. - `id` string, required — Order identifier. - `items` OrderItem[], required — Displays a list of items in an order. - `amount` integer, required — Amount of an item in the order. - `currency` string, required — Three-letter ISO 4217 currency code. - `description` string, required — Description of the item. - `inventory_id` union — UUID of the associated object for the line item. The value is expandable if it is not null. - string - Sku - `active` boolean, required — Indicates whether the item can be purchased. - `attributes` object, required — Set of product key-value pairs associated with and describing the item. This can be used for storing additional information about the item in a structured format. For example, for product attributes such as color and style, a SKU can have the following pairs: `{"color": "fuschia", "style": "bootcut"}`. - `created` integer, required — Displays results based on the object's created field. Values: String with a Unix timestamp (in milliseconds). or Dictionary of multiple options describing a time range. - `currency` string, required — Three-letter ISO 4217 currency code. - `id` string, required — Inventory item identifier. - `image` string, nullable — URL of an image for the SKU. - `livemode` boolean, required — Indicates whether the item is in production or sandbox. True - Item is in production False - Item is in sandbox - `metadata` object, required — Set of key-value pairs that you can attach to the object. This parameter is useful for storing additional information about the object in a structured format. Length: Maximum 500 characters - `object` 'sku', required — Object type. Objects with the same type have the same value. - `updated` integer, required — Time when the inventory item was modified. - `object` 'order_item', required — Object type. Objects with the same type have the same value. - `parent` union — DEPRECATED. UUID of the associated object for the line item. The value is expandable if it is not null. - string - Sku - `active` boolean, required — Indicates whether the item can be purchased. - `attributes` object, required — Set of product key-value pairs associated with and describing the item. This can be used for storing additional information about the item in a structured format. For example, for product attributes such as color and style, a SKU can have the following pairs: `{"color": "fuschia", "style": "bootcut"}`. - `created` integer, required — Displays results based on the object's created field. Values: String with a Unix timestamp (in milliseconds). or Dictionary of multiple options describing a time range. - `currency` string, required — Three-letter ISO 4217 currency code. - `id` string, required — Inventory item identifier. - `image` string, nullable — URL of an image for the SKU. - `livemode` boolean, required — Indicates whether the item is in production or sandbox. True - Item is in production False - Item is in sandbox - `metadata` object, required — Set of key-value pairs that you can attach to the object. This parameter is useful for storing additional information about the object in a structured format. Length: Maximum 500 characters - `object` 'sku', required — Object type. Objects with the same type have the same value. - `updated` integer, required — Time when the inventory item was modified. - `quantity` integer, nullable — If the `type` is `sku`, the number of instances of `parent` for the line item. - `tax_rates` union[] - union - TaxRatesRate — Tax rate object defining an item-level tax as a percentage (%). - `name` string — Label for the tax rate. - `rate` integer — Item-specific tax where a 10% rate is defined as `1000000`. - TaxRatesAmount — Tax rate object defining a flat item-level tax amount. - `name` string — Label for the tax rate. - `tax_amount` integer — Merchant-defined flat tax amount in cents. Format: Cents. - TaxRatesUuid — Tax rate object defining an item-level tax with a unique identifier (ID). - `name` string — Label for the item-level tax UUID. - `tax_rate_uuid` string — Item-level tax UUID. - `type` 'sku' | 'shipping', required — Line item type. - `past_charges` Charge[] — List of previous applicable charges on the order. - `amount` integer, required — Charge amount in cents. If the charge request includes tax (`tax_rate_uuid` or `tax_amount`), this value must be the sum of any item prices and any tax or tip. For example, if the item cost = $10 and the tax is $1, the amount is 1100 cents ($11). Format: cents - `tax_amount` integer — Amount paid in taxes. This value is not automatically added to the total amount. Your app must ensure the Amount property is the total final amount to charge the customer. - `tip_amount` integer — Amount paid in tips. This value is automatically added to the total amount when the transaction is finalized. - `additional_charges` AdditionalCharges — Additional surcharge or other fee applied on the transaction. - `amount` integer — Amount of the additional charges applied on the transaction. Format: Cents - `id` string — Unique identifier of the additional charge. - `rate` integer — Item-specific tax of an additonal charge where a 10% rate is defined as 1000000. - `type` 'CREDIT_SURCHARGE' — Type of the additional charge collected on the transaction. - `amount_refunded` integer, required — Amount refunded in cents. This value can be less than the amount property on the charge if a partial refund is issued. - `partial_auth` boolean — Indicates if the transaction was partially approved. - `billing_details` BillingDetails, required - `address` Address - `city` string, nullable — City of the customer's address. Can include district, suburb, town, or village. - `country` string, nullable — Country code. Format: 2 characters - `line1` string, nullable — First line of the customer's address. Can include the street address, PO box, or company name. - `line2` string, nullable — Second line of the customer's address. Can include the apartment, suite, unit, or building number. - `postal_code` string, nullable — Postal or ZIP code of the customer's address. - `state` string, nullable — State of the customer's address. Can include county, province, or region. - `email` string, nullable — Email address of the customer. - `name` string, nullable — Full name of the customer. - `phone` string, nullable — Phone number (including extension) of the customer. - `captured` boolean, required — Indicates whether to immediately capture the charge. Values: True - Default. False - Indicates the charge transaction type is AUTH (or PRE-AUTH), and the charge can be captured later using the [capture a charge](https://docs.clover.com/reference/capturecharge) endpoint. - `created` integer, required — Charge creation time (Unix timestamp in milliseconds). - `currency` string, required — Three-letter [ISO 4217 currency code](https://www.iso.org/iso-4217-currency-codes.html). Format: Lower case Length: Maximum 3 - `customer` string — Unique identifier of the customer associated with the charge. - `description` string, nullable — Detail description of the charge. - `external_reference_id` string — Unique identifier (ID), such as an invoice or purchase order (PO) number, that is sent to the merchant's gateway and displayed in settlement records. Format: Supported for US—alphanumeric characters with in-between spaces. Length: Maximum 12, including spaces and alphanumeric characters. - `external_customer_reference` string — Customer reference number from the merchant's order management system. - `auth_code` string, nullable — Authorization code of the charge, if available. - `ref_num` string, nullable — Reference number returned from the payment gateway when the transaction is successful. - `failure_code` string, nullable — Error code explaining the reason for the charge failure. - `failure_message` string, nullable — Detailed information about the reason for the charge failure. - `warning_message` string, nullable — Detailed warning information about the charge. Example: Missing original transaction identifer for c-token. - `id` string, required — Unique identifier of the charge. - `livemode` boolean, required — Indicates whether the token object is live in production. - `metadata` string, required — Set of key-value pairs that you can attach to the object. This parameter is useful for storing additional information about the object in a structured format. Length: Maximum 500 characters - `object` 'charge', required — Object type. - `order` string — Unique identifier of the order. - `outcome` union — Explanation of whether and why the payment was accepted. - object - object - `network_status` 'approved_by_network' | 'declined_by_network' | 'not_sent_to_network' | 'reversed_after_approval' — The status of the transaction with respect to the card network associated with the card. - `reason` string, nullable — Detailed explanation of the charge outcome. - `rule` string — Unique identifier of the matching rule used to evaluate the payment. - `seller_message` string — Detailed description of the outcome type and reason (intended for the merchant, not the customer). - `type` 'authorized' | 'blocked' | 'invalid' | 'issuer_declined' | 'manual_review' — Basic explanation of the charge's outcome. - `paid` boolean, required — Indicates whether the charge was successful or authorized for capture. - `payment_method_details` 'card' | 'ach' | 'paypal' | 'giftCard' — Indicates the payment method used for the charge. - `on_behalf_of` boolean — Indicates the transaction was made on someone's behalf. - `debt_payment` 'approved' | 'declined' | 'not_processed' — Indicates the status of the charge. - `receipt_email` string, nullable — Email address to which the charge receipt is sent. Receipts are sent only after the charge is paid. **Note:** Receipts are not sent in the sandbox environment. - `receipt_number` string, nullable — Receipt number of the charge. - `receipt_url` string, required — URL where the charge receipt is accessible. The receipt displays the latest state of the charge, including any refunds. If the charge is for an invoice, the receipt is displayed as an invoice. - `site_url` string — URL of the site performing the e-commerce transaction. **Default:** `clover.com` **Constraints:** Length: 4–13 characters. Allowed characters: Alphanumeric, periods (`.`), and hyphens (`-`) only. **Note:** Do not include protocol (for example, `https://`) or `www`. - `refunded` boolean, required — Indicates whether the charge was fully refunded or partial refunded. Values: True - Full refunded False - Partially refunded - `shipping` Shipping - `address` Address, required - `city` string, nullable — City of the customer's address. Can include district, suburb, town, or village. - `country` string, nullable — Country code. Format: 2 characters - `line1` string, nullable — First line of the customer's address. Can include the street address, PO box, or company name. - `line2` string, nullable — Second line of the customer's address. Can include the apartment, suite, unit, or building number. - `postal_code` string, nullable — Postal or ZIP code of the customer's address. - `state` string, nullable — State of the customer's address. Can include county, province, or region. - `carrier` string, nullable — Delivery service to ship the physical product. Example: DHL, Fedex, US Postal Service (USPS), and so on. - `name` string, nullable — Recipient name for the shipped product. - `phone` string, nullable — Phone number, including extension, of the recipient. - `tracking_number` string, nullable — Shipment number provided by the carrier. Use a comma-separated list for multiple tracking numbers. - `source` Source, nullable — Payment source of the charge. This can be a token or an alternate tender. - `id` string — Unique identifier (Clover token). - `object` string — Type of source. Example: Card or Bank account. - `address_city` string, nullable — City of the customer's address. Can include district, suburb, town, or village. - `address_country` string, nullable — Billing address country, if provided. - `address_line1` string, nullable — First line of the customer's address. Can include the street address, PO box, or company name. - `address_line1_check` 'pass' | 'failed' | 'unavailable' | 'unchecked', nullable — Result of the verification check of the address. - `address_line2` string, nullable — Second line of the customer's address. Can include the apartment, suite, unit, or building number. - `address_state` string, nullable — State of the customer's address. Can include county, province, or region. - `address_zip` string, nullable — Postal or ZIP code of the customer's address. - `address_zip_check` 'pass' | 'failed' | 'unavailable' | 'unchecked', nullable — Result of the verification check of the address postal code. - `brand` string, nullable — Card brand. - `country` string, nullable — 2-character country code. - `cvc_check` 'pass' | 'failed' | 'unavailable' | 'unchecked', nullable — Result of the verification check of the cvv code. - `exp_month` string — Card expiration month in 2-digit format. Format: mm - `exp_year` string — Card expiration year in 2-or 4-digit format. Format: yy or yyyy - `fingerprint` string — Unique identifier for this source. - `first6` string — First 6 numbers of the primary account number. - `funding` string — Type of card used for the payment. - `last4` string — Last 4 numbers of the primary account number. - `name` string — Cardholder's full name on the card. - `status` 'succeeded' | 'pending' | 'failed', required — Payment status of the charge. - `stored_credentials` StoredCredentials — Stored credentials for a transaction. For initial and subsequent payments with a saved card, stored credentials are available only with multi-pay (mTokens) tokens. Please ensure the `sequence` field within this object is correctly set to `FIRST` for the initial transaction or `SUBSEQUENT` for all others. See [Save a card for future transactions](https://docs.clover.com/dev/docs/save-a-card-for-future-transactions) for more information. - `sequence` 'FIRST' | 'SUBSEQUENT' — Indicates the sequence for an external multi-pay token. Values: FIRST - The initial transaction for a token, initiated by the CARDHOLDER. SUBSEQUENT - A SUBSEQUENT transaction using an existing token, can be initiated by the CARDHOLDER or the MERCHANT. - `is_scheduled` boolean — Indicates whether the transaction is scheduled or part of an installment. Values: True - Transaction is scheduled. False - Transaction is part of an installment. Installments are only available in the US. - `initiator` 'MERCHANT' | 'CARDHOLDER' — Indicates with whose consent the transaction is initiated. Values: Cardholder Merchant - `installment_info` InstallmentInfo — Installment information for the transaction. - `bill_pay_indicator` 'Recurring' | 'Installment' — Indicates whether the transaction is a recurring or installment payment. Values: Installment Recurring - For Canadian merchants, the value must be Recurring - `invoice_number` string — Invoice number of the installment or recurring transaction. Length: Max 12 characters - `description` string — Description of the `installment_info` object. - `total_count` integer — Total count of the transaction installments as per the cardholder agreement with the merchant. All customer-initiated transactions require 3DS authentication. Additionally, `total_count` is required for the following cards and transactions: **Discover® cards**, including JCB® (US domestic) and Diners® used for merchant-initiated installments and recurring transactions. Default: Not defined **India-issued Discover cards** used for merchant-initiated recurring transactions. **India-issued Visa® cards** used for recurring transactions. Values: 1 to 99; Default: 99 - `total_amount` integer — Total installment amount. Max 500,000 USD - `sequence_number` integer — Required for Discover card. Sequence of the transactions, displayed in ascending order, when multiple installment payments are submitted. Length: 2 - `amount_type` 'Fixed' | 'Variable' — Transaction account type applicable to Discover (including JCB and Diner) and Visa cards. All customer-initiated transactions require 3DS authentication. Additionally, `amount_type` is required for the following cards and transactions: **Discover cards**, including JCB (US domestic) and Diners are used for merchant-initiated installments and recurring transactions. **India-issued Discover cards** are used for merchant-initiated recurring transactions. **India-issued Visa cards** are used for recurring transactions. Default: Fixed - `interval` 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' | 'SEMI_MONTH' — Frequency of a recurring or installment or recurring payment. This field is required for: **Discover card** used for merchant-initiated installment or recurring transactions. **India-issued Visa cards** used for recurring transactions. - `interval_count` integer — Frequency counts of a installment or recurring payment. This field is required for: **Discover card** used for merchant-initiated installment or recurring transactions. **India-issued Visa cards** used for recurring transactions. - `soft_descriptor` SoftDescriptor — Soft descriptor information for a transaction. This information displays on the customer's card statement in place of the merchant's business information on record. - `dba_name` string — Merchant doing business as (DBA) name, product, or service. Length: Max 38 alphanumeric characters. - `street` string — Merchant's street address. - `city` string — Merchant's city. - `region` string — Merchant's state. Format: 2-character postal abbreviation (US only). - `postal_code` string — Merchant's postal code. - `country_code` string — Merchant's country code. Format: 3-digit; see the [Country code reference](https://docs.clover.com/docs/country-code-reference). - `merchant_contact_info` string — Merchant's phone number or email address. Format: Max 13 characters for Discover® and Visa® transactions. - `threeds` ThreedsValidationResult — 3DSecure validation result. - `validation_result` 'AUTHENTICATION_FAILED' | 'AUTHENTICATION_SUCCESSFUL' | 'ISSUER_DOES_NOT_PARTICIPATE' | 'ATTEMPTED_UNSUCCESSFULLY' | 'ATTEMPTED_SUCCESSFULLY' | 'NOT_POSSIBLE' — Indicates validation result of 3DSecure transaction. - `source` string — Source of the 3DSecure transaction. Example: `CLOVER` or `NON_CLOVER` - `gift_card` EcommGiftCardResponseExtra — Indicates meta data of the gift card. - `previous_balance` integer — Indicates the previous balance before the transaction was initiated. - `new_balance` integer — Indicates the updated balance after the transaction is completed. - `lock_amount` integer — Indicates the value on the card that was locked due to a balance lock transaction. - `expiration_date` string — Indicates the account expiration date. - `lock_id` integer — Unique lock number identifier for each balance lock record. The `lock_id` helps capture the authorized amount and is applicable for pre-auth and capture flow. - `number` string — Embossed card number on the gift card or the ift card number. Only applicable for virtual gift card activation. - `security_card_value` string — Gift card security code. Only applicable for virtual gift card activation. - `level2` PurchaseCardLevel2 — Additional data for purchase card transactions (US only). - `tax_amount` integer — Part of the transaction amount that indicates the sales tax. A `pc_order_number` is required when including a `tax_amount`. - `tax_indicator` 0 | 1 | 2 — Taxable status of the transaction. Values: 0 – No tax information provided. 1 – Tax amount is provided. 2 – Purchase item is tax exempt or non-taxable. - `purchase_identifier` string — Identifier, such as stock keeping unit (SKU), code or reference number that the merchant or customer uses to identify the purchase. - `pc_order_number` string — Order number or customer reference number reported as part of the purchase card data. - `discount_amount` integer — Discount amount for the transaction. Format: Cents - `freight_amount` integer — Freight amount included for the transaction. Format: Cents - `duty_amount` integer — Duty amount included for the transaction. Format: Cents - `destination_postal_code` string — Postal or ZIP code of the delivery location. - `ship_from_postal_code` string — Postal or ZIP code of the shipping location. - `destination_country_code` integer — Delivery location country code. Format: 3-digit code; see the [Country code reference](https://docs.clover.com/docs/country-code-reference). - `merchant_tax_id` string — Only for Mastercard®. Identifier (ID) for the tax the merchant collects for the transaction. - `product_description` string — Description of the purchased item. - `level3` PurchaseCardLevel3 — Additional data for purchase card level3 transactions (US only). Supported for Mastercard® and Visa® only. Purchase card level2 is mandatory for level3 transactions. - `service_code` string — Required for all non-keyed transactions and swiped transactions. Service code extracted from the track data. - `magnetic_Stripe_Ind` boolean — Indicates whether magnetic stripe card was used. Values: True - magnetic stripe swiped transaction False - `level3_line_items` Level3LineItem[] — List of level3 line items. - `item_description` string, required — Required for reduced interchange and for Mastercard®. ItemMerchandise description. Format: For Mastercard, level 3 must not be all 0s (zeros) or all high/low values. For Visa, level 3 must not be all spaces or all 0s (zeros). Length: Maximum 35 characters. - `product_code` string, required — Required for Mastercard and Visa. Product or Universal Product Code (UPC). Format: Must not be all spaces. - `unit_cost` integer, required — Unit cost of level3 line item. Format: For Visa must not be all spaces or 0s (zeros). - `quantity` number, required — Item quantity information; required for reduced interchange. Format: Must not be all spaces or 0s (zeros); Last 4 digits are considered decimal places, example: 20.0000 - `discount_amount` integer — Discount amount applied to the level3 line item. Format: For Visa level2 must not be all 0s (zeros), if a discount exists. - `unit_of_measure` string, required — Unit of measurement codes used for international trade. Required for reduced interchange for both Mastercard and Visa. See [Unit of Measurement codes](https://docs.clover.com/docs/units-of-measurement-codes). - `commodity_code` string — Required for Visa. Indicates classification of purchased items. - `saved_credentials_on_file` SavedCredentialsOnFile — Data about any surcharge or other fee applied to a transaction. - `tokenType` 'TRANSARMOR' — Multi-pay token type such as TransArmor. - `value` integer — The percentage of the total assessed as a surcharge or other fee. This value is set when a merchant is boarded to Clover Percentages are defined to four decimal places. For example, the value of a 3.5% surcharge is `35000` (3.5*10000). - `ref_num` string — Identifier of additional charges. - `ecomind` 'ecom' | 'moto' | 'retail' — Indicates the source of the card data. - `amount_captured` integer — Total amount captured for pre-auth transactions. - `livemode` boolean, required — Indicates whether the item is in production or sandbox. True - Item is in production False - Item is in sandbox - `metadata` object, required — Set of key-value pairs that you can attach to the object. This parameter is useful for storing additional information about the object in a structured format. Length: Maximum 500 characters - `object` 'order', required — Object type. Objects with the same type have the same value. - `returns` object, nullable - `data` OrderReturn[], required - `amount` integer, required — Total amount for the return in the smallest monetary unit of the merchant's currency. - `additional_charges` AdditionalCharges — Additional surcharge or other fee applied on the transaction. - `amount` integer — Amount of the additional charges applied on the transaction. Format: Cents - `id` string — Unique identifier of the additional charge. - `rate` integer — Item-specific tax of an additonal charge where a 10% rate is defined as 1000000. - `type` 'CREDIT_SURCHARGE' — Type of the additional charge collected on the transaction. - `created` integer, required — Creation time of the object (Unix timestamp in milliseconds). - `currency` string, required — Three-letter ISO 4217 currency code (in lowercase). - `id` string, required — Unique object identifier. - `items` OrderItem[], required — The item or items being returned. - `amount` integer, required — Amount of an item in the order. - `currency` string, required — Three-letter ISO 4217 currency code. - `description` string, required — Description of the item. - `inventory_id` union — UUID of the associated object for the line item. The value is expandable if it is not null. - string - Sku - `active` boolean, required — Indicates whether the item can be purchased. - `attributes` object, required — Set of product key-value pairs associated with and describing the item. This can be used for storing additional information about the item in a structured format. For example, for product attributes such as color and style, a SKU can have the following pairs: `{"color": "fuschia", "style": "bootcut"}`. - `created` integer, required — Displays results based on the object's created field. Values: String with a Unix timestamp (in milliseconds). or Dictionary of multiple options describing a time range. - `currency` string, required — Three-letter ISO 4217 currency code. - `id` string, required — Inventory item identifier. - `image` string, nullable — URL of an image for the SKU. - `livemode` boolean, required — Indicates whether the item is in production or sandbox. True - Item is in production False - Item is in sandbox - `metadata` object, required — Set of key-value pairs that you can attach to the object. This parameter is useful for storing additional information about the object in a structured format. Length: Maximum 500 characters - `object` 'sku', required — Object type. Objects with the same type have the same value. - `updated` integer, required — Time when the inventory item was modified. - `object` 'order_item', required — Object type. Objects with the same type have the same value. - `parent` union — DEPRECATED. UUID of the associated object for the line item. The value is expandable if it is not null. - string - Sku - `active` boolean, required — Indicates whether the item can be purchased. - `attributes` object, required — Set of product key-value pairs associated with and describing the item. This can be used for storing additional information about the item in a structured format. For example, for product attributes such as color and style, a SKU can have the following pairs: `{"color": "fuschia", "style": "bootcut"}`. - `created` integer, required — Displays results based on the object's created field. Values: String with a Unix timestamp (in milliseconds). or Dictionary of multiple options describing a time range. - `currency` string, required — Three-letter ISO 4217 currency code. - `id` string, required — Inventory item identifier. - `image` string, nullable — URL of an image for the SKU. - `livemode` boolean, required — Indicates whether the item is in production or sandbox. True - Item is in production False - Item is in sandbox - `metadata` object, required — Set of key-value pairs that you can attach to the object. This parameter is useful for storing additional information about the object in a structured format. Length: Maximum 500 characters - `object` 'sku', required — Object type. Objects with the same type have the same value. - `updated` integer, required — Time when the inventory item was modified. - `quantity` integer, nullable — If the `type` is `sku`, the number of instances of `parent` for the line item. - `tax_rates` union[] - union - TaxRatesRate — Tax rate object defining an item-level tax as a percentage (%). - … - TaxRatesAmount — Tax rate object defining a flat item-level tax amount. - … - TaxRatesUuid — Tax rate object defining an item-level tax with a unique identifier (ID). - … - `type` 'sku' | 'shipping', required — Line item type. - `livemode` boolean, required — Set to `true` if the object is in production. Set to `false` if the object is in sandbox. - `object` 'order_return', required — Object type. Objects with the same type have the same value. - `order` string — Order identifier. - `refund` string — Refund identifier. - `has_more` boolean, required — Set to `true` if there is another page of list items after the current page. - `object` 'list', required — Object type set to list. Objects with the same type have the same value. - `url` string, required — URL of the list. - `selected_shipping_method` string, nullable — Selected shipping method of the order. If present, the value is set from the `shipping_methods` list. For multiple shipping methods, the first method is automatically selected. - `shipping` Shipping - `address` Address, required - `city` string, nullable — City of the customer's address. Can include district, suburb, town, or village. - `country` string, nullable — Country code. Format: 2 characters - `line1` string, nullable — First line of the customer's address. Can include the street address, PO box, or company name. - `line2` string, nullable — Second line of the customer's address. Can include the apartment, suite, unit, or building number. - `postal_code` string, nullable — Postal or ZIP code of the customer's address. - `state` string, nullable — State of the customer's address. Can include county, province, or region. - `carrier` string, nullable — Delivery service to ship the physical product. Example: DHL, Fedex, US Postal Service (USPS), and so on. - `name` string, nullable — Recipient name for the shipped product. - `phone` string, nullable — Phone number, including extension, of the recipient. - `tracking_number` string, nullable — Shipment number provided by the carrier. Use a comma-separated list for multiple tracking numbers. - `shipping_methods` ShippingMethod[], nullable — List of supported shipping methods for the order. The shipping method can be set when paying for the order and updated as needed before the order ships. - `amount` integer, required — Total amount in the smallest monetary unit of the merchant's currency. - `currency` string, required — Three-letter ISO 4217 currency code (in lowercase). - `description` string, required — Container for user-facing information about the object. - `id` string, required — Unique object identifier. - `source` Source, nullable — Payment source of the charge. This can be a token or an alternate tender. - `id` string — Unique identifier (Clover token). - `object` string — Type of source. Example: Card or Bank account. - `address_city` string, nullable — City of the customer's address. Can include district, suburb, town, or village. - `address_country` string, nullable — Billing address country, if provided. - `address_line1` string, nullable — First line of the customer's address. Can include the street address, PO box, or company name. - `address_line1_check` 'pass' | 'failed' | 'unavailable' | 'unchecked', nullable — Result of the verification check of the address. - `address_line2` string, nullable — Second line of the customer's address. Can include the apartment, suite, unit, or building number. - `address_state` string, nullable — State of the customer's address. Can include county, province, or region. - `address_zip` string, nullable — Postal or ZIP code of the customer's address. - `address_zip_check` 'pass' | 'failed' | 'unavailable' | 'unchecked', nullable — Result of the verification check of the address postal code. - `brand` string, nullable — Card brand. - `country` string, nullable — 2-character country code. - `cvc_check` 'pass' | 'failed' | 'unavailable' | 'unchecked', nullable — Result of the verification check of the cvv code. - `exp_month` string — Card expiration month in 2-digit format. Format: mm - `exp_year` string — Card expiration year in 2-or 4-digit format. Format: yy or yyyy - `fingerprint` string — Unique identifier for this source. - `first6` string — First 6 numbers of the primary account number. - `funding` string — Type of card used for the payment. - `last4` string — Last 4 numbers of the primary account number. - `name` string — Cardholder's full name on the card. - `status` 'created' | 'paid' | 'canceled' | 'fulfilled' | 'returned' | 'partially_paid' | 'partially_refunded' | 'refunded', required — Current order status. - `status_transitions` StatusTransitions - `canceled` integer, nullable — Time stamps when the order was cancelled. - `fulfilled` integer, nullable — Time stamps when the order was fulfilled. - `paid` integer, nullable — Time stamps when the order was paid. - `returned` integer, nullable — Time stamps when the order was returned. ## Other responses - `default` — Error response. --- [API](https://skmtc.net/clover/apis/platform-api.md) · [All operations](https://skmtc.net/clover/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clover/platform-api/versions/08da265101a3/schema)