---
updatedAt: 2026-01-28T13:50:12.000Z
---

Fetch the complete documentation index at: https://developer.connecteam.com/llms.txt. Use this file to discover all available pages before exploring further.

# Managing Transactions

Transactions represent individual sales events at your locations. Use these endpoints to sync sales data from POS systems and manage transaction records.

## Endpoints

| Method | Endpoint                               | Description                |
| :----- | :------------------------------------- | :------------------------- |
| POST   | /sales/v1/transactions                 | Create transactions (bulk) |
| DELETE | /sales/v1/transactions                 | Delete by time period      |
| DELETE | /sales/v1/transactions/{transactionId} | Delete single transaction  |

***

## Create Transactions

Create one or more sales transactions. Transactions are linked to locations by their ID.

> ⚠️ Location Required
>
> You must create a location first using the [Locations API](sales-data-locations) before creating transactions. The `locationId` must reference an existing location.

### Request Body

| Field                     | Type  | Required | Description                                |
| :------------------------ | :---- | :------- | :----------------------------------------- |
| transactionsCreateRequest | array | Yes      | Array of transaction objects (1-100 items) |

### Transaction Object

| Field           | Type    | Required | Description                                        |
| :-------------- | :------ | :------- | :------------------------------------------------- |
| locationId      | integer | Yes      | The location ID from the Locations API             |
| saleType        | string  | Yes      | Type of sale (see Sale Types below)                |
| createdAt       | integer | Yes      | Transaction timestamp (Unix epoch in seconds, UTC) |
| finalSaleAmount | number  | Yes      | Sale amount after discounts, before tax            |
| taxAmount       | number  | No       | Tax amount in absolute value (not percentage)      |
| currency        | string  | No       | Currency code (e.g., "USD", "EUR")                 |

### Sale Types

| Type         | Description                     |
| :----------- | :------------------------------ |
| `SALE`       | Standard sale transaction       |
| `VOID`       | Voided transaction              |
| `REFUND`     | Refund transaction              |
| `SPLIT`      | Split payment transaction       |
| `TRANSFER`   | Transfer between locations      |
| `RECALL`     | Recalled transaction            |
| `UPDATE`     | Updated transaction             |
| `FLOAT`      | Float/cash management           |
| `TRANSITORY` | Temporary transaction           |
| `CROSS_BL`   | Cross-business line transaction |
| `CANCEL`     | Cancelled transaction           |
| `MANUAL`     | Manually entered transaction    |

### Example: Single Transaction

```bash
curl --request POST \
  --url https://api.connecteam.com/sales/v1/transactions \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "transactionsCreateRequest": [
      {
        "locationId": 123,
        "saleType": "SALE",
        "createdAt": 1706454000,
        "finalSaleAmount": 99.99,
        "taxAmount": 8.50,
        "currency": "USD"
      }
    ]
  }'
```

### Example: Bulk Transactions

```bash
curl --request POST \
  --url https://api.connecteam.com/sales/v1/transactions \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "transactionsCreateRequest": [
      {
        "locationId": 123,
        "saleType": "SALE",
        "createdAt": 1706454000,
        "finalSaleAmount": 99.99,
        "taxAmount": 8.50,
        "currency": "USD"
      },
      {
        "locationId": 123,
        "saleType": "REFUND",
        "createdAt": 1706457600,
        "finalSaleAmount": -25.00,
        "currency": "USD"
      },
      {
        "locationId": 456,
        "saleType": "SALE",
        "createdAt": 1706461200,
        "finalSaleAmount": 150.00,
        "taxAmount": 12.75,
        "currency": "USD"
      }
    ]
  }'
```

> 📝 Batch Limit
>
> You can create up to **100 transactions** per request. For larger syncs, batch your requests.

### Response

```json
{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "transactions": [
      {
        "transactionId": "f8e7d6c5-b4a3-2109-8765-43210fedcba9",
        "locationId": 123,
        "saleType": "SALE",
        "createdAt": 1706454000,
        "finalSaleAmount": 99.99,
        "taxAmount": 8.50,
        "currency": "USD"
      }
    ]
  }
}
```

### Response Fields

| Field           | Type    | Description                          |
| :-------------- | :------ | :----------------------------------- |
| transactionId   | string  | Unique transaction identifier (UUID) |
| locationId      | integer | Associated location ID               |
| saleType        | string  | Type of sale                         |
| createdAt       | integer | Transaction timestamp                |
| finalSaleAmount | number  | Sale amount                          |
| taxAmount       | number  | Tax amount (if provided)             |
| currency        | string  | Currency code (if provided)          |

***

## Delete Transactions by Time Period

Delete all transactions for a location within a specified time range.

> ⚠️ Permanent Deletion
>
> This operation permanently removes all matching transactions. This action cannot be undone.

### Query Parameters

| Parameter  | Type    | Required | Description                      |
| :--------- | :------ | :------- | :------------------------------- |
| locationId | integer | Yes      | Location ID                      |
| startTime  | integer | Yes      | Start of period (Unix timestamp) |
| endTime    | integer | Yes      | End of period (Unix timestamp)   |

### Example

```bash
curl --request DELETE \
  --url 'https://api.connecteam.com/sales/v1/transactions?locationId=123&startTime=1706400000&endTime=1706486400' \
  --header 'X-API-KEY: YOUR_API_KEY'
```

### Response

```json
{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {}
}
```

***

## Delete Single Transaction

Delete a specific transaction by its ID.

### Path Parameters

| Parameter     | Type   | Required | Description                 |
| :------------ | :----- | :------- | :-------------------------- |
| transactionId | string | Yes      | The transaction's unique ID |

### Example

```bash
curl --request DELETE \
  --url https://api.connecteam.com/sales/v1/transactions/f8e7d6c5-b4a3-2109-8765-43210fedcba9 \
  --header 'X-API-KEY: YOUR_API_KEY'
```

### Response

```json
{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {}
}
```

***

## Error Responses

### 404 Not Found

**Location not found:**

```json
{
  "detail": "Locations with IDs [999] not found"
}
```

**Transaction not found:**

```json
{
  "detail": "Transaction with ID 'invalid-id' not found"
}
```

### 422 Validation Error

**Invalid time range:**

```json
{
  "detail": [
    {
      "loc": ["query", "endTime"],
      "msg": "end_time must be greater than start_time",
      "type": "value_error"
    }
  ]
}
```

**Missing required fields:**

```json
{
  "detail": [
    {
      "loc": ["body", "transactionsCreateRequest", 0, "locationId"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

***

## Best Practices

### Syncing Daily Sales

For regular POS sync, batch transactions by day:

```javascript
async function syncDailySales(locationId, transactions) {
  const BATCH_SIZE = 100;
  
  for (let i = 0; i < transactions.length; i += BATCH_SIZE) {
    const batch = transactions.slice(i, i + BATCH_SIZE);
    
    await fetch('https://api.connecteam.com/sales/v1/transactions', {
      method: 'POST',
      headers: {
        'X-API-KEY': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        transactionsCreateRequest: batch.map(t => ({
          locationId: locationId,
          saleType: t.type,
          createdAt: Math.floor(t.date.getTime() / 1000),
          finalSaleAmount: t.amount,
          taxAmount: t.tax,
          currency: 'USD'
        }))
      })
    });
  }
}
```

### Handling Refunds

For refunds, use:

* `saleType: "REFUND"`
* Negative `finalSaleAmount` value
* Same `locationId` as the original sale

***

[API Reference](https://developer.connecteam.com/reference/)