{
  "openapi": "3.1.0",
  "info": {
    "title": "Cross&Sell Store API",
    "version": "1.0.0-beta",
    "description": "Beta. Store API for stores on their own software or an open-source platform: send products, fetch partner offers, report impressions, clicks and orders. Every response carries `X-Request-Id`. Rate limits are approximate and per store (all keys of a store share them); above them you get `429` with `Retry-After`. Write endpoints are safe to retry: products are keyed by `id`, orders by order id, refunds by status."
  },
  "servers": [
    { "url": "https://api.crossandsell.com/v1" },
    { "url": "https://app.crossandsell.com/api/v1/store", "description": "Earlier address; same endpoints" }
  ],
  "security": [{ "storeKey": [] }],
  "paths": {
    "/store": {
      "servers": [
        { "url": "https://api.crossandsell.com/v1" },
        { "url": "https://app.crossandsell.com/api/v1", "description": "Earlier address: the store summary is the API root, `/api/v1/store`" }
      ],
      "get": {
        "summary": "Connection test and store summary",
        "description": "Rate limit: about 60 requests per minute per store.",
        "operationId": "getStore",
        "responses": {
          "200": {
            "description": "Store summary",
            "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/Store" } } } } }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/products": {
      "put": {
        "summary": "Add or update products",
        "description": "Up to 500 products per request, 5,000 per store. Same `id` updates the product. Rate limit: about 60 requests per minute per store.",
        "operationId": "upsertProducts",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["products"],
                "properties": { "products": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/ProductInput" } } }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Written",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "data": { "type": "object", "properties": { "upserted": { "type": "integer" }, "catalogCount": { "type": "integer" } } } }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "422": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "get": {
        "summary": "List your catalogue",
        "description": "Ordered by `id`. Rate limit: about 60 requests per minute per store.",
        "operationId": "listProducts",
        "parameters": [
          { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "`next_cursor` from the previous page" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 200 } }
        ],
        "responses": {
          "200": {
            "description": "One page",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["object", "data", "has_more", "next_cursor"],
                  "properties": {
                    "object": { "const": "list" },
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } },
                    "has_more": { "type": "boolean" },
                    "next_cursor": { "type": ["string", "null"] }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/products/selection": {
      "put": {
        "summary": "Choose products and open partner offers",
        "description": "Same as saving the panel's product selection, with the same rules. `selected_ids` is the whole selection (products left out leave it); `offer_ids` (optional, a subset of `selected_ids`) opens partner offers on those products. It only opens: closing an open offer is done in the panel. Sending the same body again gives the same result. Nothing is written when the request is rejected. Plan limits: `422 too_many_products` / `422 too_many_offers` with `limit`, `current` (now) and `requested`. Changes the panel asks to confirm or that spend a swap right are rejected with `409` (`locked_offer`: a close-locked product cannot leave the selection; `swap_required`: opening an offer in the slot freed by a product leaving the selection). Rate limit: about 60 requests per minute per store.",
        "operationId": "setProductSelection",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectionInput" } } }
        },
        "responses": {
          "200": {
            "description": "Saved",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Selection" } } } } }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" },
          "422": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/products/{id}": {
      "delete": {
        "summary": "Delete a product",
        "description": "If the product is selected it leaves the selection at once. A selected product that is close-locked (3 or more live partner offers, or opened by Cross+Cross) cannot be deleted: `409 locked_offer`; change it from the panel. Rate limit: about 60 requests per minute per store.",
        "operationId": "deleteProduct",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 128 } }],
        "responses": {
          "200": {
            "description": "Deleted",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "const": true } } } } } } }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/offers": {
      "get": {
        "summary": "Partner offers for one of your product pages",
        "description": "Call from your server. The request itself is not counted as an impression: call `impression_url` from the browser when the offer is visible, and send shoppers to `click_url`. The response is `Cache-Control: private, no-store`: each `impression_url` is bound to one visitor. Cache it only per (product, placement, visitor) and for well under the 30-minute token life, never in a shared cache; if the call fails, render the page without offers. Rate limit: about 600 requests per minute per store.",
        "operationId": "listOffers",
        "parameters": [
          { "name": "product_id", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 128 }, "description": "Your product `id`" },
          {
            "name": "placement",
            "in": "query",
            "schema": { "type": "string", "enum": ["product_page", "cart_drawer", "cart_page", "checkout", "thank_you"], "default": "product_page" }
          },
          { "name": "visitor", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 128 }, "description": "Your opaque visitor id. Only a hash is stored." },
          {
            "name": "demo",
            "in": "query",
            "schema": { "type": "string", "enum": ["1", "true", "0", "false"] },
            "description": "Test mode only: `1` returns a sample offer built from your selected product when it has no real offer (`demo: true`). Its `impression_url` completes the impression setup step; its `click_url` opens your own product page with `cs_click=demo_…`, and an order with that `clickId` returns `reason: demo_click`. Ignored when live."
          }
        ],
        "responses": {
          "200": {
            "description": "Offers (empty list if none)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["object", "data"],
                  "properties": {
                    "object": { "const": "list" },
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } },
                    "demo": { "const": true, "description": "Present when `data` is the test-mode sample offer" },
                    "reason": {
                      "type": "string",
                      "enum": ["product_not_in_catalog", "product_not_selected", "offer_not_enabled", "domain_not_verified", "test_no_partner", "no_partner_offer"],
                      "description": "Present when `data` is empty: why there is no offer"
                    },
                    "message": { "type": "string", "description": "Human-readable (Turkish) explanation of `reason`" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/orders": {
      "post": {
        "summary": "Report a paid order",
        "description": "Only the click in `clickId` (the `cs_click` value) can be credited; an order without `clickId` is accepted and not credited. When nothing is credited the response says why in `reason`; clickId problems also show as warnings in the panel's API errors list. Sending the same order again creates nothing new; a different amount for a credited product returns `409 order_conflict`. Only TRY is accepted in Beta; another `currency` returns `422 unsupported_currency`. Rate limit: about 300 requests per minute per store.",
        "operationId": "createOrder",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderInput" } } } },
        "responses": {
          "200": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "attributed": { "type": "integer" },
                        "reason": {
                          "type": "string",
                          "enum": ["no_click_id", "demo_click", "click_not_found", "click_already_used", "click_expired", "click_after_order", "product_not_in_order", "not_attributed"],
                          "description": "Present when `attributed` is 0: why no sale was credited. The order is still accepted; do not retry."
                        },
                        "message": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" },
          "422": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/orders/{id}/refund": {
      "post": {
        "summary": "Full refund or cancellation of an order",
        "description": "No partial refunds in Beta. Rate limit: about 300 requests per minute per store.",
        "operationId": "refundOrder",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 128 } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "type": "object", "required": ["status"], "properties": { "status": { "type": "string", "enum": ["refunded", "cancelled"] } } }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "updated": { "type": "integer" },
                        "reason": { "const": "no_attributed_sales", "description": "Present when `updated` is 0: no sale is credited to this order (never reported, or not credited to a click)" },
                        "message": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/events/impression": {
      "get": {
        "summary": "Record an impression",
        "description": "Called from the shopper's browser (the `impression_url` of an offer), no key. CORS open. The token expires after 30 minutes. A repeated impression for the same visitor, product and day is not counted again. Rate limit per IP.",
        "operationId": "recordImpression",
        "security": [],
        "parameters": [{ "name": "t", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "204": { "description": "Recorded" },
          "400": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/domain/verify": {
      "post": {
        "summary": "Verify your domain",
        "description": "Put `verificationCode` from `GET /store` into `https://<your domain>/.well-known/crossandsell-verification.txt`, then call this endpoint. Our server reads the file over https from your registered domain only (one redirect to the www or non-www form is followed). Rate limit: about 60 requests per minute per store.",
        "operationId": "verifyDomain",
        "responses": {
          "200": {
            "description": "Verified",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "data": { "type": "object", "properties": { "domainVerified": { "const": true }, "domainVerifiedAt": { "type": "string", "format": "date-time" } } } }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "422": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "storeKey": { "type": "http", "scheme": "bearer", "description": "`cs_store_…` key from the panel. Server-side only." }
    },
    "responses": {
      "Error": {
        "description": "Error",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "RateLimited": {
        "description": "Rate limit exceeded",
        "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait" } },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["message", "type", "code", "param"],
            "properties": {
              "message": { "type": "string", "description": "Human-readable (Turkish); may change. Decide on `code`." },
              "type": { "type": "string", "enum": ["invalid_request_error", "authentication_error", "rate_limit_error", "api_error"] },
              "code": {
                "type": "string",
                "enum": [
                  "missing_key",
                  "invalid_key",
                  "revoked_key",
                  "rate_limited",
                  "validation_error",
                  "url_not_on_domain",
                  "catalog_limit",
                  "unknown_product",
                  "too_many_products",
                  "too_many_offers",
                  "locked_offer",
                  "swap_required",
                  "not_found",
                  "invalid_date",
                  "unsupported_currency",
                  "amount_too_large",
                  "order_conflict",
                  "invalid_token",
                  "domain_verification_failed",
                  "server_error"
                ]
              },
              "param": { "type": ["string", "null"], "description": "The field the error is about, if any" },
              "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } },
              "productIds": { "type": "array", "items": { "type": "string" } },
              "catalogCount": { "type": "integer" },
              "ids": { "type": "array", "items": { "type": "string" }, "description": "`unknown_product`: ids not in your catalogue" },
              "limit": { "type": "integer", "description": "`too_many_products`, `too_many_offers`, `swap_required`: the plan limit" },
              "current": { "type": "integer", "description": "Selected products / open offers now" },
              "requested": { "type": "integer", "description": "What the request would make it" },
              "reason": { "type": "string", "enum": ["no_account", "unreachable", "not_found", "mismatch"] }
            }
          }
        }
      },
      "Store": {
        "type": "object",
        "properties": {
          "mode": { "type": "string", "enum": ["test", "live"] },
          "domainVerified": { "type": "boolean" },
          "verificationCode": { "type": ["string", "null"], "description": "Content of the domain verification file" },
          "integrationSeenAt": { "type": ["string", "null"], "format": "date-time", "description": "Last impression from your domain" },
          "storeName": { "type": ["string", "null"] },
          "storeSlug": { "type": ["string", "null"] },
          "domain": { "type": ["string", "null"] },
          "limits": { "type": "object", "properties": { "products": { "type": "integer" }, "offers": { "type": "integer" } } },
          "catalogCount": { "type": "integer" },
          "selectedCount": { "type": "integer" },
          "scriptInstalled": { "type": "boolean", "description": "Storefront is ready (storefront code found, or domain verified and an impression came from it)" }
        }
      },
      "ProductInput": {
        "type": "object",
        "required": ["id", "title", "url"],
        "properties": {
          "id": { "type": "string", "minLength": 1, "maxLength": 128 },
          "title": { "type": "string", "minLength": 1, "maxLength": 300 },
          "url": { "type": "string", "format": "uri", "maxLength": 2000, "description": "https, on your domain, not the home page" },
          "imageUrl": { "type": ["string", "null"], "format": "uri", "maxLength": 2000, "description": "https" },
          "price": { "type": ["number", "null"], "minimum": 0, "maximum": 9999999999 },
          "salePrice": { "type": ["number", "null"], "minimum": 0, "maximum": 9999999999 },
          "currency": { "type": ["string", "null"], "pattern": "^[A-Za-z]{3}$", "default": "TRY" },
          "stock": { "type": ["integer", "null"], "minimum": 0, "maximum": 1000000000 },
          "categories": { "type": ["array", "null"], "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 120 } },
          "brand": { "type": ["string", "null"], "maxLength": 120 },
          "active": { "type": ["boolean", "null"], "default": true }
        }
      },
      "SelectionInput": {
        "type": "object",
        "required": ["selected_ids"],
        "properties": {
          "selected_ids": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Your product ids; the whole selection" },
          "offer_ids": { "type": "array", "maxItems": 500, "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Subset of `selected_ids` whose partner offer opens" }
        }
      },
      "Selection": {
        "type": "object",
        "required": ["selected", "offers", "limits"],
        "properties": {
          "selected": { "type": "integer", "description": "Selected products" },
          "offers": { "type": "integer", "description": "Products with an open partner offer (counted against the limit)" },
          "limits": { "type": "object", "properties": { "products": { "type": "integer" }, "offers": { "type": "integer" } } }
        }
      },
      "Product": {
        "allOf": [
          { "$ref": "#/components/schemas/ProductInput" },
          {
            "type": "object",
            "properties": {
              "selected": { "type": "boolean" },
              "offerEnabled": { "type": "boolean" },
              "updatedAt": { "type": "string", "format": "date-time" }
            }
          }
        ]
      },
      "Offer": {
        "type": "object",
        "required": ["id", "title", "image_url", "price", "sale_price", "currency", "store_name", "click_url", "impression_url"],
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "image_url": { "type": ["string", "null"] },
          "price": { "type": ["number", "null"], "description": "Price the shopper pays (already discounted if on sale)" },
          "sale_price": { "type": "null", "description": "Beta: always null; `price` is already the price the shopper pays" },
          "currency": { "type": ["string", "null"] },
          "store_name": { "type": "string", "description": "Partner store" },
          "click_url": { "type": "string", "format": "uri", "description": "Send the shopper here (opens the partner product, records the click)" },
          "impression_url": { "type": "string", "format": "uri", "description": "Call from the browser when the offer is visible; valid 30 minutes" }
        }
      },
      "OrderInput": {
        "type": "object",
        "required": ["id", "createdAt", "lines"],
        "properties": {
          "id": { "type": "string", "minLength": 1, "maxLength": 128 },
          "number": { "type": ["string", "null"], "maxLength": 64 },
          "createdAt": { "type": "string", "format": "date-time", "description": "Not in the future, not older than 8 days" },
          "currency": { "type": ["string", "null"], "pattern": "^[Tt][Rr][Yy]$", "default": "TRY", "description": "Only TRY in Beta (case-insensitive); any other currency returns `422 unsupported_currency`" },
          "clickId": { "type": ["string", "null"], "maxLength": 64, "description": "The `cs_click` value from the landing URL" },
          "lines": {
            "type": "array",
            "minItems": 1,
            "maxItems": 500,
            "items": {
              "type": "object",
              "required": ["productId", "quantity", "unitPrice"],
              "properties": {
                "productId": { "type": "string", "minLength": 1, "maxLength": 128 },
                "quantity": { "type": "integer", "minimum": 1, "maximum": 100000 },
                "unitPrice": { "type": "number", "minimum": 0, "maximum": 9999999999, "description": "Paid unit price: after discount, tax included, shipping excluded. The lines of one product may add up to at most 9,999,999,999.99 (else `422 amount_too_large`)" }
              }
            }
          }
        }
      }
    }
  }
}
