Squarespace Profiles API

openapi: 3.2.0
info:
  title: Squarespace Profiles API
  version: '1.0'
  description: 'Operations tagged Profiles across 2 of this provider''s published API definitions: squarespace-commerce-api-v2-openapi.json, squarespace-profiles-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.squarespace.com
  description: Commerce API
- url: https://api.squarespace.com/1.0
  description: Production Server
tags:
- name: Profiles
  x-zudoku-collapsed: true
paths:
  /1.0/profiles:
    get:
      description: Retrieves all profiles; profiles can be filtered and sorted. The response contains up to 50 Profiles and supports dynamic cursors for pagination.
      operationId: getProfiles
      parameters:
      - description: Identifies the sort direction of the result list; asc for ascending or dsc for descending. If not specified, the returned list is in descending order.
        in: query
        name: sortDirection
        required: false
        schema:
          type: string
      - description: 'Identifies the sort field of the result list. Values include: createdOn, id, email, or lastName. If not specified, the returned list is sorted by id.'
        in: query
        name: sortField
        required: false
        schema:
          type: string
      - description: 'Semicolon separated list used to filter profile results. Values include: isCustomer and/or hasAccount, or email. The email filter cannot be used with isCustomer or hasAccount.'
        in: query
        name: filter
        required: false
        schema:
          type: string
      - description: Email address filter (URL-encoded, case insensitive).
        in: query
        name: email
        required: false
        schema:
          type: string
      - description: Identifies where the next page of results should begin. Should be the value of pagination.nextPageCursor from a previous response. Cannot be used with other parameters.
        in: query
        name: cursor
        required: false
        schema:
          type: string
      - in: header
        name: Authorization
        required: true
        description: API key or OAuth access token
        schema:
          type: string
          default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
      - in: header
        name: User-Agent
        required: true
        description: User Agent
        schema:
          type: string
          default: YOUR_CUSTOM_APP_DESCRIPTION
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedProfileListResponse'
          description: A paginated list of profiles.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorPayload'
          description: Bad request.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorPayload'
          description: Not found. The API version is not supported.
      summary: List profiles
      tags:
      - Profiles
      security:
      - Authorization: []
    servers:
    - url: https://api.squarespace.com
      description: Commerce API
  /1.0/profiles/{profileIdCsvs}:
    get:
      description: Retrieves information for specific profiles. The response contains a list of up to 50 Profiles. Multiple Profiles can be retrieved by providing a comma-separated list of profile ids.
      operationId: getSpecificProfiles
      parameters:
      - description: Specifies the profiles to retrieve. Multiple Profiles can be retrieved by providing a comma-separated list of profile ids.
        in: path
        name: profileIdCsvs
        required: true
        schema:
          type: string
      - in: header
        name: Authorization
        required: true
        description: API key or OAuth access token
        schema:
          type: string
          default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
      - in: header
        name: User-Agent
        required: true
        description: User Agent
        schema:
          type: string
          default: YOUR_CUSTOM_APP_DESCRIPTION
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileListResponse'
          description: The requested profiles.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorPayload'
          description: Bad request. ids specifies greater than 50 profiles.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorPayload'
          description: Not found. One or more profiles were not found.
      summary: Get profiles
      tags:
      - Profiles
      security:
      - Authorization: []
    servers:
    - url: https://api.squarespace.com
      description: Commerce API
  /profiles:
    servers:
    - url: https://api.squarespace.com/1.0
      description: Production Server
    get:
      operationId: listProfiles
      summary: Retrieve All Profiles
      description: Returns a paginated list of profiles associated with the merchant site. Profiles represent customers, mailing list subscribers, and donors. By default returns up to 50 profiles per page. Results can be filtered by profile type, account status, or email address. Use the cursor parameter from the previous response's pagination.nextPageCursor to iterate through all profiles.
      tags:
      - Profiles
      parameters:
      - $ref: '#/components/parameters/cursor'
      - name: isCustomer
        in: query
        description: When true, filters results to only include customer profiles
        required: false
        schema:
          type: boolean
      - name: hasAccount
        in: query
        description: When true, filters to profiles associated with a Squarespace account. When false, filters to anonymous profiles.
        required: false
        schema:
          type: boolean
      - name: email
        in: query
        description: Filter profiles by exact email address match
        required: false
        schema:
          type: string
          format: email
      responses:
        '200':
          description: Successful response with paginated list of profiles
          content:
            application/json:
              schema:
                type: object
                properties:
                  profiles:
                    type: array
                    items:
                      $ref: '#/components/schemas/Profile_2'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - bearerAuth: []
  /profiles/{profileIds}:
    servers:
    - url: https://api.squarespace.com/1.0
      description: Production Server
    get:
      operationId: getProfilesByProfileIds
      summary: Retrieve Specific Profiles
      description: Retrieves profile information for one or more specific profiles by their profile IDs. Profile IDs can be provided as a comma-separated list in the path. The order of profiles in the response is not guaranteed to match the order of IDs provided.
      tags:
      - Profiles
      parameters:
      - $ref: '#/components/parameters/profileIds'
      responses:
        '200':
          description: Successful response with the requested profiles
          content:
            application/json:
              schema:
                type: object
                properties:
                  profiles:
                    type: array
                    items:
                      $ref: '#/components/schemas/Profile_2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - bearerAuth: []
      x-operation-id-source: normalized
      x-operation-id-original: getProfiles
components:
  schemas:
    TransactionsSummary:
      type: object
      properties:
        donationCount:
          type: integer
          description: Count of donations submitted.
          format: int32
        firstDonationSubmittedOn:
          type: string
          description: ISO 8601 UTC date and time string; represents when the profile's first donation was submitted.
          format: date-time
        firstOrderSubmittedOn:
          type: string
          description: ISO 8601 UTC date and time string; represents when the profile's first order was submitted.
          format: date-time
        lastDonationSubmittedOn:
          type: string
          description: ISO 8601 UTC date and time string; represents when the profile's latest donation was submitted.
          format: date-time
        lastOrderSubmittedOn:
          type: string
          description: ISO 8601 UTC date and time string; represents when the profile's latest order was submitted.
          format: date-time
        orderCount:
          type: integer
          description: Count of orders submitted.
          format: int32
        totalDonationAmount:
          $ref: '#/components/schemas/MonetaryAmount'
        totalOrderAmount:
          $ref: '#/components/schemas/MonetaryAmount'
        totalRefundAmount:
          $ref: '#/components/schemas/MonetaryAmount'
      description: Summary of profile's commerce transactions. If a profile has no commerce transactions, the object is still returned with null or 0 values. This information is calculated asynchronously; there may be a slight delay between when an order is created, and when it's reflected in the object.
    MonetaryAmount:
      type: object
      properties:
        currency:
          type: object
          description: ISO 4217 currency code.
          properties:
            currencyCode:
              type: string
            defaultFractionDigits:
              type: integer
              format: int32
            displayName:
              type: string
            numericCode:
              type: integer
              format: int32
            numericCodeAsString:
              type: string
            symbol:
              type: string
          examples:
          - USD
        value:
          type: number
          description: Decimal monetary value.
          examples:
          - 49.99
      description: A monetary amount with currency code and decimal value.
    ProfileListResponse:
      type: object
      properties:
        profiles:
          type: array
          items:
            $ref: '#/components/schemas/Profile'
    Address:
      type: object
      properties:
        address1:
          type: string
          description: Primary street address
          examples:
          - 459 Broadway
        address2:
          type: string
          description: Secondary address line
        city:
          type: string
          description: City
          examples:
          - New York
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 country code
          examples:
          - US
        firstName:
          type: string
          description: First name
          examples:
          - Bob
        lastName:
          type: string
          description: Last name
          examples:
          - Loblaw
        phone:
          type: string
          description: Phone number
          examples:
          - '5553334444'
        postalCode:
          type: string
          description: Postal or ZIP code
          examples:
          - '10003'
        state:
          type: string
          description: State or province
          examples:
          - NY
      description: Customer's shipping address provided at checkout or, for recurring subscription orders, the customer's current mailing address.
    Profile:
      type: object
      properties:
        acceptsMarketing:
          type: boolean
          description: Indicates whether the profile opted to receive marketing.
        address:
          $ref: '#/components/schemas/Address'
        createdOn:
          type: string
          description: ISO 8601 UTC date and time string; represents when the profile was created.
          format: date-time
        email:
          type: string
          description: Profile email address.
        firstName:
          type: string
          description: Profile first name.
        hasAccount:
          type: boolean
          description: Indicates whether the profile has an account with the website.
        id:
          type: string
          description: Unique Profile id.
        isCustomer:
          type: boolean
          description: Indicates whether the profile has any commerce orders or donations with the website.
        lastName:
          type: string
          description: Profile last name.
        transactionsSummary:
          $ref: '#/components/schemas/TransactionsSummary'
    StandardErrorPayload:
      type: object
      properties:
        contextId:
          type: string
        details:
          type: object
        message:
          type: string
        subtype:
          type: string
          enum:
          - MISSING_ARGUMENT
          - INVALID_ARGUMENT
          - INVALID_CONTENT_TYPE
          - CONCURRENT_MODIFICATION
          - INSUFFICIENT_STOCK
          - STOCK_NOT_TRACKED
          - STOCK_EXCEEDS_MAX
          - CURRENCY_MISMATCH
          - MEASUREMENT_STANDARD_MISMATCH
          - INSUFFICIENT_PRODUCT_VARIANTS
          - URL_SLUG_UNAVAILABLE
          - SKU_UNAVAILABLE
          - STORE_PAGE_NOT_FOUND
          - STORE_PAGE_PRODUCT_LIMIT_REACHED
          - IMAGE_LIMIT_REACHED
          - WEBHOOK_SUBSCRIPTION_LIMIT_REACHED
          - MISSING_SCOPE
          - PROFILE_CANNOT_ACCEPT_MARKETING
          - ENTITY_LIMIT_REACHED
          - PRODUCT_UPDATE_CONFLICT
          - DUPLICATE_USER_CONFLICT
          - PROMO_CODE_CONFLICT
          - INVENTORY_ITEM_NOT_FOUND
          - PRODUCT_IMAGE_NOT_FOUND
          - PRODUCT_VARIANT_NOT_FOUND
          - OAUTH_TOKEN_REQUIRED
          - FORBIDDEN_RESOURCE
          - OPERATION_NOT_ALLOWED_FOR_PRODUCT_TYPE
        type:
          type: string
          enum:
          - INVALID_REQUEST_ERROR
          - AUTHORIZATION_ERROR
          - WEBSITE_EXPIRED
          - METHOD_NOT_ALLOWED
          - CONFLICT
          - TOO_MANY_REQUESTS
          - SERVER_ERROR
          - SERVICE_UNAVAILABLE
    PaginatedProfileListResponse:
      type: object
      properties:
        pagination:
          examples:
          - hasNextPage: true
            nextPageCursor: ewogICJhIiA6ICI2OWNhOWExZjgxNGMwYTY0MmIwMTIzYzkiLAogICJiIiA6ICJJRCIKfQ
            nextPageUrl: /1.0/profiles?cursor=ewogICJhIiA6ICI2OWNhOWExZjgxNGMwYTY0MmIwMTIzYzkiLAogICJiIiA6ICJJRCIKfQ
          type: object
          properties:
            hasNextPage:
              type: boolean
            nextPageCursor:
              type: string
            nextPageUrl:
              type: string
        profiles:
          type: array
          items:
            $ref: '#/components/schemas/Profile'
    Profile_2:
      type: object
      description: A profile representing a customer, mailing list subscriber, or donor associated with the Squarespace site
      properties:
        id:
          type: string
          description: Unique identifier for the profile
        firstName:
          type: string
          description: First name of the profile holder
        lastName:
          type: string
          description: Last name of the profile holder
        email:
          type: string
          format: email
          description: Email address associated with the profile
        hasAccount:
          type: boolean
          description: Whether the profile is linked to a Squarespace account
        isCustomer:
          type: boolean
          description: Whether the profile has placed at least one order
        address:
          $ref: '#/components/schemas/ApproximateAddress'
        commerceStats:
          $ref: '#/components/schemas/CommerceStats'
        createdOn:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp when the profile was created
        modifiedOn:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp when the profile was last modified
    CommerceStats:
      type: object
      description: A summary of the profile holder's commerce activity on the site
      properties:
        orderCount:
          type: integer
          description: Total number of orders placed by this profile
          minimum: 0
        orderTotal:
          $ref: '#/components/schemas/Money'
        donationCount:
          type: integer
          description: Total number of donations made by this profile
          minimum: 0
        donationTotal:
          $ref: '#/components/schemas/Money'
        firstOrderOn:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp of the profile's first order
        lastOrderOn:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp of the profile's most recent order
    ApproximateAddress:
      type: object
      description: An approximate address derived from the profile's order history and account information, not necessarily verified
      properties:
        city:
          type: string
          description: City associated with the profile
        state:
          type: string
          description: State or region associated with the profile
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 country code
          pattern: ^[A-Z]{2}$
        postalCode:
          type: string
          description: Postal or ZIP code associated with the profile
    Error:
      type: object
      description: Standard error response returned by the Squarespace API
      properties:
        type:
          type: string
          description: Machine-readable error type identifier
        subtype:
          type: string
          description: Optional more specific error subtype
        message:
          type: string
          description: Human-readable description of the error
        statusCode:
          type: integer
          description: HTTP status code associated with the error
    Pagination:
      type: object
      description: Pagination metadata included with list responses
      properties:
        hasNextPage:
          type: boolean
          description: Indicates whether additional pages of results are available
        nextPageCursor:
          type: string
          description: Cursor value to pass in the next request to retrieve the next page
        nextPageUrl:
          type: string
          format: uri
          description: Full URL for retrieving the next page of results
    Money:
      type: object
      description: A monetary value with currency
      properties:
        value:
          type: string
          description: Decimal string representation of the monetary amount
          pattern: ^-?\d+(\.\d+)?$
        currency:
          type: string
          description: ISO 4217 three-letter currency code
          pattern: ^[A-Z]{3}$
  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The authenticated user does not have permission to access this resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was malformed or contained invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    profileIds:
      name: profileIds
      in: path
      description: Comma-separated list of profile IDs to retrieve
      required: true
      schema:
        type: string
    cursor:
      name: cursor
      in: query
      description: Pagination cursor from a previous response's pagination.nextPageCursor field. Omit or leave empty to retrieve the first page.
      required: false
      schema:
        type: string
  securitySchemes:
    Authorization:
      in: header
      scheme: bearer
      type: http
    bearerAuth:
      type: http
      scheme: bearer
      description: Authenticate using an API key or OAuth access token. Include the token in the Authorization header as "Bearer YOUR_TOKEN".
externalDocs:
  description: Squarespace Commerce API Documentation
  url: https://developers.squarespace.com/commerce-apis/overview
x-refined-from:
- squarespace-commerce-api-v2-openapi.json
- squarespace-profiles-api-openapi.yml