openapi: 3.0.3
info:
  title: Snipcart REST API
  description: >
    The Snipcart REST API provides programmatic access to your store's data including
    orders, customers, products, discounts, notifications, abandoned carts, domains,
    refunds, user sessions, and custom shipping methods. Authentication uses HTTP Basic
    Auth with a secret API key generated from the merchant dashboard. All requests must
    include an Accept: application/json header.
  version: '3.0'
  contact:
    name: Snipcart Support
    url: https://snipcart.com
  license:
    name: Proprietary
    url: https://snipcart.com/terms-of-service
servers:
  - url: https://app.snipcart.com/api
    description: Snipcart API
security:
  - basicAuth: []
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >
        Use your secret API key as the username with an empty password.
        Base64-encode as {API_KEY}: and pass as Authorization: Basic {encoded}.
  parameters:
    orderToken:
      name: token
      in: path
      required: true
      description: Unique order token
      schema:
        type: string
    customerId:
      name: id
      in: path
      required: true
      description: Unique customer identifier
      schema:
        type: string
    productId:
      name: id
      in: path
      required: true
      description: Unique product identifier
      schema:
        type: string
    discountId:
      name: id
      in: path
      required: true
      description: Unique discount identifier
      schema:
        type: string
    refundId:
      name: id
      in: path
      required: true
      description: Unique refund identifier
      schema:
        type: string
    limit:
      name: limit
      in: query
      required: false
      description: Number of results to return per page
      schema:
        type: integer
        default: 25
    offset:
      name: offset
      in: query
      required: false
      description: Zero-based offset for pagination
      schema:
        type: integer
        default: 0
  schemas:
    Order:
      type: object
      properties:
        token:
          type: string
          description: Unique order token
        status:
          type: string
          description: Order status
          enum: [Processed, Disputed, Shipped, Delivered, Pending, Cancelled]
        paymentStatus:
          type: string
          description: Payment status
          enum: [Paid, Deferred, PaidDeferred, ChargedBack, Refunded, Paidout, Failed, Pending, Cancelled, Open]
        email:
          type: string
          format: email
          description: Customer email address
        total:
          type: number
          format: float
          description: Order total
        currency:
          type: string
          description: Currency code (ISO 4217)
        completionDate:
          type: string
          format: date-time
          description: Date and time the order was completed
        trackingNumber:
          type: string
          description: Shipment tracking number
        trackingUrl:
          type: string
          format: uri
          description: Shipment tracking URL
        items:
          type: array
          description: Items in the order
          items:
            $ref: '#/components/schemas/OrderItem'
    OrderItem:
      type: object
      properties:
        uniqueId:
          type: string
        id:
          type: string
        name:
          type: string
        price:
          type: number
          format: float
        quantity:
          type: integer
        url:
          type: string
          format: uri
    Customer:
      type: object
      properties:
        id:
          type: string
          description: Unique customer identifier
        email:
          type: string
          format: email
        billingAddressFirstName:
          type: string
        billingAddressLastName:
          type: string
        ordersCount:
          type: integer
          description: Number of orders placed by customer
        totalSpent:
          type: number
          format: float
          description: Total amount spent by customer
        status:
          type: string
          enum: [Confirmed, Unconfirmed]
        creationDate:
          type: string
          format: date-time
    Product:
      type: object
      properties:
        id:
          type: string
        userDefinedId:
          type: string
        name:
          type: string
        price:
          type: number
          format: float
        url:
          type: string
          format: uri
        description:
          type: string
        stock:
          type: integer
          description: Available stock quantity
        allowOutOfStockPurchases:
          type: boolean
        totalSales:
          type: integer
    Discount:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        code:
          type: string
          description: Discount code customers enter at checkout
        type:
          type: string
          enum: [FixedAmount, Rate, AlternatePrice, Shipping]
        amount:
          type: number
          format: float
        rate:
          type: number
          format: float
          description: Discount rate as percentage (0-100)
        maxNumberOfUsages:
          type: integer
        numberOfUsages:
          type: integer
        expirationDate:
          type: string
          format: date-time
    Notification:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum: [OrderStatusChanged, Invoice, TrackingNumber, Comment, Custom]
        deliveryMethod:
          type: string
          enum: [Email, None]
        message:
          type: string
        sentOn:
          type: string
          format: date-time
    Refund:
      type: object
      properties:
        id:
          type: string
        amount:
          type: number
          format: float
        comment:
          type: string
        refundedOn:
          type: string
          format: date-time
    AbandonedCart:
      type: object
      properties:
        token:
          type: string
        email:
          type: string
          format: email
        total:
          type: number
          format: float
        currency:
          type: string
        creationDate:
          type: string
          format: date-time
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
    UserSession:
      type: object
      properties:
        token:
          type: string
        user:
          type: object
          properties:
            email:
              type: string
              format: email
            billingAddressFirstName:
              type: string
            billingAddressLastName:
              type: string
    Domain:
      type: object
      properties:
        name:
          type: string
          description: Domain name
        protocol:
          type: string
          enum: [https, http]
    PaginatedResponse:
      type: object
      properties:
        totalItems:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
        items:
          type: array
          items:
            type: object
    Error:
      type: object
      properties:
        message:
          type: string
        details:
          type: array
          items:
            type: string
paths:
  /orders:
    get:
      summary: List all orders
      operationId: listOrders
      description: Retrieve all completed orders with optional filtering.
      tags: [Orders]
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - name: status
          in: query
          schema:
            type: string
            enum: [Processed, Disputed, Shipped, Delivered, Pending, Cancelled]
        - name: from
          in: query
          schema:
            type: string
            format: date-time
          description: Filter orders created on or after this date
        - name: to
          in: query
          schema:
            type: string
            format: date-time
          description: Filter orders created on or before this date
      responses:
        '200':
          description: Paginated list of orders
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/Order'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /orders/{token}:
    get:
      summary: Get order
      operationId: getOrder
      description: Retrieve a single order including all items, promo codes, and applied taxes.
      tags: [Orders]
      parameters:
        - $ref: '#/components/parameters/orderToken'
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update order
      operationId: updateOrder
      description: Update the status, payment status, tracking information, or metadata of a specific order.
      tags: [Orders]
      parameters:
        - $ref: '#/components/parameters/orderToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum: [Processed, Disputed, Shipped, Delivered, Pending, Cancelled]
                paymentStatus:
                  type: string
                  enum: [Paid, Deferred, PaidDeferred, ChargedBack, Refunded, Paidout, Failed, Pending, Cancelled, Open]
                trackingNumber:
                  type: string
                trackingUrl:
                  type: string
                  format: uri
                metadata:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: Updated order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /orders/{token}/digital:
    get:
      summary: Get digital goods for order
      operationId: getOrderDigitalGoods
      description: Return the list of digital goods attached to an order with download details and validity status.
      tags: [Orders]
      parameters:
        - $ref: '#/components/parameters/orderToken'
      responses:
        '200':
          description: List of digital goods
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    fileName:
                      type: string
                    url:
                      type: string
                      format: uri
                    expirationDate:
                      type: string
                      format: date-time
  /orders/{token}/notifications:
    get:
      summary: List order notifications
      operationId: listOrderNotifications
      description: Returns the list of notifications for a specific order.
      tags: [Notifications]
      parameters:
        - $ref: '#/components/parameters/orderToken'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: List of notifications
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Notification'
    post:
      summary: Create order notification
      operationId: createOrderNotification
      description: Creates a new notification on an order, optionally sending it via email.
      tags: [Notifications]
      parameters:
        - $ref: '#/components/parameters/orderToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum: [OrderStatusChanged, Invoice, TrackingNumber, Comment, Custom]
                deliveryMethod:
                  type: string
                  enum: [Email, None]
                message:
                  type: string
      responses:
        '200':
          description: Created notification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notification'
  /orders/{token}/refunds:
    get:
      summary: List order refunds
      operationId: listOrderRefunds
      description: Returns all refunds for a specific order.
      tags: [Refunds]
      parameters:
        - $ref: '#/components/parameters/orderToken'
      responses:
        '200':
          description: List of refunds
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Refund'
    post:
      summary: Create refund
      operationId: createRefund
      description: Creates a new refund for an order.
      tags: [Refunds]
      parameters:
        - $ref: '#/components/parameters/orderToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount]
              properties:
                amount:
                  type: number
                  format: float
                  description: Amount to refund
                comment:
                  type: string
                  description: Reason for refund
      responses:
        '200':
          description: Created refund
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
  /orders/{token}/refunds/{id}:
    get:
      summary: Get refund
      operationId: getRefund
      description: Returns a particular refund for a specific order.
      tags: [Refunds]
      parameters:
        - $ref: '#/components/parameters/orderToken'
        - $ref: '#/components/parameters/refundId'
      responses:
        '200':
          description: Refund details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
        '404':
          description: Refund not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /customers:
    get:
      summary: List customers
      operationId: listCustomers
      description: Returns the list of all your existing customers with optional filtering.
      tags: [Customers]
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - name: status
          in: query
          schema:
            type: string
            enum: [Confirmed, Unconfirmed]
        - name: email
          in: query
          schema:
            type: string
            format: email
        - name: from
          in: query
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Paginated list of customers
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/Customer'
  /customers/{id}:
    get:
      summary: Get customer
      operationId: getCustomer
      description: Retrieves information about a specific customer.
      tags: [Customers]
      parameters:
        - $ref: '#/components/parameters/customerId'
      responses:
        '200':
          description: Customer details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /customers/{id}/orders:
    get:
      summary: List customer orders
      operationId: listCustomerOrders
      description: Returns a list of orders associated with a particular customer.
      tags: [Customers]
      parameters:
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: List of customer orders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
  /products:
    get:
      summary: List products
      operationId: listProducts
      description: Returns a list of products with options to filter by date range and sort by sales metrics.
      tags: [Products]
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - name: from
          in: query
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Paginated list of products
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/Product'
    post:
      summary: Fetch and create product
      operationId: fetchProduct
      description: Fetches the URL passed in parameter and generates products found on the page (HTML buttons or JSON definitions).
      tags: [Products]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [fetchUrl]
              properties:
                fetchUrl:
                  type: string
                  format: uri
                  description: URL of page containing product definitions
      responses:
        '200':
          description: Created or updated product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
  /products/{id}:
    get:
      summary: Get product
      operationId: getProduct
      description: Retrieves a product by its identifier (Snipcart-generated or user-defined ID).
      tags: [Products]
      parameters:
        - $ref: '#/components/parameters/productId'
      responses:
        '200':
          description: Product details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update product
      operationId: updateProduct
      description: Updates specific product attributes, particularly inventory values such as stock levels.
      tags: [Products]
      parameters:
        - $ref: '#/components/parameters/productId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                stock:
                  type: integer
                allowOutOfStockPurchases:
                  type: boolean
      responses:
        '200':
          description: Updated product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
    delete:
      summary: Archive product
      operationId: archiveProduct
      description: Archives the product, removing it from listings. Automatically restored if added to a cart again.
      tags: [Products]
      parameters:
        - $ref: '#/components/parameters/productId'
      responses:
        '200':
          description: Product archived successfully
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /discounts:
    get:
      summary: List discounts
      operationId: listDiscounts
      description: Returns all discounts for your account.
      tags: [Discounts]
      responses:
        '200':
          description: List of discounts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Discount'
    post:
      summary: Create discount
      operationId: createDiscount
      description: Creates a new discount.
      tags: [Discounts]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, type]
              properties:
                name:
                  type: string
                code:
                  type: string
                type:
                  type: string
                  enum: [FixedAmount, Rate, AlternatePrice, Shipping]
                amount:
                  type: number
                  format: float
                rate:
                  type: number
                  format: float
                maxNumberOfUsages:
                  type: integer
                expirationDate:
                  type: string
                  format: date-time
      responses:
        '201':
          description: Created discount
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Discount'
  /discounts/{id}:
    get:
      summary: Get discount
      operationId: getDiscount
      description: Returns a particular discount.
      tags: [Discounts]
      parameters:
        - $ref: '#/components/parameters/discountId'
      responses:
        '200':
          description: Discount details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Discount'
        '404':
          description: Discount not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update discount
      operationId: updateDiscount
      description: Updates an existing discount.
      tags: [Discounts]
      parameters:
        - $ref: '#/components/parameters/discountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                code:
                  type: string
                amount:
                  type: number
                  format: float
                rate:
                  type: number
                  format: float
                maxNumberOfUsages:
                  type: integer
                expirationDate:
                  type: string
                  format: date-time
      responses:
        '200':
          description: Updated discount
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Discount'
    delete:
      summary: Delete discount
      operationId: deleteDiscount
      description: Deletes an existing discount. Discounts already used in completed orders cannot be deleted.
      tags: [Discounts]
      parameters:
        - $ref: '#/components/parameters/discountId'
      responses:
        '200':
          description: Discount deleted successfully
        '400':
          description: Cannot delete discount already used in completed orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /carts/abandoned:
    get:
      summary: List abandoned carts
      operationId: listAbandonedCarts
      description: Returns all abandoned carts with a paging limit of 25 and default offset of 0.
      tags: [AbandonedCarts]
      parameters:
        - $ref: '#/components/parameters/limit'
        - name: continuationToken
          in: query
          schema:
            type: string
          description: Token for fetching the next page of results
        - name: from
          in: query
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          schema:
            type: string
            format: date-time
        - name: minimalValue
          in: query
          schema:
            type: number
            format: float
          description: Minimum cart value filter
        - name: email
          in: query
          schema:
            type: string
            format: email
        - name: productId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: List of abandoned carts
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AbandonedCart'
                  continuationToken:
                    type: string
  /carts/abandoned/{token}:
    get:
      summary: Get abandoned cart
      operationId: getAbandonedCart
      description: Retrieves a specific abandoned cart by its unique token.
      tags: [AbandonedCarts]
      parameters:
        - name: token
          in: path
          required: true
          description: Unique abandoned cart token
          schema:
            type: string
      responses:
        '200':
          description: Abandoned cart details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AbandonedCart'
        '404':
          description: Abandoned cart not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /usersessions/{token}:
    get:
      summary: Get user session
      operationId: getUserSession
      description: Returns the session information along with the user details.
      tags: [UserSessions]
      parameters:
        - name: token
          in: path
          required: true
          description: Unique user session token
          schema:
            type: string
      responses:
        '200':
          description: User session details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSession'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /settings/domain:
    get:
      summary: Get default domain
      operationId: getDefaultDomain
      description: Retrieves your current default domain and its protocol configuration.
      tags: [Domains]
      responses:
        '200':
          description: Default domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
    put:
      summary: Update default domain
      operationId: updateDefaultDomain
      description: Updates your default domain with optional protocol specification.
      tags: [Domains]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
                protocol:
                  type: string
                  enum: [https, http]
      responses:
        '200':
          description: Updated domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
  /settings/alloweddomains:
    get:
      summary: List allowed domains
      operationId: listAllowedDomains
      description: Fetches a complete list of all permitted domains and subdomains (excluding the default domain).
      tags: [Domains]
      responses:
        '200':
          description: List of allowed domains
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Domain'
    post:
      summary: Add allowed domains
      operationId: addAllowedDomains
      description: Adds new domains or subdomains to your allowed list; returns the updated collection.
      tags: [Domains]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [domains]
              properties:
                domains:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Updated list of allowed domains
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Domain'
    delete:
      summary: Remove allowed domains
      operationId: removeAllowedDomains
      description: Removes specified domains or subdomains from your allowed list; returns remaining domains.
      tags: [Domains]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [domains]
              properties:
                domains:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Updated list of allowed domains after removal
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Domain'
tags:
  - name: Orders
    description: Manage orders and order lifecycle
  - name: Notifications
    description: Manage order notifications and emails
  - name: Refunds
    description: Manage order refunds
  - name: Customers
    description: View and manage customer data
  - name: Products
    description: Manage product catalog and inventory
  - name: Discounts
    description: Manage discount codes and promotions
  - name: AbandonedCarts
    description: View and track abandoned shopping carts
  - name: UserSessions
    description: Retrieve user session information
  - name: Domains
    description: Manage allowed domains for your store