Skip to content
Subrise
Install
Developer API
Docs

Customers

Get a customer's saved payment methods and subscriptions from Shopify, and email them a link to update a card, with the Subrise API.

Shopify stores your customers and their cards. These endpoints read what Shopify holds and ask Shopify to email the customer when a card needs updating. See Developer API for the base URL and authentication.

To find a customer's subscriptions in Subrise's records, search subscriptions with the customerId filter.

Get a customer's payment methods

text
GET /payment-methods

Needs Read permission. Returns the customer, their saved payment methods and their subscriptions, read live from Shopify.

Query parameterTypeDescription
customerIdstringRequired. The customer's numeric Shopify ID or Shopify global ID.
showRevokedbooleanOptional. true also returns payment methods that were revoked. Default false.
bash
curl "https://backend-production.subrise.app/api/payment-methods?customerId=7727997518103" \
  -H "x-api-key: $SUBRISE_API_KEY"

The response uses Shopify's GraphQL shape:

json
{
  "data": {
    "customer": {
      "id": "gid://shopify/Customer/7727997518103",
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "displayName": "John Doe",
      "state": "ENABLED",
      "subscriptionContracts": {
        "edges": [
          {
            "node": {
              "id": "gid://shopify/SubscriptionContract/12704383255",
              "status": "ACTIVE",
              "customerPaymentMethod": { "id": "gid://shopify/CustomerPaymentMethod/6fddc78b26624ee3ac6c1774ed278560" }
            }
          }
        ]
      },
      "paymentMethods": {
        "edges": [
          {
            "node": {
              "id": "gid://shopify/CustomerPaymentMethod/6fddc78b26624ee3ac6c1774ed278560",
              "revokedAt": null,
              "revokedReason": null,
              "instrument": {
                "__typename": "CustomerCreditCard",
                "brand": "VISA",
                "lastDigits": "4242",
                "maskedNumber": "•••• •••• •••• 4242",
                "expiryMonth": 2,
                "expiryYear": 2028,
                "expiresSoon": false,
                "isRevocable": true,
                "name": "John Doe"
              }
            }
          }
        ]
      }
    }
  }
}
  • The response lists up to 10 payment methods and up to 20 subscriptions.
  • instrument.__typename says what kind of payment method it is, such as CustomerCreditCard or CustomerPaypalBillingAgreement. Fields differ by type.
  • customerPaymentMethod.id on each subscription shows which card it charges.

Ask a customer to update a card

text
POST /payment-methods/{paymentMethodId}/update-email

Needs Write permission. Shopify emails the customer a secure link to update the card. Use it when a card has expired or a charge failed. The API can't change card details itself.

ParameterInTypeDescription
paymentMethodIdpathstringThe last part of the payment method's ID. For gid://shopify/CustomerPaymentMethod/6fddc78b26624ee3ac6c1774ed278560, send 6fddc78b26624ee3ac6c1774ed278560. A subscription's paymentMethodId field already has this form.
contractIdbodystringOptional. A subscription's numeric ID. Subrise then records the email in that subscription's activity log.

This endpoint also accepts the safe write headers when you send contractId.

bash
curl -X POST https://backend-production.subrise.app/api/payment-methods/6fddc78b26624ee3ac6c1774ed278560/update-email \
  -H "x-api-key: $SUBRISE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contractId": "12704383255" }'
json
{
  "success": true,
  "data": {
    "customerPaymentMethodSendUpdateEmail": {
      "customer": { "id": "gid://shopify/Customer/7727997518103" },
      "userErrors": []
    }
  }
}

If Shopify can't send the email, the response is 400 with "success": false, an error message and Shopify's userErrors. A contractId that isn't on your store returns 404.

Sections