> ## Documentation Index > Fetch the complete documentation index at: https://docs.closient.com/llms.txt > Use this file to discover all available pages before exploring further. # Upsert one physical store > Reconcile and apply a single store row for one retailer. Identical to the batch endpoint with one row — the response is the same envelope, with a single entry in `rows` — so a one-store correction needs no list wrapping. Rows are **reconciled, not inserted**. Each row is tied to an existing store by exact store number, then by proximity within `proximity_m`, then by normalised street plus postal code — one-to-one, highest-confidence tier first. A match enriches the existing store in place; only a row that matches nothing creates one. This is why the endpoint is safe to point at a full dataset that overlaps rows already in the database: an insert-only surface would plant a duplicate beside every store whose recorded key predates the retailer's own numbering. Nothing is ever merged, deactivated or deleted here. An existing store no row claims is counted in `unmatched_existing` and left exactly as it is; a pair the matcher finds contradictory is reported in the row's `conflict` and left unrekeyed. `dry_run` defaults to **true**. Send `dry_run: false` to commit. `retailer_id` is a `retailers.Retailer`. An organization-private retailer requires OWNER or MANAGER on the organization that owns it; a canonical (Closient-curated) retailer requires a staff account, because those rows were previously writable only from a management command. The organization this credential acts for becomes the owning organization of any location record created. ## OpenAPI ````yaml /openapi/openapi-retailers.json post /retailers/api/v1/retailers/{retailer_id}/stores openapi: 3.1.0 info: title: Retailers API version: 1.0.0 description: > Manage retailers, in-store offers, and online offers. ## Authentication All endpoints require an API key passed via the `X-API-Key` HTTP header, unless otherwise noted. ``` X-API-Key: csb__ ``` Generate API keys in **Settings > API Keys** in your dashboard, or via the Account API. Session-based (cookie) authentication is also accepted for browser-based access. ## Rate Limits | Tier | Requests / minute | Requests / day | |-------------|-------------------|----------------| | Default | 300 | 10,000 | | Custom | Contact us | Contact us | Rate-limit headers are included on every response so callers can self-throttle without hitting our 429s ("informed governor"): - `RateLimit-Policy` — every active window, e.g. `300;w=60, 10000;w=86400` - `RateLimit-Limit` — quota for the **most-restrictive** currently-active window - `RateLimit-Remaining` — requests left in that window - `RateLimit-Reset` — seconds until that window resets (relative; clock-skew safe) Legacy `X-RateLimit-*` aliases are also emitted for back-compat. `X-RateLimit-Reset` keeps the absolute Unix-timestamp shape to avoid breaking existing consumers. When rate-limited, you receive `429 Too Many Requests` with a `retry_after_seconds` field in the error envelope and a `Retry-After` header. ## Pagination List endpoints return paginated results in this envelope: ```json { "data": [...], "pagination": { "page": 1, "page_size": 25, "total_count": 342, "total_pages": 14, "has_next": true, "has_previous": false } } ``` Use `?page=2&page_size=50` query parameters. Maximum page size is 100. ## Error Responses All errors conform to [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457) with `Content-Type: application/problem+json`: ```json { "type": "https://closient.com/docs/errors/not_found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found.", "error_code": "not_found", "retryable": false, "timestamp": "2026-03-31T12:00:00+00:00" } ``` Common error codes: `unauthorized` (401), `forbidden` (403), `not_found` (404), `validation_error` (422), `rate_limited` (429), `internal_error` (500). termsOfService: https://www.closient.com/terms/ servers: - url: https://www.closient.com security: [] tags: - name: Retailers description: Manage retailers (canonical and org-private). - name: In-store Offers description: Per-store physical offers (aisle, on-hand quantity, pickup). - name: Online Offers description: Per-storefront online offers (URL, delivery, fulfillment). - name: In-store Offer Promotions description: Time-windowed promotional pricing on in-store offers. - name: Online Offer Promotions description: Time-windowed promotional pricing on online offers. - name: Retailer Stores description: >- Physical storefront upsert, reconciled against existing stores by store number, then proximity, then normalised address — a match enriches in place rather than creating a near-duplicate. - name: Retailer Listings description: >- Retailer-scoped product listings (SKU, badges, per-property URLs, extensible attributes) and the web properties those URLs attach to. externalDocs: description: Closient Documentation url: https://docs.closient.com paths: /retailers/api/v1/retailers/{retailer_id}/stores: post: tags: - Retailer Stores summary: Upsert one physical store description: >- Reconcile and apply a single store row for one retailer. Identical to the batch endpoint with one row — the response is the same envelope, with a single entry in `rows` — so a one-store correction needs no list wrapping. Rows are **reconciled, not inserted**. Each row is tied to an existing store by exact store number, then by proximity within `proximity_m`, then by normalised street plus postal code — one-to-one, highest-confidence tier first. A match enriches the existing store in place; only a row that matches nothing creates one. This is why the endpoint is safe to point at a full dataset that overlaps rows already in the database: an insert-only surface would plant a duplicate beside every store whose recorded key predates the retailer's own numbering. Nothing is ever merged, deactivated or deleted here. An existing store no row claims is counted in `unmatched_existing` and left exactly as it is; a pair the matcher finds contradictory is reported in the row's `conflict` and left unrekeyed. `dry_run` defaults to **true**. Send `dry_run: false` to commit. `retailer_id` is a `retailers.Retailer`. An organization-private retailer requires OWNER or MANAGER on the organization that owns it; a canonical (Closient-curated) retailer requires a staff account, because those rows were previously writable only from a management command. The organization this credential acts for becomes the owning organization of any location record created. operationId: apps_retailers_api_stores_upsert_store parameters: - in: path name: retailer_id schema: description: Unique identifier of the retailer this store belongs to. format: shortuuid maxLength: 22 minLength: 22 pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$ title: Retailer Id type: string required: true description: Unique identifier of the retailer this store belongs to. requestBody: content: application/json: schema: $ref: '#/components/schemas/StoreUpsertIn' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/StoreUpsertResultOut' '400': description: Bad Request content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' '403': description: Forbidden content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' '404': description: Not Found content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' '405': description: Method Not Allowed content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' '422': description: Unprocessable Content content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' '429': description: Too Many Requests content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' security: - APIKeyHeaderAuth: [] - OAuthTokenAuth: [] - CookieGatedSessionAuth: [] components: schemas: StoreUpsertIn: description: A single store plus the same reconciliation knobs the batch form takes. examples: - address_line_1: 1250 Main St allow_create: true city: Springfield country: US country_derived: true extras: branch_code: '595' opening_hours_spec: - closes: '20:00' dayOfWeek: Monday opens: '10:00' services: - Salon - Brow Bar first_party: true lat: 39.7817 lon: -89.6501 name: Ulta Beauty opening_hours: Mo-Sa 10:00-20:00; Su 11:00-18:00 phone: '+12175550100' postal_code: '62704' region: IL source: ulta_site source_url: https://www.ulta.com/stores/springfield-il-595 store_number: '595' website: https://www.ulta.com/stores/springfield-il-595 properties: store_number: description: >- The key this source uses for the store — the retailer's own store number where it publishes one, otherwise a stable synthesized key (e.g. `SYN-…`). This is the highest-confidence match tier, so a source that can supply a real store number should: it is what makes a repeated call idempotent rather than proximity-matched. maxLength: 50 title: Store Number type: string name: default: '' description: Store or branch display name. maxLength: 255 title: Name type: string address_line_1: default: '' description: Street address, number and street name. maxLength: 255 title: Address Line 1 type: string city: default: '' description: City, town or locality. maxLength: 255 title: City type: string region: default: '' description: State, province or region. maxLength: 255 title: Region type: string postal_code: default: '' description: ZIP, postal code or postcode. maxLength: 20 title: Postal Code type: string country: default: US description: >- ISO 3166-1 alpha-2 country code for the store. An **assigned** code: this value is written to the place's country column, and a store filed under a code that names no country is the same class of defect C-5969 found 75 instances of. A bare two-letter string would have admitted 427 unassigned combinations (C-5975). format: iso3166-alpha2 maxLength: 2 minLength: 2 pattern: ^[A-Za-z]{2}$ title: Country type: string lat: anyOf: - maximum: 90 minimum: -90 type: number - type: 'null' description: >- WGS84 latitude in decimal degrees. Null is accepted — a store with a good address and no coordinates still matches on the address tier and is still worth having. title: Lat lon: anyOf: - maximum: 180 minimum: -180 type: number - type: 'null' description: WGS84 longitude in decimal degrees. Null is accepted; see `lat`. title: Lon phone: default: '' description: Store phone number; normalised to E.164 on write. maxLength: 50 title: Phone type: string website: default: '' description: The store's own page on the retailer's site. maxLength: 1000 title: Website type: string opening_hours: default: '' description: >- Opening hours in OSM `opening_hours` syntax (e.g. `Mo-Sa 10:00-20:00; Su 11:00-18:00`). There is no hours column on a location, so this is stored in `Place.source_extras` under this row's `source` — sending it here is equivalent to sending `extras.opening_hours`, and an explicit `extras.opening_hours` wins. A structured schema.org `openingHoursSpecification` can be sent alongside it in `extras`. maxLength: 1000 title: Opening Hours type: string source: description: >- Stable name of the dataset this row came from (e.g. `ulta_site`, `sephora_csv`, `osm`). Load-bearing, not a label: per-column authorship is recorded against it, and a source may later correct a value it wrote itself but never one another source wrote. Sending a different name on a rerun of the same dataset therefore forfeits that source's own right to update the columns it authored. maxLength: 100 minLength: 1 title: Source type: string source_url: default: '' description: Where this specific row was read from. maxLength: 1000 title: Source Url type: string first_party: default: false description: >- True when the row comes from the retailer's own site or feed. Only a first-party row may overwrite an existing non-placeholder value or rename a storefront; community mapping data enriches blanks instead. title: First Party type: boolean allow_create: default: true description: >- Whether a row that matches nothing may create a new store. Set false for a secondary source: it may enrich a store the retailer confirms exists, but a location only a community extract believes in is not evidence enough to seed a storefront customers would be sent to. title: Allow Create type: boolean country_derived: default: false description: >- True when `country` came from a coordinate lookup rather than from a feed label or address field. This is a **provenance assertion, and it grants the row power**: only a derived country may correct a country already stored on the place. A country that came from a label can fill a blank and nothing more. Set it only when you actually resolved the country from `lat`/`lon`. The reason it exists is concrete — Sephora's North America feed labels 482 of its 483 rows `US`, and trusting that label would have filed 75 Canadian stores as American (C-5969). A label is not evidence; a coordinate is. Asserting this on a label-derived country re-opens exactly that defect, so leave it false when in doubt: the cost is a country that stays wrong until a better row arrives, not one that gets overwritten with a worse value. title: Country Derived type: boolean extras: additionalProperties: true description: >- Everything this source carries that has no column of its own — raw hours specifications, service lists, OSM tags, source-conflict flags. Stored in `Place.source_extras` under this row's `source`. Nesting is allowed here, unlike the flat-string `metadata` field on other resources. title: Extras type: object dry_run: default: true description: >- When true (the default) the write is rolled back. Send false to commit. title: Dry Run type: boolean proximity_m: default: 100 description: Match radius in metres for the proximity tier. exclusiveMinimum: 0 maximum: 500 title: Proximity M type: number phone_region: default: US description: ISO 3166-1 alpha-2 region for phone normalisation. format: iso3166-alpha2 maxLength: 2 minLength: 2 pattern: ^[A-Za-z]{2}$ title: Phone Region type: string required: - store_number - source title: StoreUpsertIn type: object StoreUpsertResultOut: description: >- Batch census plus the per-row results. ``created + enriched + unchanged + not_created + errors`` equals the number of submitted rows for any 200 response. The endpoint returns 200 even when individual rows fail: a per-row failure is reported here rather than aborting the batch, so a single malformed row cannot cost the other 999. Request-level failures (auth, an unwritable retailer, a batch over the row cap) are 4xx instead. examples: - committed: false coverage_after: stores: 1622 with_phone: 3 with_point: 1622 created: 1 enriched: 2 errors: 0 existing_stores: 1621 fields_superseded: 4 legacy_keys_preserved: 2 matched_address: 0 matched_proximity: 2 matched_store_number: 0 near_misses: 1 not_created: 0 phones_written: 3 rekey_skipped_conflict: 0 row_errors: [] rows: - conflict: '' distance_m: 18.4 error: '' index: 0 match_method: proximity outcome: enriched store_number: '595' submitted_rows: 3 unchanged: 0 unmatched_existing: 1619 urls_written: 3 properties: committed: description: >- False when this was a dry run — every path ran and the transaction was rolled back. title: Committed type: boolean submitted_rows: description: Number of rows in the request. minimum: 0 title: Submitted Rows type: integer existing_stores: description: >- Stores this retailer already had, i.e. the size of the candidate match set. minimum: 0 title: Existing Stores type: integer created: description: Rows that produced a new store. minimum: 0 title: Created type: integer enriched: description: Rows that matched and changed something. minimum: 0 title: Enriched type: integer unchanged: description: Rows that matched and needed no change. minimum: 0 title: Unchanged type: integer not_created: description: Rows that matched nothing and were not allowed to create a store. minimum: 0 title: Not Created type: integer errors: description: Rows that raised. Equals the length of `row_errors`. minimum: 0 title: Errors type: integer matched_store_number: description: Rows matched on the exact store-number tier. minimum: 0 title: Matched Store Number type: integer matched_proximity: description: Rows matched on the proximity tier. minimum: 0 title: Matched Proximity type: integer matched_address: description: Rows matched on the normalised-address tier. minimum: 0 title: Matched Address type: integer near_misses: description: >- Pairs beyond `proximity_m` but within 500 m that were deliberately NOT matched. A judgement call for a human, never auto-matched by widening the radius. minimum: 0 title: Near Misses type: integer unmatched_existing: description: >- Existing stores no submitted row claimed. For a full-dataset run these are stores the retailer's own list no longer carries, i.e. probably closed — reported, never deactivated or deleted. minimum: 0 title: Unmatched Existing type: integer phones_written: description: Phone numbers written or refreshed. minimum: 0 title: Phones Written type: integer urls_written: description: Store URLs written or refreshed. minimum: 0 title: Urls Written type: integer fields_superseded: description: >- Existing non-placeholder values a first-party row overwrote. The previous value is preserved under `Place.source_extras['superseded']` rather than discarded. minimum: 0 title: Fields Superseded type: integer legacy_keys_preserved: description: >- Stores whose pre-existing store number was replaced by this source's real one, with the old key kept in `Place.source_extras['legacy_store_key']`. minimum: 0 title: Legacy Keys Preserved type: integer rekey_skipped_conflict: description: >- Stores left on their existing key because the evidence for re-keying was contradictory. minimum: 0 title: Rekey Skipped Conflict type: integer coverage_after: additionalProperties: type: integer description: >- Per-column coverage for this retailer's stores after the call — `stores`, `with_point`, `with_real_address`, `with_phone`, `with_url`, `with_source_extras`. On a dry run these are the post-rollback figures the run *would* have produced, measured inside the transaction. title: Coverage After type: object rows: description: One result per submitted row, in request order. items: $ref: '#/components/schemas/StoreRowResultOut' title: Rows type: array row_errors: description: >- Batch-level restatement of every row that raised, for callers that read only the census. items: type: string title: Row Errors type: array required: - committed - submitted_rows - existing_stores - created - enriched - unchanged - not_created - errors - matched_store_number - matched_proximity - matched_address - near_misses - unmatched_existing - phones_written - urls_written - fields_superseded - legacy_keys_preserved - rekey_skipped_conflict title: StoreUpsertResultOut type: object ErrorOut: description: |- RFC 9457 Problem Details response. All API errors are returned in this format with Content-Type: application/problem+json. examples: - detail: The requested resource was not found. error_code: not_found retryable: false status: 404 timestamp: '2026-03-31T12:00:00+00:00' title: Not Found type: https://closient.com/docs/errors/not_found - detail: Validation error. details: - loc: - body - name msg: Field required type: missing error_code: validation_error retryable: false status: 422 timestamp: '2026-03-31T12:00:00+00:00' title: Validation Error type: https://closient.com/docs/errors/validation_error - detail: Rate limit exceeded. Please try again later. error_code: rate_limited retry_after: 31 retryable: true status: 429 timestamp: '2026-03-31T12:00:00+00:00' title: Rate Limited type: https://closient.com/docs/errors/rate_limited properties: type: description: URI reference identifying the error type. title: Type type: string title: description: Short human-readable summary of the error. title: Title type: string status: description: HTTP status code. title: Status type: integer detail: description: Human-readable explanation of this specific occurrence. title: Detail type: string error_code: description: Machine-readable error code (e.g. not_found, unauthorized). title: Error Code type: string retryable: default: false description: Whether retrying the same request can succeed. title: Retryable type: boolean timestamp: description: ISO 8601 timestamp of when the error occurred. title: Timestamp type: string retry_after: anyOf: - type: integer - type: 'null' description: Seconds to wait before retrying (when applicable). title: Retry After owner_action_required: anyOf: - type: boolean - type: 'null' description: Whether the error requires account owner intervention. title: Owner Action Required details: description: Additional context (validation errors, etc.). title: Details required: - type - title - status - detail - error_code - timestamp title: ErrorOut type: object StoreRowResultOut: description: What happened to one submitted row. examples: - conflict: '' distance_m: 18.4 error: '' index: 0 match_method: proximity outcome: enriched store_number: '595' properties: index: description: Zero-based position of this row in the submitted `rows` array. minimum: 0 title: Index type: integer store_number: description: The `store_number` submitted for this row. title: Store Number type: string outcome: description: >- `created` — a new store and place were written. `enriched` — an existing store matched and at least one column, link or provenance record changed. `unchanged` — an existing store matched and nothing needed changing (the idempotent rerun case). `not_created` — the row matched nothing and `allow_create` was false, so no storefront was invented. `error` — this row raised; see `error`. The rest of the batch still applied. title: Outcome type: string match_method: $ref: '#/components/schemas/StoreMatchMethodEnum' description: >- Which tier tied this row to an existing store: `store_number` (exact), `proximity` (within `proximity_m`, resolved globally nearest-pair-first), `address` (normalised street plus postal code), or `none` for a row that matched nothing. distance_m: anyOf: - type: number - type: 'null' description: >- Distance to the matched store in metres. Set for a `proximity` match, else null. title: Distance M conflict: default: '' description: >- Non-empty when the evidence was contradictory — typically the row's store number matches one existing store while a *different* existing store sits inside the proximity radius, meaning those two rows duplicate each other. The store is still enriched; its store number is deliberately **not** re-keyed on a guess, and the pair is left for a human to merge. title: Conflict type: string error: default: '' description: Failure message when `outcome` is `error`. Empty otherwise. title: Error type: string required: - index - store_number - outcome - match_method title: StoreRowResultOut type: object StoreMatchMethodEnum: description: |- How a submitted store row was tied to an existing store (C-5966). Mirrors :class:`apps.retailers.importers.store_reconcile.MatchMethod`. Listed in descending confidence, which is also the order the matcher runs its tiers in — each tier only sees rows the tiers above it did not claim, and every existing store can be claimed by at most one row: * ``store_number`` — the row's store number equals an existing one. Exact, so it wins outright, and it is what makes a repeated import idempotent rather than proximity-matched. * ``proximity`` — within the request's ``proximity_m`` of an existing store's coordinates. Resolved globally nearest-pair-first rather than in row order, so two rows competing for one store resolve to the closer one. * ``address`` — normalised street plus postal code. Catches stores whose recorded coordinates are wrong by more than the radius, and stores with no coordinates at all. * ``none`` — matched nothing, so the row is a genuinely new store (or, with ``allow_create`` false, is reported and skipped). enum: - store_number - proximity - address - none title: StoreMatchMethodEnum type: string securitySchemes: APIKeyHeaderAuth: type: apiKey in: header name: X-API-Key OAuthTokenAuth: type: http scheme: bearer CookieGatedSessionAuth: type: apiKey in: cookie name: sessionid ````