Creating and paying for orders (SDK)

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.

Creating an order

To create an order, call the create() method 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"
}

Paying for an order with a source

To pay for an order using a tokenized card, call the pay() method 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
   }
}

Adding 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


Did this page help you?