sell_out

Confirm the four things Tightly must know about an account's reports, once per account

Records a person's answers for one account: location_grain (store, dc or none), currency, price_tax_basis and absence_convention, all four required in one call, with account_id in the query. Re-confirming REPLACES them, which is how a retailer that has changed its reporting week is corrected.

All four or none. A declaration missing one of them would have to be completed by a default, and the reason these four exist is that every default is wrong for about half of all accounts.

Values are checked here and again by the database, and the database constraints are the ones that hold; this validation exists so a person gets a sentence rather than a constraint violation.

Call it once per account before import_sell_out, and read it back with get_sell_out_declaration.

Sold with Essentials+: without Tightly Connect the answer is 403 plan_excludes.

Scope: sell_out:write, which includes sell_out:read.

post/api/v1/sell-out/declaration

Request

  • Base URL: https://api.app.tightly.io
  • URL: https://api.app.tightly.io/api/v1/sell-out/declaration
  • Auth: HTTP bearer

Query parameters

account_idstring required

The account these answers are for. An id, never a name.

Headers

Tightly-Versionstring
Example:2026-11

The date train to answer on. One train exists today, 2026-11, the one this reference describes and the one every key is minted on, so the call answers on it with or without this header. Send it anyway, so a client built now names its train from the start.

Idempotency-Keystring
Example:b8f1c0d2-6a4e-4f39-9c21-0d5f2e7a1b44

A string of your own, up to 255 characters, that makes this write safe to retry. Send the same key twice and the second request is answered with the first one's status and body instead of writing again, so a client that retried after a timeout ends holding the record's id rather than creating a second one. Reusing a key with a different body, or while the first request is still running, is refused 409. A write that failed releases its key. Keys answer for 24 hours and belong to the API key that used them. A key longer than 255 characters is ignored and the write goes ahead without the guarantee.

Request body

absence_convention'explicit_zero' | 'row_omitted' required

Whether a product missing from the file sold none (explicit_zero, they write a zero, so an absent row is genuinely absent data) or was simply not reported (row_omitted). This is the answer that cannot be defaulted.

currencystring required

Three-letter code, e.g. GBP or EUR.

location_grain'store' | 'dc' | 'none' required

What a row covers, one store, one distribution centre, or the whole account.

price_tax_basis'inclusive' | 'exclusive' | 'unknown' required

Whether the prices in the file include tax.

source_profile_keystring

The format profile these answers were read from, when a file proposed them.

week_anchor_dowinteger

The day their week ends on, 0 for Monday through 6 for Sunday. Absent when the export carries no date at all and there is no anchor to declare, inventing one would be the same defect the field exists to prevent.

Response

The stored declaration, in the same shape GET /sell-out/declaration serves, including confirmed_by and the confirmed_by_name resolved for it. This account's reports can now be imported.

object required

Changes

No recorded changes to this operation across all 1 revision of this API.