Shopify Customer Account API — Verde Tierra Tienda

Contexto del proyecto

Ecommerce de cosmética natural (Shopify + Hydrogen v2 / Remix + TypeScript). Se necesitan 6 operaciones GraphQL para el portal de cliente: pedidos, direcciones y perfil.

Todas las operaciones usan la Customer Account API (no el Admin API) y requieren el token de sesión del cliente autenticado via Shopify OIDC.

API Version2025-01

Endpointcustomer.myshopify.com/account/customer/api/2025-01/graphql

AuthBearer <customerAccessToken>

Operaciones6 (3 queries + 3 mutations)

📦

1 · Historial de pedidos

Últimos 5 pedidos con estado de pago, envío y seguimiento

customer.orders · docs ↗

query

GetCustomerOrders

Paginado cursor-based · last 5 · fulfilled + unfulfilled

GraphQL

Variables

Respuesta (ejemplo)

query GetCustomerOrders($cursor: String) {
  customer {
    orders(first: 5, after: $cursor, sortKey: PROCESSED_AT, reverse: true) {
      pageInfo {
        hasNextPage
        hasPreviousPage
        endCursor
        startCursor
      }
      edges {
        cursor
        node {
          id
          name                        # e.g. "#VT-1042"
          processedAt                 # ISO 8601
          financialStatus             # PAID | PENDING | REFUNDED …
          fulfillmentStatus           # FULFILLED | IN_PROGRESS …
          totalPrice {
            amount
            currencyCode
          }
          lineItems(first: 5) {
            edges {
              node {
                title
                quantity
                variant {
                  id
                  image {
                    url
                    altText
                    width
                    height
                  }
                }
              }
            }
          }
          fulfillments {
            trackingInformation {
              number
              url
              company
            }
          }
        }
      }
    }
  }
}

📍

2 · Gestión de direcciones

Listar, crear y eliminar direcciones de envío del cliente

customer.addresses · docs ↗

query

GetCustomerAddresses

Todas las direcciones — marca la predeterminada

query GetCustomerAddresses {
  customer {
    defaultAddress {
      id
    }
    addresses(first: 10) {
      edges {
        node {
          id
          name
          firstName
          lastName
          company
          address1
          address2
          city
          provinceCode
          countryCode
          zip
          phone
          formatted(withName: true)
        }
      }
    }
  }
}

mutation

CustomerAddressCreate

Nueva dirección

mutation CustomerAddressCreate(
  $address: CustomerAddressInput!
) {
  customerAddressCreate(
    address: $address
  ) {
    customerAddress {
      id
      formatted(
        withName: true
      )
    }
    userErrors {
      code
      field
      message
    }
  }
}

# Variables ejemplo:
# {
#   "address": {
#     "firstName": "María",
#     "lastName": "García",
#     "address1": "Calle Olivo 14, 3ºB",
#     "city": "Valencia",
#     "provinceCode": "VC",
#     "countryCode": "ES",
#     "zip": "46001",
#     "phone": "+34 960 000 000"
#   }
# }

mutation

CustomerAddressDelete

Eliminar por ID

mutation CustomerAddressDelete(
  $addressId: ID!
) {
  customerAddressDelete(
    addressId: $addressId
  ) {
    deletedAddressId
    userErrors {
      code
      field
      message
    }
  }
}

# Variables:
# {
#   "addressId":
#   "gid://shopify/MailingAddress/
#     8742630011231?model_name=
#     CustomerAddress"
# }

👤

3 · Actualización de perfil

Nombre, apellidos y email del cliente autenticado

customer.update · docs ↗

query

GetCustomerProfile

Datos básicos del perfil

query GetCustomerProfile {
  customer {
    id
    firstName
    lastName
    emailAddress {
      emailAddress
      marketingState
    }
    phoneNumber {
      phoneNumber
    }
    creationDate
    numberOfOrders
  }
}

mutation

CustomerUpdate

Actualizar nombre y email

mutation CustomerUpdate(
  $input: CustomerUpdateInput!
) {
  customerUpdate(input: $input) {
    customer {
      firstName
      lastName
      emailAddress {
        emailAddress
      }
    }
    userErrors {
      code
      field
      message
    }
  }
}

# Variables:
# {
#   "input": {
#     "firstName": "María",
#     "lastName": "López",
#     "email": "nueva@email.com"
#   }
# }

⚠️

Customer Account API ≠ Admin API: estas operaciones solo funcionan con el token OIDC del cliente autenticado. El endpoint es https://shopify.com/<shop-id>/account/customer/api/2025-01/graphql y requiere el header Authorization: Bearer <access_token>.

ℹ️

En Hydrogen v2 usa storefront.query() para Storefront API y customerAccount.query() / customerAccount.mutate() para estas operaciones de Customer Account. Los IDs de GID (gid://shopify/…) deben pasarse codificados en base64 al eliminar recursos.

📋

Referencia de tipos de entrada

CustomerAddressInput · CustomerUpdateInput

Campo	Tipo	Requerido	Notas
`firstName`	String		Nombre de pila del cliente
`lastName`	String		Apellidos
`address1`	String	✓ (address)	Línea principal de dirección
`address2`	String		Piso, puerta, etc.
`city`	String	✓	Ciudad
`provinceCode`	String		Código ISO de provincia (ES: "VC", "MD"…)
`countryCode`	CountryCode!	✓	ISO 3166-1 alpha-2 ("ES", "MX"…)
`zip`	String	✓ (ES)	Código postal 5 dígitos en España
`phone`	String		E.164 recomendado: +34 6XX XXX XXX
`email` (update)	String		Shopify enviará email de reconfirmación