Release NotesAnnouncementsVideosCommunityBlog
Guides

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 objectDescription
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 percentageTo set a tax percentage, set the rate as an integer. For example, use 1000000 for a 10% tax.
Tax as amountTo 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:

SubtotalTip
Correctamount=2716tip_amount=300
Incorrectamount=3016tip_amount=300

Updated 14 days ago