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

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

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

"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

"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

"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

"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