> ## Documentation Index
> Fetch the complete documentation index at: https://docs.partnero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create transaction

> Record sales transactions for commission calculation in your affiliate program

## Endpoint

```
POST https://api.partnero.com/v1/transactions
```

Partnero automatically calculates the commission based on your program settings.

## Request body

**Transaction fields**

| Parameter      | Type    | Required | Description                                                                  |
| -------------- | ------- | -------- | ---------------------------------------------------------------------------- |
| `key`          | string  | No       | Unique transaction ID (recommended for refund handling)                      |
| `amount`       | number  | Yes\*    | Transaction amount. Partnero calculates commission based on program settings |
| `reward`       | number  | Yes\*    | Set the commission amount directly instead of calculating from `amount`      |
| `amount_units` | string  | No       | Currency code (e.g., `USD`, `EUR`, `GBP`)                                    |
| `action`       | string  | No       | Transaction type (e.g., `sale`)                                              |
| `product_id`   | string  | No       | Product ID for advanced commission rules                                     |
| `product_type` | string  | No       | Product type/category for advanced commission rules                          |
| `rewarded`     | boolean | No       | Whether the transaction is already rewarded (default: `false`)               |
| `rewardable`   | boolean | No       | Whether the transaction is eligible for rewards (default: `true`)            |
| `created_at`   | integer | No       | Unix timestamp to backdate the transaction                                   |

\*Provide either `amount` or `reward`.

**Customer identification**

| Parameter        | Type   | Required | Description                           |
| ---------------- | ------ | -------- | ------------------------------------- |
| `customer.key`   | string | Yes\*    | Customer's unique key                 |
| `customer.email` | string | Yes\*    | Customer's email (alternative to key) |

\*Provide at least one: `key` or `email`.

**Create customer with transaction** (`options.create_customer: true`)

When the customer doesn't exist yet, you can create them and the transaction in a single request.

| Parameter                 | Type    | Description                                    |
| ------------------------- | ------- | ---------------------------------------------- |
| `options.create_customer` | boolean | Create customer and transaction simultaneously |
| `customer.name`           | string  | Customer's first name                          |
| `customer.surname`        | string  | Customer's last name                           |
| `customer.tags`           | array   | Tags to assign to the customer                 |
| `customer.created_at`     | string  | Customer creation date                         |
| `customer.partner.key`    | string  | Partner key for attribution                    |
| `customer.partner.id`     | string  | Partner ID for attribution                     |
| `customer.partner.email`  | string  | Partner email for attribution                  |
| `options.referral_url`    | string  | Referral URL for custom link attribution       |

**Multiple products**

For transactions with multiple products. Each product entry can include commission data (`product_id`, `product_price`), product metadata (`product_information`), or both.

| Parameter                                    | Type         | Description                              |
| -------------------------------------------- | ------------ | ---------------------------------------- |
| `products`                                   | array        | Array of product objects                 |
| `products[].product_id`                      | string       | Product ID for commission rules          |
| `products[].product_price`                   | number       | Product price for commission calculation |
| `products[].product_information`             | object       | Product metadata (optional)              |
| `products[].product_information.sku`         | string       | Product SKU                              |
| `products[].product_information.name`        | string       | Product name                             |
| `products[].product_information.description` | string\|null | Product description                      |

**Bulk transactions**

| Parameter                     | Type    | Description                                    |
| ----------------------------- | ------- | ---------------------------------------------- |
| `transactions`                | array   | Array of transaction objects for bulk creation |
| `transactions[].amount`       | number  | Transaction amount (required)                  |
| `transactions[].key`          | string  | Unique transaction ID                          |
| `transactions[].action`       | string  | Transaction type                               |
| `transactions[].amount_units` | string  | Currency code                                  |
| `transactions[].product_id`   | string  | Product ID                                     |
| `transactions[].product_type` | string  | Product type                                   |
| `transactions[].rewarded`     | boolean | Already rewarded                               |
| `transactions[].rewardable`   | boolean | Eligible for rewards                           |

## Request

<Tabs>
  <Tab title="Single transaction">
    ```bash theme={null}
    curl --location 'https://api.partnero.com/v1/transactions' \
      --header 'Authorization: Bearer YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "customer": {
          "key": "customer_123"
        },
        "key": "transaction_123",
        "amount": 99.99,
        "amount_units": "USD",
        "product_id": "prod_123",
        "product_type": "monthly",
        "action": "sale"
      }'
    ```
  </Tab>

  <Tab title="Direct reward">
    ```bash theme={null}
    curl --location 'https://api.partnero.com/v1/transactions' \
      --header 'Authorization: Bearer YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "customer": {
          "key": "customer_123"
        },
        "key": "transaction_789",
        "reward": 25.00,
        "amount_units": "USD",
        "action": "sale"
      }'
    ```
  </Tab>

  <Tab title="With customer creation">
    ```bash theme={null}
    curl --location 'https://api.partnero.com/v1/transactions' \
      --header 'Authorization: Bearer YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "key": "transaction_456",
        "amount": 50.99,
        "action": "sale",
        "options": {
          "create_customer": true
        },
        "customer": {
          "key": "customer_456",
          "name": "Robert",
          "surname": "Johnson",
          "email": "robert@example.com",
          "partner": {
            "key": "partner_123"
          }
        }
      }'
    ```
  </Tab>

  <Tab title="Multiple transactions">
    ```bash theme={null}
    curl --location 'https://api.partnero.com/v1/transactions' \
      --header 'Authorization: Bearer YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "customer": {
          "key": "customer_123"
        },
        "transactions": [
          {
            "key": "transaction_123_m",
            "amount": 50.99,
            "action": "sale"
          },
          {
            "key": "transaction_456_m",
            "amount": 100.99,
            "action": "sale"
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="Multiple products">
    ```bash theme={null}
    curl --location 'https://api.partnero.com/v1/transactions' \
      --header 'Authorization: Bearer YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "customer": {
          "key": "customer_123"
        },
        "key": "order_789",
        "action": "sale",
        "products": [
          {
            "product_id": "prod_a",
            "product_price": 29.99
          },
          {
            "product_id": "prod_b",
            "product_price": 49.99
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="With product information">
    ```bash theme={null}
    curl --location 'https://api.partnero.com/v1/transactions' \
      --header 'Authorization: Bearer YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "customer": {
            "key": "customer_123"
        },
        "action": "sale",
        "amount": 1000,
        "products": [
            {
                "product_id": "product_1",
                "product_price": 100,
                "product_information": {
                    "sku": "SKU123",
                    "name": "Product 1 name",
                    "description": "Product 1 short description"
                }
            },
            {
                "product_id": "product_2",
                "product_price": 200
            },
            {
                "product_information": {
                    "sku": "SKU456",
                    "name": "Product 2 name",
                    "description": null
                }
            }
        ]
    }'
    ```
  </Tab>
</Tabs>

## Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": {
      "key": "transaction_123",
      "action": "sale",
      "amount": 99.99,
      "partner": "partner_123",
      "customer": "customer_123",
      "credit": false,
      "is_currency": true,
      "amount_units": "USD",
      "created_at": "2025-05-07T05:32:48.000000Z",
      "deleted_at": null,
      "rewards": [
        {
          "key": "transaction_123",
          "action": "sale",
          "status": "ok",
          "customer": "customer_123",
          "partner": "partner_123",
          "amount": 29.997,
          "amount_units": "USD",
          "is_currency": true,
          "credit": false,
          "created_at": "2025-05-07T05:32:48.000000Z",
          "deleted_at": null,
          "product_type_data": {
            "product_id": "prod_123",
            "product_type": "monthly"
          }
        }
      ]
    },
    "status": 1
  }
  ```
</ResponseExample>

### Response fields

<Accordion title="Transaction — data">
  | Field          | Type         | Description                             |
  | -------------- | ------------ | --------------------------------------- |
  | `key`          | string       | Transaction identifier                  |
  | `action`       | string       | Transaction type                        |
  | `amount`       | number       | Transaction amount                      |
  | `amount_units` | string       | Currency code                           |
  | `partner`      | string       | Attributed partner key                  |
  | `customer`     | string       | Customer key                            |
  | `credit`       | boolean      | Whether this is a credit transaction    |
  | `is_currency`  | boolean      | Whether the amount is monetary          |
  | `created_at`   | string       | ISO 8601 timestamp                      |
  | `deleted_at`   | string\|null | Deletion timestamp if archived/refunded |
</Accordion>

<Accordion title="Rewards — data.rewards[]">
  | Field               | Type         | Description                                       |
  | ------------------- | ------------ | ------------------------------------------------- |
  | `key`               | string       | Reward identifier (matches transaction key)       |
  | `action`            | string       | Reward origin                                     |
  | `status`            | string       | Reward status (`ok`, `review_period`, `rejected`) |
  | `customer`          | string       | Customer key                                      |
  | `partner`           | string       | Partner key                                       |
  | `amount`            | number       | Commission amount                                 |
  | `amount_units`      | string       | Currency code                                     |
  | `is_currency`       | boolean      | Whether the amount is monetary                    |
  | `credit`            | boolean      | Whether this is a credit reward                   |
  | `created_at`        | string       | ISO 8601 timestamp                                |
  | `deleted_at`        | string\|null | Deletion timestamp                                |
  | `product_type_data` | object       | Product ID and type (if provided)                 |
</Accordion>

## Error responses

| Status | Error              | Solution                                                              |
| ------ | ------------------ | --------------------------------------------------------------------- |
| 400    | Customer not found | Create customer first or use `options.create_customer`                |
| 400    | Duplicate key      | Transaction with this key already exists                              |
| 422    | Validation error   | Check required fields (`amount`/`reward` and customer identification) |

<Tip>
  Use unique transaction keys (like invoice IDs) to enable refund handling. When you delete a transaction by key, the associated commission is automatically reversed.
</Tip>