Create and pay for orders (SDK)

North America—United States and Canada

Most applications need to allow merchants to manage order data that payments are associated with. The Ecommerce SDKs provide resources for performing order-related actions.

1. Create an order

To create an order, call the [create an order](https://docs.clover.com/reference/postorders) endpoint and pass in the minimum required order information:

currency
email
items

from clover import Order

order = Order.create(
    currency='usd',
    email='[email protected]',
    items=[
        {
            'amount': 1358,
            'currency': 'usd',
            'description': 'Lemon cupcake with blackberry frosting',
            'quantity': 2,
            'tax_rates'=[
                {
                    'name': 'Sale',
                    'tax_rate_uuid': '{tax_uuid}'
                }
            ]
        }
    ]
)

require('dotenv').config();
const Clover = require("clover-ecomm-sdk");

let ACCESS_TOKEN = process.env.ACCESS_TOKEN;
let ENVIRONMENT = process.env.ENVIRONMENT;

const cloverInst = new Clover(ACCESS_TOKEN, {
  environment: ENVIRONMENT
});

let order = cloverInst.orders.create({
    currency: 'usd',
    email:'[email protected]',
    items:{
        'amount': 1358,
        'currency': 'usd',
        'description': 'Lemon cupcake with blackberry frosting',
        'quantity': 2,
      	'tax_rates':{'name':'Sale','tax_rate_uuid':'{tax_uuid}'}
    }
});

In this example, the item-level tax is set using the tax_rates object. You can set the tax value for each item in three ways.

Tax object	Description
Tax as UUID (recommended)	To set the tax based on merchant tax information, use `tax_rate_uuid`. This is the recommended approach. Taxes are set under Setup > Taxes & Fees on the Merchant Dashboard. You can retrieve this merchant tax information with `/v3/merchants/{mId}/tax_rates`.
Tax as percentage	To set a tax percentage, set the `rate` as an integer. For example, use `1000000` for a 10% tax.
Tax as amount	To set a flat fee, use `tax_amount`.

This returns an order object in JSON. The id value is the unique identifier of the order needed for other requests.

{
    "id": "6WDD8Y1AQ7WCT",
    "object": "order",
    "amount": 2716,
    "tax_amount": 272,
    "amount_returned": 0,
    "currency": "usd",
    "created": 1580416974000,
    "email": "[email protected]",
    "items": [
        {   
            "type": "sku",
            "quantity": 2,
            "amount": 1358,
            "currency": "usd",
            "description": "Lemon cake with blackberry frosting"
          	"tax_rates": [
                {
                   "name" : "Sale",
      						 "tax_rate_uuid" : "77FAGR71YYD5M"
                }
            ]
        }
    ],
        {   
            "type" : "tax",
            "amount" : 272,
            "description" : "Sales Tax"
        }
    ],
    "status": "created"
}

2. Pay for an order with a source

To pay for an order using a tokenized card, call the pay for the order endpoint and pass in the order's ID and a payment source.

import clover

pay = clover.Order.pay(orderId, source='clv_1TSTSpbfbN6Jh5CqCm3bMQne')

require('dotenv').config();
const Clover = require("clover-ecomm-sdk");

let ACCESS_TOKEN = process.env.ACCESS_TOKEN;
let ENVIRONMENT = process.env.ENVIRONMENT;

const cloverInst = new Clover(ACCESS_TOKEN, {
  environment: ENVIRONMENT
});

let pay = cloverInst.orders.pay(
  orderId,
  {source:'clv_1TSTSpbfbN6Jh5CqCm3bMQne'},
  function(err, order) {
    //handle errors and successful payment
  }
)

📘
NOTE
In case you are adding a customer while creating an order, you can set the source value to the customer UUID while paying for the created order.

The card is charged for the full order amount, and an order object is returned showing the status as paid. See the REST API Reference for complete information about the returned values.

{
   "id": "6WDD8Y1AQ7WCT", 
   "object": "order", 
   "amount": 2716,
   "tax_amount": 272,
   "amount_paid": 2716,
   "tax_amount_paid": 272,
   "currency": "usd", 
   "charge": "5E1ZZ9JJMA5Z6",
   "created": 1582301374000,
   "email": "[email protected]",
   "ref_num": "015600501490",
   "auth_code": "OK2183",
   "items": [
       {
           "quantity": 2,
           "amount": 1358,
           "description": "Lemon cake with blackberry frosting"
           "tax_rates": [
               {
                   "name": "Sale",
                   "rate": 1000000
               }
           ]
       }
   ],
   ...
   card details
   ...
   "status": "paid",
   "status_transitions": {
       "paid": 1582301378011
   }
}

3. Add a tip to your order

You can use the tip_amount (in cents) value to add a tip before paying for an order.

import clover

pay = clover.Order.pay(orderId, tip_amount=300,
                       source='clv_1TSTSpbfbN6Jh5CqCm3bMQne')

require('dotenv').config();
const Clover = require("clover-ecomm-sdk");

let ACCESS_TOKEN = process.env.ACCESS_TOKEN;
let ENVIRONMENT = process.env.ENVIRONMENT;

const cloverInst = new Clover(ACCESS_TOKEN, {
  environment: ENVIRONMENT
});

let pay = cloverInst.orders.pay(
  orderId,
  {tip_amount: 300, source:'clv_1TSTSpbfbN6Jh5CqCm3bMQne'},
  function(err, order) {
    //handle errors and successful payment
  }
)

Calculations with tips

Always submit the charge amount and tip separately. In the above Python example, for a subtotal of $27.16 and a tip of $3:

	Subtotal	Tip
Correct	`amount=2716`	`tip_amount=300`
Incorrect	`amount=3016`	`tip_amount=300`

Updated 4 days ago

1. Create an order

2. Pay for an order with a source

📘NOTE

3. Add a tip to your order

Calculations with tips

📘
NOTE