Memberful API

Memberful's API allows you to query Memberful for data about members, subscriptions, and much more. The API also offers 'mutations' to add, update, modify, or delete data.

The API uses GraphQL, a flexible and powerful data query language. This article will walk you through the basics of using the API and share some examples of queries you might use, along with example responses you can expect from our API.

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've added a Custom App under Settings → Custom applications, you can access our GraphQl API Explorer by clicking the Open API Explorer button for your app:

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 Show Documentation Explorer button:

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

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

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 parameter 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 an authorization header:

Authorization: Bearer <your-api-key>

To generate API keys, create a new Custom Application (Settings → Custom applications) 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.

Related help docs:

• Integrate with Zapier.
• Implement Memberful sign-in for apps via OAuth.
• Subscribe to Memberful's webhooks.
• Create coupons in bulk via API.