Memberful API

Memberful's API uses GraphQL, a flexible and powerful data query language. To learn more, see the the official GraphQL documentation.

In this help doc:

Using the GraphQL API Explorer

The GraphQL API Explorer serves as live, always up to date documentation. It also allows you to construct and test your queries and mutations.

Once you've added a Custom App under Settings → Integrate → Custom Apps, you can access our GraphQl API Explorer by clicking the Open API Explorer button for your app:

Access API explorer

Important: The GraphQL API Explorer makes use of your real, production data.

The GraphQL API Explorer comes with a built-in documentation explorer so you can learn about all the queries, mutations, and objects that are available in the API. To access this documentation, click the Docs button:

Access API documentation explorer

Once the panel is open, you can search for what you need by typing into the search box.

Search documentation explorer

You can then click on one of the results to learn more about the object, query, or mutation.

Documentation explorer for Members

Endpoint

The Memberful GraphQL API has a single endpoint:

https://YOURSITE.memberful.com/api/graphql

This endpoint always remains constant for all operations. All requests sent to the endpoint should be POST requests. The payload must contain a string called query with your query or mutation. If there are no errors, the endpoint will always return a JSON response.

Authentication

Each API request needs to include authorization header:

Authorization: Bearer <your-api-key>

To generate API keys, create a new Custom Application (Settings → Integrate → Custom Apps) from your Memberful dashboard.

Error handling

The GraphQL endpoint should always respond with a HTTP 200 status code. If there is a problem processing your request, the response payload will include details about the error.

Authentication error:

{
  "errors": [
    {
      "message": "Invalid authentication token."
    }
  ]
}

Invalid request error:

{
  "errors": [
    {
      "message": "Field 'memberCreate' is missing required arguments: email, fullName",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "fields": [
        "mutation",
        "createMember"
      ]
    }
  ]
}

Queries and Mutations

GraphQL supports both queries and mutations.

Example query:

query {
  member(id: 1) {
    id
    fullName
    email
    subscriptions {
      id
      plan {
        id
        name
      }
    }
  }
}

Response:

{
  "data": {
    "member": {
      "id": "1",
      "fullName": "John Doe",
      "email": "[email protected]",
      "subscriptions": [
        {
          "id": "1",
          "plan": {
            "id": "1",
            "name": "Monthly"
          }
        }
      ]
    }
  }
}

Example mutation:

mutation {
  memberCreate(email:"[email protected]", fullName:"John Doe") {
    member {
      id
      username
    }
  }
}

Response:

{
  "data": {
    "memberCreate": {
      "member": {
        "id": "1",
        "username": "john588361"
      }
    }
  }
}

Read more about queries and mutations.

Pagination

You'll use GraphQL connection types to detect paginated data.

Example query:

query {
  members(first: 2, after: "MTA=") {
    totalCount
    pageInfo {
      startCursor
      endCursor
      hasNextPage
      hasPreviousPage
    }
    edges {
      node {
        id
        email
      }
    }
  }
}

Example response:

{
  "data": {
    "members": {
      "totalCount": 100,
      "pageInfo": {
        "startCursor": "MTE=",
        "endCursor": "MjA=",
        "hasNextPage": true,
        "hasPreviousPage": true
      },
      "edges": [
        {
          "node": {
            "id": "11",
            "email": "[email protected]"
          }
        },
        {
          "node": {
            "id": "12",
            "email": "[email protected]"
          }
        }
      ]
    }
  }
}

Read more about GraphQL pagination.

Member metadata

The Memberful GraphQL API also supports storing custom metadata on each member. This data is not accessible elsewhere on the site, only via the API.

All metadata is set through a JSON object and limited to string values. A maximum of 50 keys can be stored on each member, with key lengths up to 40 characters and values up to 500 characters long.

Example mutation:

mutation {
  memberUpdate(id: 1, metadata: "{\"company\": \"Acme Corporation\"}") {
    member {
      id
      metadata
    }
  }
}

All metadata is additive, meaning if you don't add a specific key/value pair on a future update it will not delete that original value. You must explicitly delete a key by setting its value to an empty string.

Can't find what you're looking for? We'd love to help! 💪

Send us a message through the orange chat bubble in the lower right corner of the page. You'll hear back within a few hours Monday - Friday. 😀