openapi: 3.1.0
info:
  title: Ecwid REST API
  description: |
    JSON REST API for managing Ecwid by Lightspeed store data including
    products, categories, orders, customers, discount coupons, payment and
    shipping methods, and store profile. Requests are authenticated with
    OAuth 2.0 access tokens (private for write access, public for read-only)
    provided in the Authorization header as a Bearer token. This specification
    is a best-effort, documentation-derived description and may omit fields.
  version: 3.0.0
  contact:
    name: Ecwid by Lightspeed
    url: https://api-docs.ecwid.com/reference/overview
servers:
  - url: https://app.ecwid.com/api/v3/{storeId}
    description: Store-scoped REST root
    variables:
      storeId:
        default: '0'
        description: Your Ecwid store identifier.
security:
  - BearerAuth: []
paths:
  /profile:
    get:
      summary: Get store profile
      operationId: getStoreProfile
      responses:
        '200':
          description: Store profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreProfile'
    put:
      summary: Update store profile
      operationId: updateStoreProfile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreProfile'
      responses:
        '200':
          description: Updated
  /products:
    get:
      summary: Search products
      operationId: searchProducts
      parameters:
        - in: query
          name: keyword
          schema:
            type: string
        - in: query
          name: limit
          schema:
            type: integer
            maximum: 100
        - in: query
          name: offset
          schema:
            type: integer
        - in: query
          name: category
          schema:
            type: integer
        - in: query
          name: enabled
          schema:
            type: boolean
      responses:
        '200':
          description: Products page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductsPage'
    post:
      summary: Add a product
      operationId: createProduct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '200':
          description: Product created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
  /products/{productId}:
    parameters:
      - $ref: '#/components/parameters/ProductId'
    get:
      summary: Get a product
      operationId: getProduct
      responses:
        '200':
          description: Product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
    put:
      summary: Update a product
      operationId: updateProduct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '200':
          description: Updated
    delete:
      summary: Delete a product
      operationId: deleteProduct
      responses:
        '200':
          description: Deleted
  /categories:
    get:
      summary: Search categories
      operationId: searchCategories
      parameters:
        - in: query
          name: parent
          schema:
            type: integer
        - in: query
          name: limit
          schema:
            type: integer
        - in: query
          name: offset
          schema:
            type: integer
      responses:
        '200':
          description: Categories page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoriesPage'
    post:
      summary: Create a category
      operationId: createCategory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Category'
      responses:
        '200':
          description: Created
  /categories/{categoryId}:
    parameters:
      - in: path
        name: categoryId
        required: true
        schema:
          type: integer
    get:
      summary: Get a category
      operationId: getCategory
      responses:
        '200':
          description: Category
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
    put:
      summary: Update a category
      operationId: updateCategory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Category'
      responses:
        '200':
          description: Updated
    delete:
      summary: Delete a category
      operationId: deleteCategory
      responses:
        '200':
          description: Deleted
  /orders:
    get:
      summary: Search orders
      operationId: searchOrders
      parameters:
        - in: query
          name: keywords
          schema:
            type: string
        - in: query
          name: limit
          schema:
            type: integer
        - in: query
          name: offset
          schema:
            type: integer
        - in: query
          name: paymentStatus
          schema:
            type: string
        - in: query
          name: fulfillmentStatus
          schema:
            type: string
      responses:
        '200':
          description: Orders page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersPage'
    post:
      summary: Create an order
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '200':
          description: Created
  /orders/{orderNumber}:
    parameters:
      - in: path
        name: orderNumber
        required: true
        schema:
          type: integer
    get:
      summary: Get an order
      operationId: getOrder
      responses:
        '200':
          description: Order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
    put:
      summary: Update an order
      operationId: updateOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '200':
          description: Updated
    delete:
      summary: Delete an order
      operationId: deleteOrder
      responses:
        '200':
          description: Deleted
  /customers:
    get:
      summary: Search customers
      operationId: searchCustomers
      parameters:
        - in: query
          name: keyword
          schema:
            type: string
        - in: query
          name: limit
          schema:
            type: integer
        - in: query
          name: offset
          schema:
            type: integer
      responses:
        '200':
          description: Customers page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomersPage'
    post:
      summary: Create a customer
      operationId: createCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Customer'
      responses:
        '200':
          description: Created
  /customers/{customerId}:
    parameters:
      - in: path
        name: customerId
        required: true
        schema:
          type: integer
    get:
      summary: Get a customer
      operationId: getCustomer
      responses:
        '200':
          description: Customer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
    put:
      summary: Update a customer
      operationId: updateCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Customer'
      responses:
        '200':
          description: Updated
  /discount_coupons:
    get:
      summary: Search discount coupons
      operationId: searchCoupons
      responses:
        '200':
          description: Coupons page
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  count:
                    type: integer
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/DiscountCoupon'
    post:
      summary: Create a discount coupon
      operationId: createCoupon
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscountCoupon'
      responses:
        '200':
          description: Created
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 access token (private or public) used as a Bearer token.
  parameters:
    ProductId:
      in: path
      name: productId
      required: true
      schema:
        type: integer
  schemas:
    StoreProfile:
      type: object
      additionalProperties: true
      properties:
        generalInfo:
          type: object
          additionalProperties: true
        account:
          type: object
          additionalProperties: true
        settings:
          type: object
          additionalProperties: true
        company:
          type: object
          additionalProperties: true
        formatsAndUnits:
          type: object
          additionalProperties: true
    Product:
      type: object
      additionalProperties: true
      properties:
        id:
          type: integer
        sku:
          type: string
        name:
          type: string
        price:
          type: number
        enabled:
          type: boolean
        quantity:
          type: integer
        unlimited:
          type: boolean
        categoryIds:
          type: array
          items:
            type: integer
        description:
          type: string
    ProductsPage:
      type: object
      properties:
        total:
          type: integer
        count:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/Product'
    Category:
      type: object
      additionalProperties: true
      properties:
        id:
          type: integer
        parentId:
          type: integer
        name:
          type: string
        enabled:
          type: boolean
        productIds:
          type: array
          items:
            type: integer
    CategoriesPage:
      type: object
      properties:
        total:
          type: integer
        count:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/Category'
    Order:
      type: object
      additionalProperties: true
      properties:
        orderNumber:
          type: integer
        vendorOrderNumber:
          type: string
        email:
          type: string
        total:
          type: number
        paymentStatus:
          type: string
        fulfillmentStatus:
          type: string
        items:
          type: array
          items:
            type: object
            additionalProperties: true
    OrdersPage:
      type: object
      properties:
        total:
          type: integer
        count:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/Order'
    Customer:
      type: object
      additionalProperties: true
      properties:
        id:
          type: integer
        email:
          type: string
          format: email
        billingPerson:
          type: object
          additionalProperties: true
        shippingAddresses:
          type: array
          items:
            type: object
            additionalProperties: true
    CustomersPage:
      type: object
      properties:
        total:
          type: integer
        count:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/Customer'
    DiscountCoupon:
      type: object
      additionalProperties: true
      properties:
        name:
          type: string
        code:
          type: string
        discountType:
          type: string
        status:
          type: string
        discount:
          type: number