Guides
Start typing to search…

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

MethodEndpointDescription
POST/sales/v1/transactionsCreate transactions (bulk)
DELETE/sales/v1/transactionsDelete 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 before creating transactions. The locationId must reference an existing location.

Request Body

FieldTypeRequiredDescription
transactionsCreateRequestarrayYesArray of transaction objects (1-100 items)

Transaction Object

FieldTypeRequiredDescription
locationIdintegerYesThe location ID from the Locations API
saleTypestringYesType of sale (see Sale Types below)
createdAtintegerYesTransaction timestamp (Unix epoch in seconds, UTC)
finalSaleAmountnumberYesSale amount after discounts, before tax
taxAmountnumberNoTax amount in absolute value (not percentage)
currencystringNoCurrency code (e.g., "USD", "EUR")

Sale Types

TypeDescription
SALEStandard sale transaction
VOIDVoided transaction
REFUNDRefund transaction
SPLITSplit payment transaction
TRANSFERTransfer between locations
RECALLRecalled transaction
UPDATEUpdated transaction
FLOATFloat/cash management
TRANSITORYTemporary transaction
CROSS_BLCross-business line transaction
CANCELCancelled transaction
MANUALManually entered transaction

Example: Single Transaction

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

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

{
  "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

FieldTypeDescription
transactionIdstringUnique transaction identifier (UUID)
locationIdintegerAssociated location ID
saleTypestringType of sale
createdAtintegerTransaction timestamp
finalSaleAmountnumberSale amount
taxAmountnumberTax amount (if provided)
currencystringCurrency 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

ParameterTypeRequiredDescription
locationIdintegerYesLocation ID
startTimeintegerYesStart of period (Unix timestamp)
endTimeintegerYesEnd of period (Unix timestamp)

Example

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

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

Delete Single Transaction

Delete a specific transaction by its ID.

Path Parameters

ParameterTypeRequiredDescription
transactionIdstringYesThe transaction's unique ID

Example

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

Response

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

Error Responses

404 Not Found

Location not found:

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

Transaction not found:

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

422 Validation Error

Invalid time range:

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

Missing required fields:

{
  "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:

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

Updated 11 days ago