Snipcart Customers API

openapi: 3.2.0
info:
  title: Snipcart REST Customers 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: []
tags:
- name: Customers
  description: View and manage customer data
paths:
  /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'
components:
  parameters:
    customerId:
      name: id
      in: path
      required: true
      description: Unique customer 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:
    Error:
      type: object
      properties:
        message:
          type: string
        details:
          type: array
          items:
            type: string
    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
    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
    PaginatedResponse:
      type: object
      properties:
        totalItems:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
        items:
          type: array
          items:
            type: object
    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'
  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}.

        '