> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.americanexpress.ferndocs.com/utilities/network-loyalty/api-reference/an-endpoint-to-subscribe-to-a-benefit-for-a-given-instrument/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.americanexpress.ferndocs.com/_mcp/server.

# An endpoint to subscribe to a benefit for a given instrument.

POST https://api.qa2s.americanexpress.com/loyalty/benefits/subscription
Content-Type: application/json

This endpoint will subscribe an instrument into the benefit identified by the given request parameters.

Reference: https://developer.americanexpress.ferndocs.com/utilities/network-loyalty/api-reference/an-endpoint-to-subscribe-to-a-benefit-for-a-given-instrument

## Authentication

- `X-AMEX-API-KEY` header (required) — Application API key issued during app registration.
- `Authorization` header (required) — HMAC (one-way TLS). A `MAC` authorization header signed with your client secret. See https://developer.americanexpress.com/documentation/api-security/hmac
- `Authorization` header (required) — HMAC over mutual TLS. Requires a client certificate in addition to the signed `MAC` authorization header.
- `Authorization` header (bearer token, required) — OAuth 2.0 client credentials. Exchange your API key and secret for a bearer token, then send it as `Authorization: Bearer <token>`.

## Servers

- `https://api.qa2s.americanexpress.com/loyalty` (Sandbox, default)
- `https://api.qa2s.americanexpress.com/loyalty/v1/network` (Sandbox, default)

## Request

### Headers

- `Authorization` (string, required) — The Authorization header for the authentication at APIGEE. The following should be in the format of this header:MAC id: The Partner's Client ID. The Client ID is generated during the Partner Onboarding and the App Registration.ts: A client-generated timestamp (Unix Epoch format in milli-seconds).nonce: A unique identifier string. The value of nonce must be unique for the each request.mac: The request mac is generated using the HMAC SHA256 algorithm. Use the Client Secret to generate a hash/signature. The Client ID and Client Secret is generated during the Partner Onboarding and App registration.e.g., MAC id="adc3af10-7bf6-4d8a-87ea-35519ff6e1ad",ts="1466548572491",nonce="be3bd46c-b052-4ae8-9f61-993635e5bc98",bodyhash="cRPVGQWU+89HNR0ASAJFjhKqDF9X0pApGYuC/NVQNEU=",mac="NqbqNO3vSBwk6EE7pBi11DzvgLCh50IPAICCIWgjxYA="
- `correlation_id` (string, required) — A unique identifier used to track the request. This is with the current debugging standard in mind to track the request end-to-end. This will be mainly passed by the originating server (if it's a Webapp) or empty in case of the direct browser/app calls.e.g., GUID.
- `sender` (string, required) — The sender contains the sender information.e.g., Issuer or Service Provider.
- `keyname` (string, required) — The value assigned to the key used to encrypt the payload. For HIPED operations, this value must start with 'MK'.e.g., AA3434342323.

### Body (application/json)

This endpoint expects a Benefit_Subscription.

- `network_info` (Network_Info, required) — An object containing the GNS-related information.
- `instrument_id` (string, required) — A unique ID for an instrument that is internal to the Issuer.e.g., GUID.
- `benefit_id` (string, optional) — A unique ID that is associated with the benefit. This field is only mandatory if the Issuer chooses not to use external_benefit_id.e.g., mock_benefit_id_001.
- `external_benefit` (External_Benefit, optional) — The reference to a benefit set up in an external system. If Issuer chooses to use benefit_id from R42 then this field is not required.e.g., A benefit from a GNS Issuer, such as the Express Company (EC).
- `program_account_id` (string, optional) — The Partner Account ID refers to the FFN.e.g., The Hilton Honors or the BA Executive Club number of the Customer.This is required to be sent by Network Loyalty GNS for the partners: Hilton, Radisson, Marriott.
- `demographic` (Benefit_demographics, optional) — This is required by Network Loyalty GNS. This contains all possible Customer data which can be sent by Network/Issuer to make a successful transfer.NOTE: All the fields that follow are optional, as any Partner may have different mandatory fields. Typically, the API checks mandatory parameters from a specific program_name and validates the mandatory fields.

## Response

### 202

Accepted the request for a subscription.

## Errors

### 400 Bad Request Error

Bad request.

- `error_code` (string, optional)
- `user_message` (string, optional) — An error occurred when processing your request.
- `developer_message` (string, optional) — A named\_exception was thrown by service\_method when performing processing\_task.

### 403 Forbidden Error

Forbidden request.

- `error_code` (string, optional)
- `user_message` (string, optional) — An error occurred when processing your request.
- `developer_message` (string, optional) — A named\_exception was thrown by service\_method when performing processing\_task.

### 404 Not Found Error

Not Found.

- `error_code` (string, optional)
- `user_message` (string, optional) — An error occurred when processing your request.
- `developer_message` (string, optional) — A named\_exception was thrown by service\_method when performing processing\_task.

### 409 Conflict Error

Conflict: Business error.

- `error_code` (string, optional)
- `user_message` (string, optional) — An error occurred when processing your request.
- `developer_message` (string, optional) — A named\_exception was thrown by service\_method when performing processing\_task.

### 500 Internal Server Error

Internal server error.

- `error_code` (string, optional)
- `user_message` (string, optional) — An error occurred when processing your request.
- `developer_message` (string, optional) — A named\_exception was thrown by service\_method when performing processing\_task.

## Types

### Network_Info

An object containing the GNS-related information.

- `institution_id` (string, required) — A unique ID which recognizes the Issuer.e.g., Bank_1, Bank_2.
- `network_id` (string, optional) — A unique ID which identifies the Issuer Network and will be provided, if required.e.g., Express_Company.

### External_Benefit

The reference to a benefit set up in an external system. If Issuer chooses to use benefit_id from R42 then this field is not required.e.g., A benefit from a GNS Issuer, such as the Express Company (EC).

- `id` (string, optional)
- `system` (string, optional)

### Benefit_demographics

This is required by Network Loyalty GNS. This contains all possible Customer data which can be sent by Network/Issuer to make a successful transfer.NOTE: All the fields that follow are optional, as any Partner may have different mandatory fields. Typically, the API checks mandatory parameters from a specific program_name and validates the mandatory fields.

- `TITLE` (string, optional) — This is required to be sent by Network Loyalty GNS for the Partner: Marriott.
- `FIRST_NAME` (string, optional) — This is required to be sent by Network Loyalty GNS for the partners: Marriott, Radisson.
- `MIDDLE_NAME` (string, optional)
- `LAST_NAME` (string, optional) — This is required to be sent by Network Loyalty GNS for the partners: Marriott, Radisson, Hilton.
- `DOB` (string, optional)
- `GENDER` (string, optional)
- `EMAIL` (string, optional) — This is required to be sent by Network Loyalty GNS for the partners: Marriott, Radisson.
- `LANGUAGE` (string, optional)
- `ADDR_LINE_1` (string, optional) — This is required to be sent by Network Loyalty GNS for the partners: Marriott, Radisson (Americas Only).
- `ADDR_LINE_2` (string, optional)
- `ADDR_LINE_3` (string, optional)
- `CITY` (string, optional) — This is required to be sent by Network Loyalty GNS for the partners: Marriott, Radisson (Americas Only).
- `STATE` (string, optional) — This is required to be sent by Network Loyalty GNS for the Partner: Marriott.
- `POSTAL_CODE` (string, optional)
- `COUNTRY` (string, optional) — This is required to be sent by Network Loyalty GNS for the partners: Marriott, Radisson.
- `TELEPHONE` (string, optional)

## Examples

**Request**

```json
{
  "network_info": {
    "institution_id": "string"
  },
  "instrument_id": "GUID"
}
```

**Response**

```json
{}
```

**SDK Code**

```python
import requests

url = "https://api.qa2s.americanexpress.com/loyalty/benefits/subscription"

payload = {
    "network_info": { "institution_id": "string" },
    "instrument_id": "GUID"
}
headers = {
    "Authorization": "Authorization",
    "correlation_id": "correlation_id",
    "keyname": "keyname",
    "sender": "sender",
    "X-AMEX-API-KEY": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.qa2s.americanexpress.com/loyalty/benefits/subscription';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Authorization',
    correlation_id: 'correlation_id',
    keyname: 'keyname',
    sender: 'sender',
    'X-AMEX-API-KEY': '<apiKey>',
    'Content-Type': 'application/json'
  },
  body: '{"network_info":{"institution_id":"string"},"instrument_id":"GUID"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.qa2s.americanexpress.com/loyalty/benefits/subscription"

	payload := strings.NewReader("{\n  \"network_info\": {\n    \"institution_id\": \"string\"\n  },\n  \"instrument_id\": \"GUID\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Authorization")
	req.Header.Add("correlation_id", "correlation_id")
	req.Header.Add("keyname", "keyname")
	req.Header.Add("sender", "sender")
	req.Header.Add("X-AMEX-API-KEY", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.qa2s.americanexpress.com/loyalty/benefits/subscription")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Authorization'
request["correlation_id"] = 'correlation_id'
request["keyname"] = 'keyname'
request["sender"] = 'sender'
request["X-AMEX-API-KEY"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"network_info\": {\n    \"institution_id\": \"string\"\n  },\n  \"instrument_id\": \"GUID\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.qa2s.americanexpress.com/loyalty/benefits/subscription")
  .header("Authorization", "Authorization")
  .header("correlation_id", "correlation_id")
  .header("keyname", "keyname")
  .header("sender", "sender")
  .header("X-AMEX-API-KEY", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"network_info\": {\n    \"institution_id\": \"string\"\n  },\n  \"instrument_id\": \"GUID\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.qa2s.americanexpress.com/loyalty/benefits/subscription', [
  'body' => '{
  "network_info": {
    "institution_id": "string"
  },
  "instrument_id": "GUID"
}',
  'headers' => [
    'Authorization' => 'Authorization',
    'Content-Type' => 'application/json',
    'X-AMEX-API-KEY' => '<apiKey>',
    'correlation_id' => 'correlation_id',
    'keyname' => 'keyname',
    'sender' => 'sender',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.qa2s.americanexpress.com/loyalty/benefits/subscription");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Authorization");
request.AddHeader("correlation_id", "correlation_id");
request.AddHeader("keyname", "keyname");
request.AddHeader("sender", "sender");
request.AddHeader("X-AMEX-API-KEY", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"network_info\": {\n    \"institution_id\": \"string\"\n  },\n  \"instrument_id\": \"GUID\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Authorization",
  "correlation_id": "correlation_id",
  "keyname": "keyname",
  "sender": "sender",
  "X-AMEX-API-KEY": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "network_info": ["institution_id": "string"],
  "instrument_id": "GUID"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.qa2s.americanexpress.com/loyalty/benefits/subscription")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```