Shopify Multipass API

openapi: 3.1.0
info:
  title: Shopify Multipass API
  description: >-
    Multipass login enables seamless single sign-on for Shopify Plus stores.
    It allows store owners who have a separate website and a Shopify store to
    redirect users from the external website and automatically log them into
    the Shopify store. Multipass tokens are generated server-side using AES
    encryption and HMAC signing with the store multipass secret, then passed
    to the Shopify login endpoint via URL. Tokens are valid for 15 minutes
    and can only be used once. Requires a Shopify Plus plan.
  version: '2025-01'
  contact:
    name: Shopify
    url: https://shopify.dev/docs/api/multipass
    email: [email protected]
  license:
    name: Shopify API Terms
    url: https://www.shopify.com/legal/api-terms
  x-date: '2026-03-04'
servers:
  - url: https://{store}.myshopify.com
    description: Shopify storefront
    variables:
      store:
        default: my-store
        description: The Shopify store subdomain
tags:
  - name: Multipass
    description: Single sign-on token-based authentication
paths:
  /account/login/multipass/{token}:
    get:
      operationId: multipassLogin
      summary: Shopify Log in a customer using a Multipass token
      description: >-
        Authenticates a customer using a Multipass token. The token is
        generated server-side by encrypting a JSON customer payload with
        AES-128-CBC and signing it with HMAC-SHA256 using keys derived
        from the store Multipass secret. The token is valid for 15 minutes
        and can only be used once. On success the customer is logged in and
        redirected to the return_to URL or the store homepage.
      tags:
        - Multipass
      parameters:
        - name: token
          in: path
          required: true
          description: >-
            The encrypted and signed Multipass token. Generated by encrypting
            a JSON payload containing at minimum an email address, then
            Base64 URL-encoding the result.
          schema:
            type: string
      responses:
        '302':
          description: >-
            Successful authentication. Redirects to the return_to URL
            specified in the token payload or the store homepage.
          headers:
            Location:
              description: The redirect destination URL
              schema:
                type: string
                format: uri
            Set-Cookie:
              description: Session cookie for the authenticated customer
              schema:
                type: string
        '401':
          description: >-
            Token is invalid, expired, or has already been used.
        '403':
          description: >-
            Multipass is not enabled for this store or the store is not
            on a Shopify Plus plan.
components:
  schemas:
    MultipassTokenPayload:
      type: object
      description: >-
        The JSON payload that is encrypted into a Multipass token. This
        payload is constructed server-side and never sent directly to
        Shopify as JSON. It is encrypted with AES-128-CBC and signed
        with HMAC-SHA256 before being URL-safe Base64 encoded.
      required:
        - email
        - created_at
      properties:
        email:
          type: string
          format: email
          description: >-
            The customer email address. Required. If no customer exists
            with this email one will be created automatically.
        created_at:
          type: string
          format: date-time
          description: >-
            ISO 8601 timestamp of when the token was created. Tokens
            are valid for 15 minutes from this timestamp.
        first_name:
          type: string
          description: Customer first name
        last_name:
          type: string
          description: Customer last name
        tag_string:
          type: string
          description: Comma-separated list of tags to apply to the customer
        identifier:
          type: string
          description: >-
            A unique identifier for the customer from the external system.
            If provided it is used instead of email to match customers.
        remote_ip:
          type: string
          description: >-
            The IP address of the customer. Used for fraud analysis.
        return_to:
          type: string
          format: uri
          description: >-
            The URL to redirect the customer to after login. Must be
            within the store domain. Defaults to the store homepage.
        addresses:
          type: array
          description: Customer addresses to set or update
          items:
            type: object
            properties:
              address1:
                type: string
              address2:
                type: string
              city:
                type: string
              company:
                type: string
              country:
                type: string
              first_name:
                type: string
              last_name:
                type: string
              phone:
                type: string
              province:
                type: string
              zip:
                type: string