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 help or have questions, feel free to reach out to us.

API Authentication

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

If you are not using HTTP Basic Auth headers, you can pass authentication credentials directly as input parameters in the request body.

Obtaining your API Key

API Resource

Validate

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 (Push Data)

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

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

Request Headers:

Transaction Data Model & Fields

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

• All data must be sent as an array of transactions, even when sending a single entry.
• 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 / request: 1 main order record + 3 line item records.

Request Fields Specification

Specifics on Shopping cart payment

• For orders with multiple line items, send separate transaction records for each line item.
• For example, an order with 3 line items requires 4 records: 1 entry for the main order header and 3 entries for each line item, all sent together in a single request.

Transaction Types

Quantity Rules

• Main Transaction: Sum of all line item quantities
• Line Item: Quantity purchased for that specific product

Complete 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"
  }
]

Limits & Performance

• Max Request Size: 30 MB
• Recommended Batch Size: 1,000–2,000 rows per batch (optimizes processing speed and avoids timeouts)
• Data Refresh Time: Ingested data appears in the Putler dashboard within 30–40 minutes

Specifics on Shopping Cart CSV Format

Specifics on Buy Now payment

Each transaction will have only 1 entry.

Specifics on Refund Transaction

New entry for each refund.

Required field: Reference_Txn_ID

Specifics on Subscription Transaction

Each subscription transaction will have only 1 entry.

Required field: Subscription_ID

Refund Handling

Refunds must be sent as separate transactions.

Refund Example

[
  {
    "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"
  }
]

Refund Rules

• Transaction_ID must be unique.
• Reference_Txn_ID links to the original order’s Transaction_ID.
• Gross must be negative.
• A refund is a single entry (no child line items required).

Refund Strategies

• Option 1 (Recommended): Send the refund separately as its own transaction with Reference_Txn_ID. This preserves complete transactional history and ensures accurate revenue and refund accounting.
• Option 2: Update the existing order’s amount and status directly. This is simpler but less granular for historical tracking.

Duplicate Handling

• Transaction_ID is the unique primary key for every record.
• Re-sending a transaction with an identical Transaction_ID updates the existing record without creating duplicates.

Status Values

Error Codes

Common Issues & Fixes

1. 400 Validation Failed

   • Data not wrapped in an array: Wrap your payload in an array [ { ... } ] even if sending a single transaction.
   • Missing required fields (e.g. Date, Time, Type, Transaction_ID, Quantity, Item_Title).
   • Line items missing for shopping cart transactions.
   • Incorrect Type or Status value.
   • Invalid refund structure (e.g. missing Reference_Txn_ID or non-negative Gross).

2. Data Not Appearing in Dashboard

   • Inbound data requires approximately 30–40 minutes to process and reflect across Putler dashboards.
   • Verify all required fields are present and correctly spelled.
   • Check that date and time formats conform to MM/DD/YYYY and HH:MM:SS (GMT).

3. Invalid or Unrecognized Fields

   • Putler silently ignores unrecognized fields.
   • Examples of invalid field names: Order_ID (use Transaction_ID), Payment_Method (use Source), From_Name (use Name).

4. Refund Not Linked to Order

   • Ensure Reference_Txn_ID exactly matches the Transaction_ID of the parent order.

Best Practices

• Always send the main order transaction and its child line items together in a single request payload.
• Use unique and immutable Transaction_ID values.
• For bulk imports, batch transactions in chunks of 1,000–2,000 rows (max 30 MB per payload).
• Send refunds as separate transactions for accurate reporting.
• Ensure the JSON data payload is passed in the request body (not as URL query parameters).

Need Help?

If you are still facing issues or need assistance configuring your Inbound API integration:

• Double-check your payload structure and required field mappings against the specification tables above.
• Reach out to our team at Putler Support.