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

# Sales inbound api

# Tango Sales Inbound API

> Generated from `Tango Sales Inbound API Integration Design Specification V1.1.docx` in SharePoint folder `02 Lease Integrations`.
> OAS spec: [`sales-inbound-api.yaml`](./sales-inbound-api.yaml)

## Overview

Async REST API: client posts monthly sales data to Tango for percentage-rent calculations. Sales data lands under the Percentage Rent tab of Lease Financials. The lease must be Active with a Percent Rent agreement also Active before data lands.

**Owner:** Tango Analytics
**Spec version:** 1.1
**Status:** Draft (auto-generated — needs review)

## Base URLs

| Environment | URL |
| - | - |
| Production | `https://api.tangoanalytics.com` |
| Test (SIT/UAT) | `https://testapi.tangoanalytics.com` |

## Authentication

Headers `x-client` + `x-api-key`.

## Endpoints

| Method | Path | Summary |
| - | - | - |
| PUT | `/v1/leasemgmt/sales` | Submit sales records (async). |
| GET | `/v1batch/status?gu_id=...` ⚠ | Poll processing status. (See Open Questions.) |

### `PUT /v1/leasemgmt/sales`

```json theme={null}
{
  "records": [
    {
      "lease_number": "",
      "store_number": "0-0",
      "calendar_month": 1,
      "calendar_year": 2020,
      "effective_from": "1/1/2020",
      "effective_to": "1/15/2020",
      "sales_code": "Jan",
      "sales_category": "SALES-GROSS",
      "sale_exclusion": "SALES",
      "sales": 110,
      "actual_forecast": "ACTUAL",
      "currency_code": "USD",
      "country": "USA"
    }
  ]
}
```

## Integration logic

* Either `lease_number` or `store_number` must be present; both are needed if multiple leases attach to one store.
* Percent rent calculations operate on Calendar Period / Calendar Year (not fiscal).
* Sales code is optional — the unique identifier is `(sales_exclusion, sales_category)`.
* Data update: data received for the same month overwrites the previous run.
* Sales Forecast is replaced when Actual is later sent for the same month/year/category combination.
* Annual / Monthly CAP% logic: see source doc — applied when 12th period (annual) or each period (monthly) is `ACTUAL` and CAP% is set on the exclusion category.

## Data model

| Field | Type | Required | Notes |
| - | - | - | - |
| `lease_number` | String | one-of | Required if `store_number` missing |
| `store_number` | String | ✅ | Store / location number |
| `calendar_month` | Number | – | Calendar period MM |
| `calendar_year` | Number | – | YYYY |
| `effective_from` | Date `MM/DD/YYYY` | – | Auto-filled |
| `effective_to` | Date `MM/DD/YYYY` | – | Auto-filled |
| `sales_code` | String | – | Lookup `PERCENT_RENT_SALES_CODE` |
| `sales_category` | String | ✅ | Lookup `PERCENT_RENT_SALES_CATEGORY` |
| `sale_exclusion` | String | ✅ | Lookup `PERCENT_RENT_SALES_EXCLUSION` |
| `sales` | Number | – | Sales amount |
| `actual_forecast` | String | ✅ | `ACTUAL` or `FORECAST` |
| `currency_code` | String | – | |
| `country` | String | ✅ | |

## Validations

1. Both `store_number` and `lease_number` missing → `Store Number/Lease Number cannot be blank`
2. Invalid `lease_number` → `Lease Number is not valid`
3. Invalid `store_number` → `Store Number is not valid`
4. Lease status not active → `Lease status is not active for lease number <>`
5. Percent Rent status not active → `Percent rent status should be ACTIVE`
6. `sale_exclusion` not in lookup → `sales_exclusion should have valid lookups`
7. `sales_category` not in lookup → `sales_category should have valid lookups`
8. `actual_forecast` not (`ACTUAL`, `FORECAST`) → `actual_forecast does not match expected value`
9. `sales_category` missing → `sales_category is missing or empty`
10. `sales_category` not configured in UI → `sales setup missing for sales category: <>`
11. `country` missing → `country cannot be blank`
12. `effective_from`/`effective_to` outside sales-setup dates → `Sales setup missing for sales category: <> for store Number: <>`

## Open Questions / Assumptions

* [ ] **Status URL typo**: source doc lists `/v1batch/status` (no slash between `v1` and `batch`). Other Tango APIs use `/v1/batch/status`. The YAML preserves the doc verbatim — confirm and correct on next revision.
* [ ] **Pre-requisites**: full sales/exclusion category list and percent-rent scenarios must be provided by the client before integration starts; changes later are change orders.
* [ ] **`sales_code` is optional** but is recommended as the lookup `PERCENT_RENT_SALES_CODE` value.
* [ ] **Monthly vs Annual CAP%** — Cap Frequency on the Sales Setup defaults to ANNUAL if left blank. CAP% logic differs.
* [ ] **`record_key` shape in error responses** is a semicolon-joined tuple `store;cm;cy;category`.

## Changelog

| Ver | Date | Description | Author |
| - | - | - | - |
| 0.1–1.0 | 2022-2025 | (see source doc) | Various |
| 1.1 | 04/22/2026 | Updated API Architecture | Jasmin Thasleem |