Inbound API – Putler

If your data source/ service is not directly integrated within Putler, you can take a look at this step-by-step documentation to connect it within Putler. Once connected, Putler will automatically start pulling in data from your respective data source/service.

If you need any help/ have any queries, do reach out to us.

Let’s get started.

API Authentication

API authentication is handled with HTTP Basic access authentication.(email:token)

If you are not using HTTP basic-auth, you can authenticate using input parameters

Input Parameters
Parameter Description
email The email you use to login to Putler
token API key generated from Putler

Obtaining your API Key

Create a new account in Putler of type “Putler Inbound API”. You will get a Key to use in all the API calls.


API Resource


Validate API Key and Email



HTTP Method

If you are not using HTTP HEAD, you can validate using action input parameters

Input Parameters
Parameter Value
action validate


Status Code Description
200 Valid User
401 Unauthorised User



Push transactions into Putler



HTTP Method

If you are not using HTTP POST, you can push transactions using action input parameters

Input Parameters
Parameter Value
action store


Request Header
Content-Type The MIME type of the request body.

  • application/json (Default)
  • text/csv
  • application/xml
NOTE:While sending transactions in CSV, CSV file should have header fields


Field Required Description
Date Yes The date this order was created(MM/DD/YYYY)
Time Yes The time this order was created in GMT- 24 hour format (HH:MM:SS)
Type Yes
  • Main transaction – Shopping Cart Payment Received
  • Line item transaction – Shopping Cart Item
  • Buy now transaction- Web Accept Payment Received
  • Refund transaction- Refund
  • Subscription – Recurring Payment Received
Transaction_ID Yes Transaction ID of the order
Item_Title Yes
  • Main transaction – “Shopping Cart”
  • Line item/Buy now/Subscription transaction – The title of the product
Quantity Yes
  • Main transaction – Count of Line Items
  • Line item transaction – The quantity of the purchase for this product
Source Name of Payment gateway/ Shopping carts
Name Customer name
Status Status of the Order(Pending, Completed, Cancelled, Partially Refunded, Refunded)
Currency A 3-character currency code of the currency being used in this transaction (default is USD)
Gross Order total, including tax(default is 0.00)
Fee Total Fees paid for this transaction (default is 0.00)
Net Order total, inculding tax and excluding fees (default is 0.00)
From_Email_Address Contact email address
Item_ID Line item/Buy now/Subscription transaction -> The ID of the product
Shipping_and_Handling_Amount The value of shipping and handling cost (default is 0.00)
Insurance_Amount Total shipping insurance costs for this order (default is 0.00)
Discount Amount of discount for this transaction (default is 0.00)
Sales_Tax Total Tax paid for this transaction (default is 0.00)
Option_1_Name For Line item -> Product Option/Attribute -1 name
If there are more than 2 Option/Attribute, Send comma seperated list {Color:Red, Size:XL, Style:Simple}
Option_1_Value For Line item -> Product Option/Attribute -1 value
Option_2_Name For Line item -> Product Option/Attribute -2 name
Option_2_Value For Line item -> Product Option/Attribute -2 value
Reference_Txn_ID For Refund Transaction -> Transaction ID of parent Transaction
Invoice_Number Invoice or Tracking number
Balance Account balance if any (default is 0.00)
Note Any additional Order notes
Address_Line_1 Line 1 of street address
Address_Line_2 Line 2 of street address
Town_City Name of city
State_Province State/province name
Zip_Postal_Code Zip or postal code
Country Country full name
Contact_Phone_Number Contact phone number
Subscription_ID For Subscription transaction ->Subscription id

Specifics on Shopping cart payment

  • For more than 1 Line items
  • Seperate Transactions for each line items


Eg:  Order with 3 Line items, there will be 4 entries, viz. 1 entry for main order and 3 entries for each line items

Sample CSV with headers

"10/24/13",16:02:00,"XYZ Gateway","Chirag B","Shopping Cart Payment Received","Completed","USD",409,0,409,"",46,"Shopping Cart",,10,,,3,"Order Note","Powai","Borivali","mumbai","MH",444554,"IN",95323135
"10/24/13",16:02:00,"XYZ Gateway","Chirag B","Shopping Cart Item","Completed","USD",149,,,"",46,"Product-1","P-45",0,"Color","Black",1,,"Powai","Borivali","mumbai","MH",444554,"IN",95323135
"10/24/13",16:02:00,"XYZ Gateway","Chirag B","Shopping Cart Item","Completed","USD",150,,,"",46,"Product-2","P-37",0,"Color","Red",2,,"Powai","Borivali","mumbai","MH",444554,"IN",95323135
"10/24/13",16:02:00,"XYZ Gateway","Chirag B","Shopping Cart Item","Completed","USD",100,,,"",46,"Product-3","P-19",0,"Color","Yellow",1,,"Powai","Borivali","mumbai","MH",444554,"IN",95323135

Specifics on Buy Now payment

Each transaction will have only 1 entry.

Sample CSV with headers

10/29/13,03:24:52,"Chirag B","Web Accept Payment Received","Completed","USD",29,-1.14,27.86,"","5EA652410Y693721T","Product-1","MUTD","Color:red, Size: XL, Style:Simple","RT-9871",1,819.57,"Street1","Street2","City","CA",95101,"United States",98512154552

Specifics on Refund Transaction

New entry for Each refunds
Required feilds: Reference_Txn_ID

Sample CSV with headers

"Date"," Time"," Name"," Type"," Status"," Currency"," Gross"," Fee"," Net","From_Email_Address","Transaction_ID","Item_Title","Item_ID"," Sales_Tax"," Reference_Txn_ID"," Quantity","Address_Line_1","Address_Line_2","Town_City","State_Province","Zip_Postal_Code"," Country"
10/29/13,13:05:29,"Chirag B","Shopping Cart Payment Received","Partially Refunded","USD",50.5,-1.76,48.74,"","5X16702303884432U","Shopping Cart",,0.5,,1,"Street1","Street2","City","CA",95101,"United States"
10/29/13,13:05:29,"Chirag B","Shopping Cart Item","Partially Refunded","USD",50,,,"","5X16702303884432U","Product-1","RM-7",,,1,"Street1","Street2","City","CA",95101,"United States"
10/29/13,14:05:38,"Chirag B","Refund","Completed","USD",-20,0.58,-19.42,"","5L671541UP2927356",,,,"5X16702303884432U",,,,,,,

Specifics on Subscription Transaction

Each subscription transaction will have only 1 entry
Required feilds: Subscription_ID

10/29/13,03:36:11,"Chirag B","Recurring Payment Received","Completed","USD",2,-0.36,1.64,"","0G565730603123547","Weather Updates","MET-2013",821.21,"1Test address","San Jose","CA",95131,"United States",6543332132,"Sub-7562396"

Error Codes

Status Code Description
400 Authorization Failed
401 Unauthorised User
404 Unknown Action
500 Could not store transactions