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

Validate API Key and Email

URL

http://api.putler.com/inbound/

HTTP Method

HEAD

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

Input Parameters

Parameter	Value
action	validate

Response

Status Code	Description
200	Valid User
401	Unauthorised User

Store

Push transactions into Putler

URL

http://api.putler.com/inbound/

HTTP Method

POST

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

Input Parameters

Parameter	Value
action	store

Request Header

Parameter	Value
Content-Type	The MIME type of the request body. application/json (Default) text/csv application/xml

tip

While sending transactions in CSV, CSV file should have header fields

Request

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 for Shopping cart payment

"Date","Time","Source","Name","Type","Status","Currency","Gross","Fee","Net","From_Email_Address","Transaction_ID","Item_Title","Item_ID","Shipping_and_Handling_Amount","Option_1_Name","Option_1_Value","Quantity","Note","Address_Line_1","Address_Line_2","Town_City","State_Province","Zip_Postal_Code","Country","Contact_Phone_Number"
"10/24/13",16:02:00,"XYZ Gateway","Chirag B","Shopping Cart Payment Received","Completed","USD",409,0,409,"john@putler.com",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,,,"john@putler.com",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,,,"john@putler.com",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,,,"john@putler.com",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 for Buy Now payment

"Date","Time","Name","Type","Status","Currency","Gross","Fee","Net","From_Email_Address","Transaction_ID","Item_Title","Item_ID","Option_1_Name","Invoice_Number","Quantity","Balance","Address_Line_1","Address_Line_2","Town_City","State_Province","Zip_Postal_Code","Country","Contact_Phone_Number"
10/29/13,03:24:52,"Chirag B","Web Accept Payment Received","Completed","USD",29,-1.14,27.86,"john@putler.com","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 for Refund Transaction

"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,"john@putler.com","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,,,"john@putler.com","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,"john@putler.com","5L671541UP2927356",,,,"5X16702303884432U",,,,,,,

Specifics on Subscription Transaction

Each subscription transaction will have only 1 entry

Required feilds: Subscription_ID

Sample CSV with headers Sfor Subscription Transaction

"Date","Time","Name","Type","Status","Currency","Gross","Fee","Net","From_Email_Address","Transaction_ID","Item_Title","Item_ID","Balance","Address_Line_1","Town_City","State_Province","Zip_Postal_Code","Country","Contact_Phone_Number","Subscription_ID"
10/29/13,03:36:11,"Chirag B","Recurring Payment Received","Completed","USD",2,-0.36,1.64,"john@putler.com","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

info

It takes about 30 mins - 40 mins to reflect the data on the Putler Dashboard after pushing the data through the Putler Inbound API