Create a service charge on an order

post https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders/{orderId}/order_fee_line_items

Creates a service charge to an order.

Path Params

mId

string

required

Merchant identifier.

orderId

string

required

Order identifier.

Body Params

string

Unique identifier.

item

object

A reference to the inventory item that was used to create this line item. Note that since this a reference the item can be changed and deleted any time such that it no longer matches this line item.

colorCode

string

Hex code representation of the color assigned to item in the form of #fff, #ffffff, or #ffffffff. Note that item color can be changed and deleted any time such that it no longer matches this line item

name

string

Line item name.

alternateName

string

Alternate name of the line item.

price

int64

Price of the item, typically in cents of merchant currency. When unit quantity is not null then this is the price for a single unit and is not the complete price.

priceWithModifiers

int64

Price of item after adding all modifications. This is used only for reporting.

priceWithModifiersAndItemAndOrderDiscounts

int64

Price of item after adding all modifications and subtracting all line item and order level discounts. This is used only for reporting.

unitQty

integer

This is applicable only if the item is priced by quantity of a unit. The item must have a priceType of PER_UNIT. The value is a fixed-point integer with scaling factor of 1000 (e.g. if charging per ounce, the value should be set to 2500 for 2.5 ounces). To compute the complete price perform the following calculation: PRICE * (UNIT QTY / 1000). If the item doesn’t have a priceType of PER_UNIT, then unitQty is ignored.

unitName

string

Unit name (e.g. oz, lb, etc) if priced by unit, otherwise null.

itemCode

string

note

string

printed

boolean

Defaults to false

True if this line item has been printed out on an order printer at least once already.

exchangedLineItem

object

binName

string

userData

string

createdTime

int64

orderClientCreatedTime

int64

discounts

array of objects

List of discounts applied to the line item. Each line item on an order may have zero or more percentage or amount discounts. Line item discounts are separate from order-level discounts (which are applied to the order subtotal).

discounts

orderLevelDiscounts

array of objects

List of order level discounts attributed to this line item. Amounts are rounded to the nearest penny. This is for reporting purposes only. These rounding approximates are not used when calculating the transaction.

orderLevelDiscounts

discountAmount

integer

Unnamed fixed discount amount in cents. Or, in reporting, this may be the calculated sum of all the line item discounts.

orderLevelDiscountAmount

int64

The calculated sum of order level discounts attributed, approximately to the nearest cent, to this the line item. This is only used in reporting.

exchanged

boolean

Defaults to false

modifications

array of objects

List of references to modifications applied to this line item.

modifications

tags

array of objects

List of tags associated with this line item.

tags

refunded

boolean

Defaults to false

True if this line item has been refunded

refund

object

direct item refund

isRevenue

boolean

Defaults to false

True if this item should be counted as revenue, for example gift cards and donations would not.

taxRates

array of objects

Tax rates that apply to this line item

taxRates

payments

array of objects

Payments that apply to this line item

payments

revenueAmount

int64

Revenue collected for this. This field is only used in reporting.

quantitySold

number

Quantity sold for this line item. This field is only used in reporting

printGroup

object

Optional reference to the print group that this line item belongs to.

hidden

boolean

Defaults to false

True if this line item has been marked as hidden on User Interface like Orders page and receipts

percentage

integer

For percentage based order fee line item, percent to charge times 10000, e.g. 12.5% will be 125000

orderFee

object

A reference to the inventory order fee that was used to create this line item. Note that since this a reference the order fee can be changed and deleted any time such that it no longer matches this line item.

isOrderFee

boolean

True if this line item is an order fee line item

isPlatformOrderFee

boolean

True if this line item is an platform order fee line item

orderFeeType

string

Used to define type of order fee line item, e.g. gratuity.

Response

Response body

object

string

Unique identifier.

item

object

A reference to the inventory item that was used to create this line item. Note that since this a reference the item can be changed and deleted any time such that it no longer matches this line item.

string

Unique identifier

colorCode

string

name

string

Line item name.

alternateName

string

Alternate name of the line item.

price

int64

Price of the item, typically in cents of merchant currency. When unit quantity is not null then this is the price for a single unit and is not the complete price.

priceWithModifiers

int64

Price of item after adding all modifications. This is used only for reporting.

priceWithModifiersAndItemAndOrderDiscounts

int64

Price of item after adding all modifications and subtracting all line item and order level discounts. This is used only for reporting.

unitQty

integer

unitName

string

Unit name (e.g. oz, lb, etc) if priced by unit, otherwise null.

itemCode

string

note

string

printed

boolean

Defaults to false

True if this line item has been printed out on an order printer at least once already.

exchangedLineItem

object

string

Unique identifier

binName

string

userData

string

createdTime

int64

orderClientCreatedTime

int64

discounts

array of objects

discounts

object

string

Unique identifier

discount

object

If this item is based on a standard discount, this will point to the appropriate inventory.Discount

approver

object

The person that authorized a discount

name

string

required

Name of the discount

amount

integer

Discount amount in fraction of currency unit (e.g. cents) based on currency fraction digits supported

percentage

integer

Discount amount in percent

orderLevelDiscounts

array of objects

orderLevelDiscounts

object

string

Unique identifier

discount

object

If this item is based on a standard discount, this will point to the appropriate inventory.Discount

approver

object

The person that authorized a discount

name

string

required

Name of the discount

amount

integer

Discount amount in fraction of currency unit (e.g. cents) based on currency fraction digits supported

percentage

integer

Discount amount in percent

discountAmount

integer

Unnamed fixed discount amount in cents. Or, in reporting, this may be the calculated sum of all the line item discounts.

orderLevelDiscountAmount

int64

The calculated sum of order level discounts attributed, approximately to the nearest cent, to this the line item. This is only used in reporting.

exchanged

boolean

Defaults to false

modifications

array of objects

List of references to modifications applied to this line item.

modifications

object

string

name

string

the name of the modifier when it was applied

alternateName

string

amount

int64

the additional cost of the modifier when it was applied

modifier

object

The modifier object. Values from the Modifier are copied to the Modification at the time that the order is placed. Modifier values may change after the modification is created.

quantitySold

int64

This is only used in reports. The count of how many of these modifiers that were sold.

tags

array of objects

List of tags associated with this line item.

tags

object

string

Unique identifier

name

string

required

Tag name

showInReporting

boolean

Defaults to false

True if tag is a summary label in the reporting app

items

array of objects

Items associated with this tag

items

object

string

Unique identifier

printers

array of objects

Printers associated with this tag

printers

object

string

Unique identifier

refunded

boolean

Defaults to false

True if this line item has been refunded

refund

object

direct item refund

string

Unique identifier

orderRef

object

The order with which the refund is associated

device

object

Device which processed the transaction for this refund, a 128-bit UUID, not a normal base-13 Clover ID.

amount

int64

Total amount refunded, including tax and tip

taxAmount

integer

Tax amount refunded

tipAmount

integer

Tip amount refunded

createdTime

int64

The time when the refund was recorded on the server

clientCreatedTime

int64

The time when the refund was recorded on the client

deletedTime

int64

The time when the refund was deleted on the server

gatewayProcessingTime

int64

The time when the refund was processed by the gateway

payment

object

The payment with which the refund is associated

employee

object

lineItems

array of objects

lineItems

object

string

Unique identifier

overrideMerchantTender

object

The tender type associated with this payment, e.g. credit card, cash, etc.

taxableAmountRates

array of objects

taxableAmountRates

object

string

Tax rate id.

name

string

Tax rate name. This field is optional.

taxableAmount

int64

The sub-total of line items that the tax was based on. For VAT, this amount includes tax. For all others, this amount does not include tax.

rate

int64

The tax rate. 100% = 1e7.

isVat

boolean

Whether the taxable amount includes tax.

taxAmount

int64

The amount of tax collected. In cases where there are multiple payments for an order then it may be necessary to add an extra cent of tax to the last payment.

transactionRef

object

The refund with which the tax rate is associated

isDefault

boolean

Whether the tax rate was configured as a default tax rate at the time that the refund was created.

serviceChargeAmount

object

additionalCharges

array of objects

additionalCharges

object

string

Additional charge id

amount

int64

Amount of the additional charge

rate

int64

Percent rate of the additional charge times 10000

type

string

The type of additional charge

INTERAC CREDIT_SURCHARGE CONVENIENCE_FEE INTERAC_V2 DELIVERY_FEE

attributes

object

refundExtraData

object

germanInfo

object

German region-specific information

appTracking

object

Tracking information for the app that created this refund.

voided

boolean

voidReason

string

cardTransaction

object

Information about the card used for credit or debit card refunds

transactionInfo

object

Transaction information

merchant

object

externalReferenceId

string

The external reference id if associated with the refund

authCode

string

Auth code generated by the acquire

status

string

Status of the refund.It can be Fail/Success/Pending

FAIL SUCCESS PENDING VOIDED

oceanGatewayInfo

object

Ocean Gateway info - for India region

reason

string

Reason why the refund was initiated

fxInfo

object

Associated GEP exchange rate information

closeoutBatchInfo

object

Information about the Batch used for payments

isRevenue

boolean

Defaults to false

True if this item should be counted as revenue, for example gift cards and donations would not.

taxRates

array of objects

Tax rates that apply to this line item

taxRates

object

string

name

string

required

taxType

string

to support Argentina's tax type

VAT_TAXABLE VAT_NON_TAXABLE VAT_EXEMPT INTERNAL_TAX PARTNER_TAX ORDER_FEES

rate

int64

For percentage based discounts like sales tax

isDefault

boolean

items

array of objects

Items associated with this tax rate

items

object

string

Unique identifier

taxAmount

integer

For a flat tax like recycling redemption fee, expressed as number of cents

deletedTime

integer

Timestamp when tax rate was last deleted

modifiedTime

integer

Timestamp when tax rate was last modified

payments

array of objects

Payments that apply to this line item

payments

object

string

Unique identifier; TBD this is confusing because it's used as either line item id or payment id

percentage

int64

Percent of this line item covered by this payment

binName

string

Bin this line item payment was for

refunded

boolean

Payment has been refunded

revenueAmount

int64

Revenue collected for this. This field is only used in reporting.

quantitySold

number

Quantity sold for this line item. This field is only used in reporting

printGroup

object

Optional reference to the print group that this line item belongs to.

string

Unique identifier

hidden

boolean

Defaults to false

True if this line item has been marked as hidden on User Interface like Orders page and receipts

percentage

integer

For percentage based order fee line item, percent to charge times 10000, e.g. 12.5% will be 125000

orderFee

object

string

Unique identifier

isOrderFee

boolean

True if this line item is an order fee line item

isPlatformOrderFee

boolean

True if this line item is an platform order fee line item

orderFeeType

string

Used to define type of order fee line item, e.g. gratuity.

Language

Credentials

Bearer


xxxxxxxxxx
19
1
curl --request POST \
2
     --url https://apisandbox.dev.clover.com/v3/merchants/mId/orders/orderId/order_fee_line_items \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json' \
5
     --data '
6
{
7
  "printed": "false",
8
  "exchanged": "false",
9
  "refunded": "false",
10
  "refund": {
11
    "transactionInfo": {
12
      "isTokenBasedTx": "false",
13
      "emergencyFlag": "false"
14
    }
15
  },
16
  "isRevenue": "false",
17
  "hidden": "false"
18
}
19
'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Successful response. Service charge is displayed.