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
• Member metadata

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. We allow up to 100 queries per minute 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.

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.