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
• Endpoint
• Authentication
• Error handling
• Queries and Mutations
• Pagination

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 generate an API key, you can access it by clicking on the Open API Explorer link in custom applications list or custom application details page:

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. Use queries to pull your data from Memberful and mutations to modify your Memberful data.

Example query:

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

Response:

{
  "data": {
    "member": {
      "id": "1",
      "fullName": "John Doe",
      "email": "john.doe@example.com",
      "subscriptions": [
        {
          "id": "1",
          "plan": {
            "id": "1",
            "name": "Monthly"
          }
        }
      ]
    }
  }
}

Example mutation:

mutation {
  memberCreate(email:"john.doe@example.com", 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": "email11@example.com"
          }
        },
        {
          "node": {
            "id": "12",
            "email": "email12@example.com"
          }
        }
      ]
    }
  }
}

Read more about GraphQL pagination.