openapi: 3.1.0
info:
  title: hikie Store API
  version: 1.0.0
  summary: Read a hikie store and manage its products, payment links and discounts.
  description: |
    The Store API lets a seller's own software act on one hikie store.

    **Authentication.** Send a store API key as `Authorization: Bearer hks_...`.
    Each key belongs to exactly one store and carries a list of permissions.
    The store is never selected by a request field.

    **Permissions.** Every operation lists the permission it needs in
    `x-required-permission`. A key without it receives `403 API_PERMISSION_DENIED`.
    Operations marked `x-requires-developer-access` also need approved developer
    access, otherwise they return `403 API_ACCESS_NOT_APPROVED`.

    **Retries.** Send `Idempotency-Key` on every `POST`, `PATCH` and `DELETE`.
    It is required on `POST` for scoped keys.

    **Errors.** Errors are `{ "status": number, "message": string, "errorCode"?: string }`.
    Branch on the status and `errorCode`; `message` is Turkish and may change.

    **Versioning.** Clients must ignore unknown response fields and tolerate new
    values in `status`, `kind` and `errorCode`. Breaking changes are announced at
    least 90 days ahead; see /docs/store-api/versioning.

    Human-readable documentation: /docs/store-api (Turkish: /tr/docs/store-api).
    Plain-text index for assistants: /llms.txt.
  contact:
    name: hikie developer documentation
servers:
  - url: https://api.hikie.space/v1
security:
  - StoreKey: []
tags:
  - name: Store
  - name: Products
  - name: Orders
  - name: Reports
  - name: Payment links
  - name: Discounts
  - name: Campaigns
  - name: Discount codes
paths:
  /store:
    get:
      tags: [Store]
      operationId: getStore
      summary: Get the key's store
      x-required-permission: store:read
      responses:
        '200':
          description: The store.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Store' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /products:
    get:
      tags: [Products]
      operationId: listProducts
      summary: List digital products (including legacy)
      description: |
        Newest first. Physical products are not returned in this release.
        `page` × `limit` may not exceed 5000 (`PAGE_TOO_DEEP`).
      x-required-permission: products:read
      parameters:
        - { $ref: '#/components/parameters/Page' }
        - { $ref: '#/components/parameters/Limit' }
        - name: type
          in: query
          description: Return only one kind. Omit for both.
          schema: { type: string, enum: [digital, membership] }
      responses:
        '200':
          description: A page of products.
          content:
            application/json:
              schema:
                type: object
                required: [items, total, page, limit]
                properties:
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/ProductSummary' }
                  total: { type: integer }
                  page: { type: integer }
                  limit: { type: integer }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
    post:
      tags: [Products]
      operationId: createProduct
      summary: Create a draft product
      description: |
        Creates a **draft**. `shipmentAdressCollected: true` creates a `physical`
        product with one variant, `stock` and paid shipping (only `one-off`).
        `false` creates a hidden digital product (`type: membership`) with unlimited stock that the seller
        delivers; it can be `one-off`, `recurring` or `free` (see `paymentType`).
        The legacy digital product type (`digital`) is never created.
        A store can create 50 products per day (Turkey time).
        If the response has `id: null` and `syncPending: true` the product was
        still created; do not retry with a new Idempotency-Key.
      x-required-permission: products:write
      parameters:
        - { $ref: '#/components/parameters/IdempotencyKeyRequired' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateProduct' }
      responses:
        '201':
          description: The created draft.
          headers:
            Idempotent-Replay: { $ref: '#/components/headers/IdempotentReplay' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProductResult' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/IdempotencyReused' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /products/{id}:
    parameters:
      - { $ref: '#/components/parameters/ProductId' }
    get:
      tags: [Products]
      operationId: getProduct
      summary: Get one digital product (including legacy)
      description: Physical products return 404 in this release.
      x-required-permission: products:read
      responses:
        '200':
          description: The product with its details.
          content:
            application/json:
              schema:
                oneOf:
                  - { $ref: '#/components/schemas/DigitalProductDetail' }
                  - { $ref: '#/components/schemas/MembershipDetail' }
                discriminator:
                  propertyName: type
                  mapping:
                    digital: '#/components/schemas/DigitalProductDetail'
                    membership: '#/components/schemas/MembershipDetail'
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
    patch:
      tags: [Products]
      operationId: updateProduct
      summary: Edit a product
      description: |
        Works on any product in the store. Send at least one field.
        Stock cannot be edited in this release.
      x-required-permission: products:write
      parameters:
        - { $ref: '#/components/parameters/IdempotencyKeyOptional' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdateProduct' }
      responses:
        '200':
          description: The updated product.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProductResult' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/IdempotencyReused' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /products/{id}/publish:
    post:
      tags: [Products]
      operationId: publishProduct
      summary: Put a product on sale
      description: |
        Needs a verified store. A physical or legacy digital product needs a price
        above zero, and a physical product needs stock. Publishing does not check
        that there is delivery content.
      x-required-permission: products:write
      parameters:
        - { $ref: '#/components/parameters/ProductId' }
        - { $ref: '#/components/parameters/IdempotencyKeyRequired' }
      responses:
        '200':
          description: The product, now `active`.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProductResult' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /products/{id}/unpublish:
    post:
      tags: [Products]
      operationId: unpublishProduct
      summary: Take a product off sale
      description: Physical and legacy digital products become `inactive`; a digital product (`membership`) becomes `draft`. Its payment links stop working.
      x-required-permission: products:write
      parameters:
        - { $ref: '#/components/parameters/ProductId' }
        - { $ref: '#/components/parameters/IdempotencyKeyRequired' }
      responses:
        '200':
          description: The product, now off sale.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProductResult' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /images:
    post:
      tags: [Products]
      operationId: uploadImage
      summary: Upload a product image
      description: |
        JPEG, PNG or WebP, up to 10 MB; the type is read from the file content.
        300 uploads per day (Turkey time). Products accept only URLs returned here.
      x-required-permission: products:write
      parameters:
        - { $ref: '#/components/parameters/IdempotencyKeyRequired' }
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file: { type: string, format: binary }
      responses:
        '201':
          description: The uploaded image.
          content:
            application/json:
              schema:
                type: object
                required: [url]
                properties:
                  url: { type: string, format: uri }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /orders:
    get:
      tags: [Orders]
      operationId: listOrders
      summary: List orders
      description: Newest first. Customer email, phone and addresses are never returned.
      x-required-permission: orders:read
      parameters:
        - { $ref: '#/components/parameters/Page' }
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/From' }
        - { $ref: '#/components/parameters/To' }
        - name: status
          in: query
          schema: { $ref: '#/components/schemas/OrderStatus' }
      responses:
        '200':
          description: A page of orders.
          content:
            application/json:
              schema:
                type: object
                required: [items, total, page, limit]
                properties:
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/Order' }
                  total: { type: integer }
                  page: { type: integer }
                  limit: { type: integer }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /orders/{id}:
    get:
      tags: [Orders]
      operationId: getOrder
      summary: Get one order
      description: '`id` is the order id or its `orderNumber`.'
      x-required-permission: orders:read
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The order.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /reports/sales:
    get:
      tags: [Reports]
      operationId: getSalesReport
      summary: Sales by day, week or month
      description: |
        Paid orders grouped by period in Turkey time. Refunded, cancelled and
        failed orders are not counted in `revenue` or `orders`; refunded orders
        are reported under `refunds`. Default range is the last 30 days; the
        maximum is 1100 days.
      x-required-permission: reports:read
      parameters:
        - name: granularity
          in: query
          schema: { type: string, enum: [day, week, month], default: day }
        - { $ref: '#/components/parameters/From' }
        - { $ref: '#/components/parameters/To' }
      responses:
        '200':
          description: The report.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SalesReport' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /payment-links:
    get:
      tags: [Payment links]
      operationId: listPaymentLinks
      summary: List payment links
      description: |
        The links of the store, newest first, including those created in the
        dashboard (they are the same checkout links). Deleted links are not
        listed; expired links are, with `status: expired`. `status` reflects only
        the expiry date: a link that reached `maxUses` or whose product was
        unpublished still shows `active`.
      x-required-permission: payment_links
      parameters:
        - { $ref: '#/components/parameters/Page' }
        - { $ref: '#/components/parameters/Limit' }
        - name: status
          in: query
          description: Return only links that have not expired (`active`) or only expired ones.
          schema: { type: string, enum: [active, expired] }
      responses:
        '200':
          description: A page of payment links.
          content:
            application/json:
              schema:
                type: object
                required: [items, total, page, limit]
                properties:
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/PaymentLink' }
                  total: { type: integer }
                  page: { type: integer }
                  limit: { type: integer }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
    post:
      tags: [Payment links]
      operationId: createPaymentLink
      summary: Create a payment link for a published digital product
      description: |
        The link opens the checkout page of one digital product. Only digital products (`membership`) can
        have a payment link (`409 PRODUCT_TYPE_NOT_SUPPORTED` otherwise), and the
        product must be published and visible (`409 PRODUCT_NOT_PUBLISHED`).
        The store must be verified. The link is valid for 30 days unless
        `expiresAt` is given, and has no usage limit unless `maxUses` is given. A
        use is an opening of the checkout page, not a sale: every opening counts,
        whether or not the buyer pays, and once `useCount` reaches `maxUses` the
        link no longer opens. The link stores the product, not a price.
      x-required-permission: payment_links
      parameters:
        - { $ref: '#/components/parameters/IdempotencyKeyRequired' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreatePaymentLink' }
      responses:
        '201':
          description: The payment link.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaymentLink' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/IdempotencyReused' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /payment-links/{id}:
    get:
      tags: [Payment links]
      operationId: getPaymentLink
      summary: Get one payment link
      description: |
        A link that does not exist, belongs to another store or was deleted
        returns 404 `PAYMENT_LINK_NOT_FOUND`.
      x-required-permission: payment_links
      parameters:
        - { $ref: '#/components/parameters/PaymentLinkId' }
      responses:
        '200':
          description: The payment link.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaymentLink' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
    delete:
      tags: [Payment links]
      operationId: deletePaymentLink
      summary: Delete a payment link
      description: |
        Stops the link, and its short link, right away; the link leaves the list.
        The link is deactivated, not erased, and can be turned back on from the
        dashboard. Orders already paid through it are not affected. Deleting a
        link that is already deleted returns 404 `PAYMENT_LINK_NOT_FOUND`.
      x-required-permission: payment_links
      parameters:
        - { $ref: '#/components/parameters/PaymentLinkId' }
        - { $ref: '#/components/parameters/IdempotencyKeyOptional' }
      responses:
        '204': { description: Deleted. }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /discounts:
    get:
      tags: [Discounts]
      operationId: listDiscounts
      summary: List every discount
      description: Automatic discounts, shared-code discounts and unique-code campaigns in one list.
      x-required-permission: discount_codes:read
      x-requires-developer-access: true
      responses:
        '200':
          description: All discounts.
          content:
            application/json:
              schema:
                type: object
                required: [items, total]
                properties:
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/Discount' }
                  total: { type: integer }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /campaigns:
    get:
      tags: [Campaigns]
      operationId: listCampaigns
      summary: List unique-code campaigns
      x-required-permission: discount_codes:read
      x-requires-developer-access: true
      responses:
        '200':
          description: The store's unique-code campaigns.
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/Campaign' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
    post:
      tags: [Campaigns]
      operationId: createCampaign
      summary: Create a unique-code campaign
      description: Codes apply to one-off digital products and TRY payments only.
      x-required-permission: discount_codes:write
      x-requires-developer-access: true
      parameters:
        - { $ref: '#/components/parameters/IdempotencyKeyRequired' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateCampaign' }
      responses:
        '201':
          description: The created campaign.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Campaign' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/IdempotencyReused' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /campaigns/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Campaigns]
      operationId: getCampaign
      summary: Get one campaign
      x-required-permission: discount_codes:read
      x-requires-developer-access: true
      responses:
        '200':
          description: The campaign.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Campaign' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
    patch:
      tags: [Campaigns]
      operationId: updateCampaign
      summary: Rename, pause or extend a campaign
      description: Pausing a campaign stops all of its codes at once.
      x-required-permission: discount_codes:write
      x-requires-developer-access: true
      parameters:
        - { $ref: '#/components/parameters/IdempotencyKeyOptional' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdateCampaign' }
      responses:
        '200':
          description: The updated campaign.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Campaign' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /campaigns/{id}/codes:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Discount codes]
      operationId: listCampaignCodes
      summary: List a campaign's codes
      x-required-permission: discount_codes:read
      x-requires-developer-access: true
      parameters:
        - { $ref: '#/components/parameters/Page' }
        - { $ref: '#/components/parameters/Limit' }
      responses:
        '200':
          description: A page of codes.
          content:
            application/json:
              schema:
                type: object
                required: [items, total, page, limit]
                properties:
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/DiscountCode' }
                  total: { type: integer }
                  page: { type: integer }
                  limit: { type: integer }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
    post:
      tags: [Discount codes]
      operationId: addCampaignCodes
      summary: Add up to 1000 codes to a campaign
      description: |
        A code is unique in the store across all campaigns. If any item is
        invalid the whole request fails and nothing is created. A code that
        already exists is reported as `exists`.
      x-required-permission: discount_codes:write
      x-requires-developer-access: true
      parameters:
        - { $ref: '#/components/parameters/IdempotencyKeyRequired' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AddCodes' }
      responses:
        '201':
          description: One result per code.
          content:
            application/json:
              schema:
                type: object
                required: [results]
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      required: [code, status]
                      properties:
                        code: { type: string }
                        status: { type: string, enum: [created, exists] }
                        id: { type: string }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/IdempotencyReused' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /discount-codes/{code}:
    parameters:
      - name: code
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Discount codes]
      operationId: getDiscountCode
      summary: Get one code
      x-required-permission: discount_codes:read
      x-requires-developer-access: true
      responses:
        '200':
          description: The code.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DiscountCode' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
    patch:
      tags: [Discount codes]
      operationId: updateDiscountCode
      summary: Activate or deactivate a code
      x-required-permission: discount_codes:write
      x-requires-developer-access: true
      parameters:
        - { $ref: '#/components/parameters/IdempotencyKeyOptional' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [isActive]
              properties:
                isActive: { type: boolean }
      responses:
        '200':
          description: The updated code.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DiscountCode' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
    delete:
      tags: [Discount codes]
      operationId: deleteDiscountCode
      summary: Delete a code that was never used
      description: A used code, or one whose payment is in progress, returns 409 `DISCOUNT_CODE_IN_USE`; deactivate it instead.
      x-required-permission: discount_codes:write
      x-requires-developer-access: true
      parameters:
        - { $ref: '#/components/parameters/IdempotencyKeyOptional' }
      responses:
        '204': { description: Deleted. }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/RateLimited' }
components:
  securitySchemes:
    StoreKey:
      type: http
      scheme: bearer
      description: A store API key starting with `hks_`, created under Settings → API keys.
  headers:
    IdempotentReplay:
      description: '`true` when the response is the stored result of an earlier request with the same Idempotency-Key.'
      schema: { type: string, enum: ['true'] }
  parameters:
    Page:
      name: page
      in: query
      schema: { type: integer, minimum: 1, default: 1 }
    Limit:
      name: limit
      in: query
      schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
    From:
      name: from
      in: query
      description: |
        A day (`2026-11-01`, Turkey time) or an ISO 8601 timestamp with a time zone.
        Must be before `to`.
      schema:
        type: string
        pattern: '^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2}))?$'
    To:
      name: to
      in: query
      description: |
        A day (`2026-11-07`, the whole day is included) or an ISO 8601 timestamp
        with a time zone (that moment is included).
      schema:
        type: string
        pattern: '^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2}))?$'
    ProductId:
      name: id
      in: path
      required: true
      schema: { type: string, pattern: '^[a-fA-F0-9]{24}$' }
    PaymentLinkId:
      name: id
      in: path
      required: true
      description: The `id` returned when the link was created or listed.
      schema: { type: string, pattern: '^[a-fA-F0-9]{24}$' }
    IdempotencyKeyRequired:
      name: Idempotency-Key
      in: header
      required: true
      description: |
        1–255 characters, new for each intended change. Retrying the same request
        with the same value returns the first result. A different request with the
        same value returns 422. Results are kept for 24 hours. Required on POST for
        scoped keys.
      schema: { type: string, minLength: 1, maxLength: 255 }
    IdempotencyKeyOptional:
      name: Idempotency-Key
      in: header
      required: false
      description: Optional on PATCH and DELETE, but recommended. Same rules as on POST.
      schema: { type: string, minLength: 1, maxLength: 255 }
  responses:
    BadRequest:
      description: |
        The request is invalid. Possible `errorCode` values include
        DATE_RANGE_INVALID, PAGE_TOO_DEEP, STOCK_NOT_ALLOWED, EMPTY_UPDATE,
        IMAGE_REQUIRED, IMAGE_TOO_LARGE, IMAGE_TYPE_NOT_ALLOWED,
        IMAGE_URL_NOT_ALLOWED, IMAGE_DUPLICATE, IMAGE_STORAGE_UNAVAILABLE,
        PRODUCT_CREATE_FAILED, EXPIRES_AT_INVALID,
        PAYMENT_TYPE_NOT_ALLOWED, PRICE_REQUIRED, PRICE_NOT_ALLOWED,
        RECURRING_FIELDS_REQUIRED, RECURRING_FIELDS_NOT_ALLOWED,
        PAYMENT_PERIOD_NOT_SUPPORTED, INVALID_PAYMENT_PERIOD, INVALID_DURATION,
        IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_INVALID. A body that fails
        validation has no `errorCode`.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Unauthorized:
      description: |
        API_KEY_MISSING, API_KEY_INVALID, API_KEY_REVOKED or API_KEY_EXPIRED.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Forbidden:
      description: |
        API_PERMISSION_DENIED, API_ACCESS_NOT_APPROVED, STORE_INACTIVE or
        STORE_NOT_VERIFIED.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: |
        PRODUCT_NOT_FOUND, ORDER_NOT_FOUND, STORE_NOT_FOUND, CAMPAIGN_NOT_FOUND,
        DISCOUNT_CODE_NOT_FOUND or PAYMENT_LINK_NOT_FOUND. Another store's records are reported as not found.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Conflict:
      description: |
        IDEMPOTENCY_IN_PROGRESS, PRODUCT_NOT_READY, PRODUCT_HAS_VARIANTS,
        PRICE_CHANGE_NOT_ALLOWED, DISCOUNT_EXCEEDS_PRICE, PRODUCT_NOT_PUBLISHED,
        PRODUCT_TYPE_NOT_SUPPORTED or DISCOUNT_CODE_IN_USE.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    IdempotencyReused:
      description: IDEMPOTENCY_KEY_REUSED. The Idempotency-Key was used for a different request.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    RateLimited:
      description: |
        RATE_LIMIT_EXCEEDED (retry after `Retry-After` seconds) or, on product and
        image creation, DAILY_LIMIT_REACHED.
      headers:
        Retry-After:
          description: Seconds to wait. Present on RATE_LIMIT_EXCEEDED.
          schema: { type: integer }
        X-RateLimit-Limit: { schema: { type: integer } }
        X-RateLimit-Remaining: { schema: { type: integer } }
        X-RateLimit-Reset:
          description: Unix seconds when the window resets.
          schema: { type: integer }
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
  schemas:
    Error:
      type: object
      required: [status, message]
      properties:
        status: { type: integer }
        message: { type: string, description: Turkish, human-readable. May change. }
        errorCode: { type: string, description: Machine-readable code. Branch on this. }
    Store:
      type: object
      required: [id, verification, salesOpen, storeClosed, activeProducts]
      properties:
        id: { type: string }
        name: { type: [string, 'null'] }
        subdomain: { type: [string, 'null'] }
        address: { type: [string, 'null'] }
        logo: { type: [string, 'null'] }
        verification: { type: string, enum: [verified, pending, under_review, suspended] }
        salesOpen: { type: boolean }
        storeClosed: { type: boolean }
        activeProducts:
          type: object
          properties:
            digital: { type: integer }
            membership: { type: integer }
            total: { type: integer }
    ProductSummary:
      type: object
      required: [id, type, name, status, currency, images]
      properties:
        id: { type: string }
        type: { type: string, enum: [digital, membership] }
        name: { type: string }
        slug: { type: [string, 'null'] }
        status: { type: [string, 'null'], description: 'legacy digital: draft, active or inactive. membership (digital product): draft or active.' }
        price: { type: [number, 'null'], description: Current selling price in TRY. Null for a free digital product. }
        compareAtPrice: { type: [number, 'null'] }
        paymentType: { $ref: '#/components/schemas/PaymentType', description: Listed for `membership`; legacy `digital` products show it in the detail. }
        currency: { type: string, examples: [TRY] }
        images: { type: array, items: { type: string, format: uri } }
        createdAt: { type: [string, 'null'], format: date-time }
        updatedAt: { type: [string, 'null'], format: date-time }
    DigitalProductDetail:
      allOf:
        - { $ref: '#/components/schemas/ProductSummary' }
        - { $ref: '#/components/schemas/ProductPayment' }
        - type: object
          properties:
            description: { type: [string, 'null'] }
            categories: { type: array, items: { type: string } }
            tags: { type: array, items: { type: string } }
            variants:
              type: array
              items:
                type: object
                properties:
                  id: { type: string }
                  sku: { type: [string, 'null'] }
                  price: { type: number }
                  compareAtPrice: { type: [number, 'null'] }
                  isActive: { type: boolean }
    MembershipDetail:
      allOf:
        - { $ref: '#/components/schemas/ProductSummary' }
        - { $ref: '#/components/schemas/ProductPayment' }
        - type: object
          properties:
            description: { type: [string, 'null'] }
            headline: { type: [string, 'null'] }
            isFree: { type: boolean }
            isVisible: { type: boolean }
            pricing:
              type: object
              properties:
                type: { type: [string, 'null'], description: one-time or subscription. }
                price: { type: [number, 'null'] }
                discountedPrice: { type: [number, 'null'] }
                currency: { type: string }
                subscriptionDuration: {}
                maxCharges: {}
            features: { type: array, items: {} }
            faqs:
              type: array
              items:
                type: object
                properties:
                  question: { type: string }
                  answer: { type: string }
    CreateProduct:
      type: object
      additionalProperties: false
      required: [name, vatRate, paymentType, shipmentAdressCollected]
      description: There is no `type` field. `shipmentAdressCollected` and `paymentType` decide whether a physical or a digital product is created.
      properties:
        name: { type: string, minLength: 1, maxLength: 120 }
        description: { type: string, maxLength: 5000 }
        price:
          type: [number, 'null']
          minimum: 0.01
          maximum: 1000000
          multipleOf: 0.01
          description: TRY, all taxes included (this is what the buyer pays). Required unless `paymentType` is `free`, where it must be omitted or null. For `recurring` it is the amount of each charge.
        images:
          type: array
          maxItems: 10
          uniqueItems: true
          items: { type: string, maxLength: 500, format: uri }
          description: URLs returned by POST /images.
        stock:
          type: integer
          minimum: 0
          maximum: 1000000
          default: 0
          description: Only with `shipmentAdressCollected` true.
        vatRate: { type: integer, enum: [0, 1, 10, 20], description: 'VAT rate in percent. Required. VAT is taken out of `price`, never added on top.' }
        paymentType: { $ref: '#/components/schemas/PaymentType' }
        paymentPeriod:
          type: string
          enum: [weekly, monthly, yearly]
          description: '`recurring` only. How often the buyer is charged. `weekly` is not available yet (400 PAYMENT_PERIOD_NOT_SUPPORTED).'
        paymentPeriodCount:
          type: integer
          minimum: 1
          maximum: 52
          description: '`recurring` only. Charge every this many periods. At most 12 for `monthly` and 10 for `yearly`.'
        durationInCycleCount:
          type: integer
          minimum: 1
          maximum: 3650
          description: '`recurring` only. Total length of the subscription, in `durationInCyclePeriod` units. Must be a whole multiple of the charge period; at most 120 months and 60 charges.'
        durationInCyclePeriod:
          type: string
          enum: [day, week, month, year]
          description: '`recurring` only. `day` and `week` are not available yet.'
        shipmentAdressCollected:
          type: boolean
          description: 'Required. Decides the product type. `true`: a physical product with a delivery address, only `one-off`. `false`: a digital product, `type: membership` (`one-off`, `recurring` or `free`).'
    PaymentType:
      type: string
      enum: [one-off, recurring, free]
      description: 'Required when creating a product; there is no default. `recurring` and `free` are not allowed with `shipmentAdressCollected: true`; without a delivery address every payment type creates a digital product. A `free` product has no price.'
    ProductPayment:
      type: object
      description: Payment fields, returned with the values that were received.
      properties:
        paymentType: { $ref: '#/components/schemas/PaymentType' }
        vatRate: { type: [integer, 'null'], enum: [0, 1, 10, 20, null], description: 'Prices include all taxes. `null` only for products created in the dashboard without a VAT rate.' }
        shipmentAdressCollected: { type: boolean }
        paymentPeriod: { type: [string, 'null'], enum: [weekly, monthly, yearly, null] }
        paymentPeriodCount: { type: [integer, 'null'] }
        durationInCycleCount: { type: [integer, 'null'] }
        durationInCyclePeriod: { type: [string, 'null'], enum: [day, week, month, year, null] }
    UpdateProduct:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        name: { type: string, minLength: 1, maxLength: 120 }
        description: { type: string, maxLength: 5000 }
        price: { type: number, minimum: 0.01, maximum: 1000000, multipleOf: 0.01, description: 'TRY, all taxes included.' }
        images:
          type: array
          maxItems: 10
          uniqueItems: true
          items: { type: string, maxLength: 500, format: uri }
    ProductResult:
      type: object
      required: [type, name]
      properties:
        id:
          type: [string, 'null']
          description: Null only when `syncPending` is true; the product was still created.
        syncPending: { type: boolean }
        type: { type: string, enum: [digital, physical, membership] }
        name: { type: string }
        status: { type: [string, 'null'], description: 'draft, active or inactive.' }
        price: { type: [number, 'null'], description: Null for a free product. }
        images: { type: array, items: { type: string } }
      allOf:
        - { $ref: '#/components/schemas/ProductPayment' }
    OrderStatus:
      type: string
      enum: [PENDING, PROCESSING, COMPLETED, CANCELLED, FAILED, REFUNDED]
    Order:
      type: object
      description: Customer identity, contact, addresses and payment references are deliberately omitted.
      required: [id, orderNumber, isPaid, currency, totalAmount, items]
      properties:
        id: { type: string }
        orderNumber: { type: string }
        status: { oneOf: [{ $ref: '#/components/schemas/OrderStatus' }, { type: 'null' }] }
        isPaid: { type: boolean }
        paidAt: { type: [string, 'null'], format: date-time }
        createdAt: { type: [string, 'null'], format: date-time }
        cancelledAt: { type: [string, 'null'], format: date-time }
        currency: { type: string }
        totalAmount: { type: number }
        items:
          type: array
          items:
            type: object
            properties:
              productId: { type: [string, 'null'] }
              name: { type: [string, 'null'] }
              variant: {}
              quantity: { type: number }
              price: { type: number }
              itemType: { type: string, enum: [product, membership] }
        discountCodes: { type: array, items: { type: string } }
        source: { type: [string, 'null'] }
    SalesReport:
      type: object
      required: [granularity, from, to, rows, totals]
      properties:
        granularity: { type: string, enum: [day, week, month] }
        from: { type: string, format: date-time }
        to: { type: string, format: date-time }
        rows:
          type: array
          items:
            type: object
            properties:
              period: { type: string, description: 'YYYY-MM-DD, ISO week like 2026-W44, or YYYY-MM.' }
              currency: { type: string }
              revenue: { type: number }
              orders: { type: integer }
              refunds: { $ref: '#/components/schemas/RefundTotals' }
        totals:
          type: object
          description: Totals per currency, keyed by currency code.
          additionalProperties:
            type: object
            properties:
              revenue: { type: number }
              orders: { type: integer }
              refunds: { $ref: '#/components/schemas/RefundTotals' }
    RefundTotals:
      type: object
      properties:
        count: { type: integer }
        amount: { type: number }
    CreatePaymentLink:
      type: object
      additionalProperties: false
      required: [productId]
      properties:
        productId: { type: string, pattern: '^[a-fA-F0-9]{24}$', description: A published digital product (`membership`) in your store. }
        maxUses: { type: integer, minimum: 1, maximum: 1000000, description: How many times the link can be opened. Every opening of the checkout page counts, not every sale. Omit for no limit. }
        expiresAt:
          type: string
          format: date-time
          description: |
            When the link stops working. ISO 8601 with a time zone, in the future
            and at most 365 days ahead (`EXPIRES_AT_INVALID` otherwise). Omit for 30 days.
    PaymentLink:
      type: object
      required: [id, url, productId, maxUses, useCount, isMaxUsesApplied, status, expiresAt]
      properties:
        id: { type: string, description: Use it to read or delete the link. }
        url: { type: string, format: uri }
        productId: { type: string, description: The digital product the link sells. }
        maxUses: { type: [integer, 'null'], description: How many times the link can be opened; null for no limit. }
        useCount: { type: integer, description: How many times the checkout page has been opened through the link. Not the number of sales. }
        isMaxUsesApplied: { type: boolean, description: '`true` once `useCount` reaches `maxUses`; the link no longer opens.' }
        status: { type: string, enum: [active, expired], description: '`active` until `expiresAt`. Does not look at `maxUses`.' }
        createdAt: { type: [string, 'null'], format: date-time }
        expiresAt: { type: string, format: date-time }
    Discount:
      type: object
      properties:
        id: { type: string }
        kind: { type: string, enum: [automatic, shared_code, unique_codes] }
        name: { type: [string, 'null'] }
        code: { type: [string, 'null'], description: Set only for `shared_code`. }
        type: { type: string, enum: [percent, amount, free_shipping, free_product] }
        percentOff: { type: [number, 'null'] }
        amountOff: { type: [number, 'null'] }
        amountMinimum: { type: number }
        currency: { type: string }
        startsAt: { type: [string, 'null'], format: date-time }
        expiresAt: { type: [string, 'null'], format: date-time }
        isActive: { type: boolean }
        usageCount: { type: integer, description: Paid orders that used the discount. }
        maxUses: { type: [integer, 'null'] }
        createdAt: { type: [string, 'null'], format: date-time }
    CreateCampaign:
      type: object
      additionalProperties: false
      required: [name, type]
      properties:
        name: { type: string, minLength: 1, maxLength: 80 }
        type: { type: string, enum: [percent, amount] }
        percentOff: { type: number, exclusiveMinimum: 0, maximum: 100, description: Required when type is percent. }
        amountOff: { type: number, exclusiveMinimum: 0, description: Required when type is amount. TRY. }
        amountMinimum: { type: number, minimum: 0, default: 0 }
        currency: { type: string, enum: [TRY], default: TRY }
        startsAt: { type: string, format: date-time }
        expiresAt: { type: string, format: date-time }
        membershipIds:
          type: array
          maxItems: 100
          items: { type: string }
          description: Limit to these one-off digital products. Empty means all.
    UpdateCampaign:
      type: object
      additionalProperties: false
      properties:
        name: { type: string, minLength: 1, maxLength: 80 }
        isActive: { type: boolean }
        expiresAt: { type: string, format: date-time }
    Campaign:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        type: { type: string, enum: [percent, amount] }
        percentOff: { type: [number, 'null'] }
        amountOff: { type: [number, 'null'] }
        amountMinimum: { type: number }
        currency: { type: string }
        startsAt: { type: [string, 'null'], format: date-time }
        expiresAt: { type: [string, 'null'], format: date-time }
        membershipIds: { type: array, items: { type: string } }
        isActive: { type: boolean }
        codes:
          type: object
          properties:
            total: { type: integer }
            used: { type: integer }
            reserved: { type: integer, description: Redemptions whose payment is in progress. }
            remaining: { type: integer }
        createdAt: { type: string, format: date-time }
    AddCodes:
      type: object
      additionalProperties: false
      required: [codes]
      properties:
        codes:
          type: array
          maxItems: 1000
          items:
            type: object
            additionalProperties: false
            required: [code]
            properties:
              code: { type: string, minLength: 8, maxLength: 40, description: 'A–Z, 0–9 and -. Upper-cased.' }
              numAvailable: { type: integer, minimum: 1, maximum: 100000, default: 1, description: Total number of uses. }
    DiscountCode:
      type: object
      properties:
        id: { type: string }
        code: { type: string }
        campaignId: { type: string }
        maxUses: { type: integer }
        numUsed: { type: integer }
        numAvailable: { type: integer, description: Uses left, excluding redemptions in progress. }
        isActive: { type: boolean }
        createdAt: { type: string, format: date-time }
