Setting Up Putler Inbound API and Sending Data

If your data source or custom platform is not directly integrated within Putler, you can use Putler’s Inbound API to push custom sales, customer records, and transaction data into Putler. Once connected, Putler automatically aggregates your custom store records into your unified analytics dashboards.

If you need any assistance, feel free to reach out to our support team.

1. API Authentication

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

If you are not using HTTP Basic Auth headers, you can pass authentication credentials directly in the request payload.

2. Obtaining Your API Key

3. API Resources

Validate Endpoint

Verify that your API key and email credentials are valid before sending transactions.

• URL: http://api.putler.com/inbound/
• HTTP Method: HEAD (or POST with action: validate)

Response Codes:

Store Endpoint (Push Data)

Push order, product, and customer transaction records into Putler.

• URL: http://api.putler.com/inbound/
• HTTP Method: POST

Request Headers:

4. Transaction Data Model & Fields

Putler uses a flat transaction model (similar to PayPal ledger exports):

• Each line item in an order is sent as an individual record.
• The parent order header and its child line items share the same Transaction_ID.
• For an order with 3 distinct items, submit 4 total records in a single array: 1 main order record + 3 line item records.

Request Fields Specification

Transaction Types Reference

Order Status Values

5. Complete JSON Payload Example

[
  {
    "Date": "05/01/2026",
    "Time": "12:00:00",
    "Type": "Shopping Cart Payment Received",
    "Status": "Completed",
    "Transaction_ID": "ORD123",
    "Name": "John Doe",
    "From_Email_Address": "john@example.com",
    "Currency": "USD",
    "Gross": "100.00",
    "Quantity": "5",
    "Item_Title": "Shopping Cart"
  },
  {
    "Date": "05/01/2026",
    "Time": "12:00:00",
    "Type": "Shopping Cart Item",
    "Status": "Completed",
    "Transaction_ID": "ORD123",
    "Item_Title": "Product A",
    "Quantity": "2"
  },
  {
    "Date": "05/01/2026",
    "Time": "12:00:00",
    "Type": "Shopping Cart Item",
    "Status": "Completed",
    "Transaction_ID": "ORD123",
    "Item_Title": "Product B",
    "Quantity": "3"
  }
]

6. Refund Handling

Refunds must be submitted as distinct transactions with a negative Gross amount and linked via Reference_Txn_ID:

[
  {
    "Date": "05/02/2026",
    "Time": "14:00:00",
    "Type": "Refund",
    "Status": "Completed",
    "Transaction_ID": "ORD123_R1",
    "Reference_Txn_ID": "ORD123",
    "Gross": "-30.00",
    "Item_Title": "Product A",
    "Quantity": "1",
    "Name": "John Doe",
    "From_Email_Address": "john@example.com"
  }
]

7. Error Codes & Troubleshooting

Common Issues and Solutions

1. 400 Bad Request: Ensure your payload is sent as an array of objects [...], even when pushing a single order.
2. Duplicate Data: Re-sending a transaction with an identical Transaction_ID safely updates the existing record without creating duplicates.
3. Data Refresh Delay: Data ingested via Inbound API is processed and reflected in your Putler dashboards within 30–40 minutes.
4. Unrecognized Fields: Any custom fields not in the specification table are safely ignored during processing.