Transactional Data API Guide

The Transactional Data API enables you to send, update, and manage transactional data with Replenit. This guide outlines the available endpoints, payload structures, and best practices for integration.

Overview #

The API allows you to manage transactional data, such as purchases and product details, ensuring accurate replenishment reminders and analytics. The Product ID in the transaction payload serves as a differentiator for replenishment reminders across SKUs. For example, if a perfume has SKUs for 100ml, 50ml, and 30ml sizes, all with the same Product ID, reminders will consider usage across all SKUs.

Base URL #

https://services.replen.it

Authorization #

All routes require an Access Token with the correct permission level in the Authorization header. You can access your client ID and Access Token details in the platform under the Data Health and Management section.

Endpoints #

Field Descriptions #

Identifiers (Object) #

Transaction (Object) #

Line Items (Array) #

Sample Payloads #

1. Single Transaction Upsert

Endpoint: /transactions/{clientId}/upload

  {
    "identifiers": {
      "userId": "U123456",
      "email": "[email protected]"
    },
    "transaction": {
      "transactionId": "T123456",
      "transactionDate": "2024-07-02T12:44:19.658Z",
      "transactionCurrency": "USD",
      "transactionAmount": 120.50,
      "totalProductQuantity": 2,
      "uniqueProductQuantity": 1
    },
    "lineItems": [
      {
        "productId": "P123456",
        "SKU": "SKU123456",
        "productName": "Perfume 100ml",
        "productOriginalPrice": 150.00,
        "productSalePrice": 120.50,
        "productSize": "100ml",
        "quantity": 2
      }
    ]
  }
      

2. Bulk Transaction Upsert

Endpoint: /transactions/{clientId}/upload-bulk

  [
    {
      "identifiers": {
        "userId": "U123456",
        "email": "[email protected]"
      },
      "transaction": {
        "transactionId": "T123457",
        "transactionDate": "2024-07-02T12:45:50.085Z",
        "transactionCurrency": "USD",
        "transactionAmount": 200.00,
        "totalProductQuantity": 3,
        "uniqueProductQuantity": 2
      },
      "lineItems": [
        {
          "productId": "P123457",
          "SKU": "SKU123457",
          "productName": "Lotion 200ml",
          "productOriginalPrice": 100.00,
          "productSalePrice": 90.00,
          "productSize": "200ml",
          "quantity": 1
        },
        {
          "productId": "P123458",
          "SKU": "SKU123458",
          "productName": "Soap 100g",
          "productOriginalPrice": 50.00,
          "productSalePrice": 45.00,
          "productSize": "100g",
          "quantity": 2
        }
      ]
    }
  ]
      

3. Delete Transaction

Endpoint: /transactions/{clientId}?transactionId={transactionId}

  {
    "identifiers": {
      "userId": "U123456",
      "email": "[email protected]"
    }
  }
      

Retry Mechanism #

For all API operations, implement a retry mechanism to handle transient failures, such as network interruptions or server errors (e.g., HTTP 500). Use an exponential backoff strategy with a maximum of 5 retries.

Example Retry Logic:

• Retry after 1 second for the first failure.
• Double the retry delay (2, 4, 8 seconds) for subsequent failures.
• Stop retries after 5 attempts or upon a successful request.

Ensure Complete Transaction Data #

Whenever a transaction is added or updated, ensure all relevant fields (both mandatory and optional) are passed in the payload. Missing fields may result in incomplete or incorrect data processing.
For example, always include:

• userId and transactionId
• Line items with productId, SKU, productSalePrice, productOriginalPrice, and quantity.

This ensures seamless integration and avoids errors in downstream processes.

Error Handling #

Best Practices #

• Batch Updates: Use the /upload-bulk endpoint for multiple transactions to optimize performance.
• Validation: Validate input fields (e.g., date format, currency format) before sending requests.
• Retry Mechanism: Implement an exponential backoff strategy for retries.
• Ensure Data Completeness: Always pass all relevant fields in the payload for accuracy.

Contact and Support #

For any questions or support, please contact the Replenit team at
[email protected].