Subscription Syncing

The entitlement information for your subscribers that is stored in Facebook's database can be retrieved and updated through a set of Graph API endpoints.

Authorization

Calls to the Subscription Syncing API must be authorized by supplying a valid access token. See Token Management for information on how to obtain and manage the correct access token.

Retrieving subscription nodes

Your subscription integration with Instant Articles is configured through a subscription node. This subscription node also serves as the endpoint for retrieving and modifying user subscriptions.

Production data and test data are isolated in two separate subscription nodes. You can view the IDs in the tooling by going to Publishing Tools -> Instant Articles -> Subscriptions -> Developer Tools.

Clicking the ID will copy it to your clipboard.

Retrieving existing user subscriptions

To retrieve existing user subscriptions, query the subscriptions edge of the subscription node in the following manner:

Request

GET /v2.10/{subscription-node-id}/subscriptions HTTP/1.1
Host: graph.facebook.com

Example Response

{
  "data": [
    {
      "expiry_time": "2017-10-08T18:22:04+0000",
      "publisher_user_id": "c85320d9ddb90c13f4a215f1f0a87b531ab33310",
      "is_active": false,
      "id": "1234567890112345678901"
    },
    {
      "expiry_time": "2017-10-13T20:52:11+0000",
      "publisher_user_id": "f572d396fae9206628714fb2ce00f72e94f2258f",
      "is_active": false,
      "id": "1234567890212345678902"
    },
    {
      "expiry_time": "2018-06-07T17:56:00+0000",
      "is_active": true,
      "user": {
        "name": "John Smith",
        "id": "1234567890412345678904"
      },
      "id": "1234567890312345678903"
    }
  ],
  "paging": {
    "cursors": {
      "before": "...",
      "after": "..."
    }
  }
}
    

Creating/Updating existing user subscriptions

The create and update user subscription endpoint accepts an array of user subscription objects. You can send one or more user subscriptions at any time.

The details surrounding the user subscription object are described below:

Request

POST /v2.10/{subscription-node-id}/subscriptions HTTP/1.1
Host: graph.facebook.com

Expected parameter: subscriptions

Example Parameters

{
  subscriptions: [{
    "user_id": "1234567890412345678904",
    "is_active": true,
    "expiry_time": "2018-06-07T17:55:00+00:00"
  },{
    "user_id": "1234567890412345678903",
    "is_active": false,
    "expiry_time": "2018-06-07T17:55:00+00:00"
  },{
    "user_id": "1234567890412345678901",
    "is_active": true,
    "expiry_time": "2018-06-07T17:55:00+00:00"
  }]
}
    
{
  subscriptions: [{
    "publisher_user_id": "7482",
    "is_active": true,
    "expiry_time": "2018-06-07T17:55:00+00:00"
  }]
}
    

The subscriptions parameter is a JSON object containing:

  • is_active (boolean): A boolean set to true if the subscription is active, false if inactive
  • expiry_time (string): The time at which the subscription transitions to inactive. This time is in ISO8601 format. To set an indefinite expiry, a value of -1 (string) can be provided.

When creating new user subscriptions the user_id field is required, for updating a subscription only one of the following is required:

  • user_id (string/integer): The Facebook app scoped ID of the user that is having their subscription created/updated
  • publisher_user_id (string): An ID that can uniquely identify the user (typically, the user ID in your database, but the key is entirely up to you)

The returned response is a JSON object containing:

  • success (boolean): Boolean value of whether the creation/update succeeded
  • user_subscription_ids (array): An array of IDs of the User Subscription Objects created or updated through the request.

Example Response

{
  "success": true,
  "user_subscription_ids": [
    "1001200005004"
  ]
}
    

Unexpected Payload Behavior

If both the user_id and publisher_user_id are specified, then the user_id takes precedence. This means that publisher_user_id would be modified in a request where user_id is specified and the value of publisher_user_id is also included.

The following examples illustrate this behavior in various scenarios:

Example 1. Updating the publisher user id

Current Subscriptions Status:

[{
  "user_id": 1,
  "publisher_user_id": "USER1",
  "is_active": false,
  "expiry_time": "2018-06-27T23:52:06+0000",
}, {
  "user_id": 2,
  "publisher_user_id": "USER2",
  "is_active": false,
  "expiry_time": "2018-06-27T23:52:06+0000",
}]
    

Update Payload:

{
  "user_id": 1,
  "publisher_user_id": "USER3",
  "is_active": true,
}
    

Resulting Status:

[{
  "user_id": 1,
  "publisher_user_id": "USER3",
  "is_active": true,
  "expiry_time": "2018-06-27T23:52:06+0000",
}, {
  "user_id": 2,
  "publisher_user_id": "USER2",
  "is_active": false,
  "expiry_time": "2018-06-27T23:52:06+0000",
}]
    

Example 2. Updating publisher user id, creating a duplicate

Current Subscriptions Status:

[{
  "user_id": 1,
  "publisher_user_id": "USER1",
  "is_active": false,
  "expiry_time": "2018-06-27T23:52:06+0000",
}, {
  "user_id": 2,
  "publisher_user_id": "USER2",
  "is_active": false,
  "expiry_time": "2018-06-27T23:52:06+0000",
}]
    

Update Payload:

{
  "user_id": 2,
  "publisher_user_id": "USER1",
  "is_active": true,
}
    

Resulting Status:

Error, USER1 already exists.
    

Example 3. Updating using only publisher user id

Current Subscriptions Status:

[{
  "user_id": 1,
  "publisher_user_id": "USER1",
  "is_active": false,
  "expiry_time": "2018-06-27T23:52:06+0000",
}, {
  "user_id": 2,
  "publisher_user_id": "USER2",
  "is_active": false,
  "expiry_time": "-1",
}]
    

Update Payload:

{
  "publisher_user_id": "USER1",
  "is_active": true,
}
    

Resulting Status:

[{
  "user_id": 1,
  "publisher_user_id": "USER1",
  "is_active": true,
  "expiry_time": "2018-06-27T23:52:06+0000",
}, {
  "user_id": 2,
  "publisher_user_id": "USER2",
  "is_active": false,
  "expiry_time": "-1",
}]
    

Example 4. Updating using only user id

Current Subscriptions Status:

[{
  "user_id": 1,
  "publisher_user_id": "USER1",
  "is_active": false,
  "expiry_time": "-1",
}, {
  "user_id": 2,
  "publisher_user_id": "USER2",
  "is_active": false,
  "expiry_time": "-1",
}]

    

Update Payload:

{
  "user_id": 2,
  "is_active": true,
}
    

Resulting Status:

[{
  "user_id": 1,
  "publisher_user_id": "USER1",
  "is_active": false,
  "expiry_time": "-1",
}, {
  "user_id": 2,
  "publisher_user_id": "USER2",
  "is_active": true,
  "expiry_time": "-1",
}]
    

An expiry time must be specified (exist within the user subscription). If no expiry time is specified, an error will occur. To set an indefinite expiry, a value of -1 (string) can be provided.

The is_active field and the expiry_time field must be in a valid state at all times. This means that if the is_active field is set to true, then the expiry_time must be set some time in the future (or to -1).

If multiple create/update records in a request have the same user ID, the last provided user subscription data of that ID will take precedence.