Push payloads

A push carries more than a title and body. The data object rides alongside the alert, and your app reads it on arrival or tap. Put your fields in a data object on the message. One data object covers FCM, APNs, and Expo, so you describe the payload once. Send your push template with a data object using :

const { requestId } = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    routing: { method: 'all', channels: ['push'] },
    data: {
      order_id: 'ord_4821',
      screen: 'order-detail',
      carrier: 'UPS',
    },
  },
});

response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {"method": "all", "channels": ["push"]},
        "data": {
            "order_id": "ord_4821",
            "screen": "order-detail",
            "carrier": "UPS",
        },
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": { "method": "all", "channels": ["push"] },
      "data": {
        "order_id": "ord_4821",
        "screen": "order-detail",
        "carrier": "UPS"
      }
    }
  }'

response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: { method: "all", channels: ["push"] },
    data: {
      order_id: "ord_4821",
      screen: "order-detail",
      carrier: "UPS"
    }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Method:   string(shared.MessageRoutingMethodAll),
			Channels: []shared.MessageRoutingChannelUnionParam{{OfString: courier.String("push")}},
		},
		Data: map[string]any{
			"order_id": "ord_4821",
			"screen":  "order-detail",
			"carrier": "UPS",
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(JsonValue.from(java.util.Map.of(
            "method", "all",
            "channels", java.util.List.of("push"))))
        .data(JsonValue.from(java.util.Map.of(
            "order_id", "ord_4821",
            "screen", "order-detail",
            "carrier", "UPS")))
        .build())
    .build();
client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => ['method' => 'all', 'channels' => ['push']],
    'data' => [
      'order_id' => 'ord_4821',
      'screen' => 'order-detail',
      'carrier' => 'UPS',
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new Routing { Method = Method.All, Channels = ["push"] },
        Data = new Dictionary<string, JsonElement>()
        {
            { "order_id", JsonSerializer.SerializeToElement("ord_4821") },
            { "screen", JsonSerializer.SerializeToElement("order-detail") },
            { "carrier", JsonSerializer.SerializeToElement("UPS") },
        },
    },
};

await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","routing":{"method":"all","channels":["push"]},"data":{"order_id":"ord_4821","screen":"order-detail","carrier":"UPS"}}'

With Courier MCP, send the order-shipped push to user_123 with the order id and deep link in the data.

Older templates need a route for data.
New templates map data into the FCM and APNs payload by default, and a send with inline content needs no mapping at all. Having trouble getting your fields through on an older template? covers it. Expo forwards data either way.

Courier adds one key of its own to the same object, trackingUrl, for delivery and click tracking. Treat that name as reserved.

How the data arrives per provider

Each provider has its own payload rules, so the same data object lands in a different shape.

Where it lands	Nested values	Override key
The `data` block of the FCM message	Flattened to strings. An object or array becomes a JSON string.	`override.body.data`
The top level of the APNs payload, next to `aps`	Preserved as real JSON.	`override.body.payload`
The `data` field of the Expo push message	Preserved as real JSON.	`override` (merged at the top level)

FCM flattens everything to strings. FCM only accepts string values in data, so Courier converts anything else with JSON.stringify. Send { "nested": { "carrier": "UPS" } } and the device receives nested as the string {"carrier":"UPS"}, which your app has to parse. Numbers arrive as strings too: badgeCount: 3 arrives as "3". Expo forwards data on every send. The Expo handler copies the request’s data straight into the payload, so it arrives with no data mapping.

The same send, side by side

Sending this data object, with the template’s push channel mapping it through:

{
  "order_id": "ord_4821",
  "screen": "order-detail",
  "badgeCount": 3,
  "isPriority": true,
  "nested": {
    "carrier": "UPS",
    "eta": "2026-07-30"
  },
  "tags": ["shipped", "priority"]
}

produces two different payloads on the device:

{
  "aps": {
    "alert": { "title": "Order #4821 shipped", "body": "Arriving Thursday." },
    "sound": "ping.aiff",
    "mutable-content": 1
  },
  "order_id": "ord_4821",
  "screen": "order-detail",
  "badgeCount": 3,
  "isPriority": true,
  "nested": { "carrier": "UPS", "eta": "2026-07-30" },
  "tags": ["shipped", "priority"],
  "trackingUrl": "https://<tenant>.ct0.app/t/<token>"
}

{
  "title": "Order #4821 shipped",
  "body": "Arriving Thursday.",
  "order_id": "ord_4821",
  "screen": "order-detail",
  "badgeCount": "3",
  "isPriority": "true",
  "nested": "{\"carrier\":\"UPS\",\"eta\":\"2026-07-30\"}",
  "tags": "[\"shipped\",\"priority\"]",
  "trackingUrl": "https://<tenant>.ct0.app/t/<token>",
  "gcm.message_id": "1785281856917263",
  "google.c.sender.id": "313914309026"
}

On APNs your keys are siblings of aps and keep their JSON types. On FCM they live in the data block and are all strings. Both payloads reflect Courier’s default provider settings, tuned for the mobile SDKs:

FCM: Apply Recommended Courier Mobile SDK Formatting (remapData), on by default. It ships the message as data instead of notification, which improves delivery and lets you style the notification yourself. It also attaches an APNs override so iOS delivery tracking stays accurate. That is why title and body appear in the data block above. Turn it off and they arrive in a separate notification block.
APNs: Attach Mutable Content (mutableContent), on by default. It adds "mutable-content": 1, which lets a see the message before it reaches the user and record the delivery. Turn it off and messages still arrive, but delivery metrics get less accurate.

An iOS device receiving through FCM also gets the aps block and the google.c.* keys shown above. An Android device does not.

Flat, already-stringified data values avoid parsing on Android. One level of string keys and string values behaves identically on FCM, APNs, and Expo.

Read the data on the device

The Courier mobile SDKs hand you the full payload on delivery and on tap. Read your keys from it and route.

class AppDelegate: CourierDelegate {

    override func pushNotificationDeliveredInForeground(
        message: [AnyHashable: Any]
    ) -> UNNotificationPresentationOptions {
        let order_id = message["order_id"] as? String
        print("Delivered for order: \(order_id ?? "none")")
        return [.sound, .list, .banner, .badge]
    }

    override func pushNotificationClicked(message: [AnyHashable: Any]) {
        if let screen = message["screen"] as? String {
            router.navigate(to: screen)
        }
    }
}

class MainActivity : CourierActivity() {

    // The payload is a Map<String, String>: every FCM data value is a string
    override fun onPushNotificationClicked(pushNotification: Map<String, String>) {
        val screen = pushNotification["screen"]
        val order_id = pushNotification["order_id"]

        // A nested object arrives as a JSON string, so parse it
        val carrier = pushNotification["nested"]?.let { JSONObject(it).getString("carrier") }

        screen?.let { router.navigate(it) }
    }

    override fun onPushNotificationDelivered(pushNotification: Map<String, String>) {
        Log.d("Courier", "Delivered: $pushNotification")
    }
}

Courier.shared.addPushListener(
  onPushClicked: (push) {
    final screen = push['screen'];
    if (screen != null) {
      router.navigate(screen);
    }
  },
  onPushDelivered: (push) {
    debugPrint('Delivered: $push');
  },
);

Courier.shared.addPushNotificationListener({
  onPushNotificationClicked: (push) => {
    if (push.screen) {
      router.navigate(push.screen);
    }
  },
  onPushNotificationDelivered: (push) => {
    console.log("Delivered:", push);
  },
});

On iOS and Android the handler is a method on a class you already own, so it lives as long as your app does. Flutter and React Native return a listener instead, and it holds a reference until you drop it. Call remove() on teardown, such as inside Flutter’s dispose().

Deep-link on tap

Send the destination under your own key in data, then read it in your tap handler and route. The example at the top of this page uses screen. Any URL works there: a custom scheme like acme://orders/ord_4821, or a universal link like https://acme.com/orders/ord_4821. Universal links are set up on the platform, not in Courier. Courier carries the string, and the operating system decides whether it opens your app:

The tap handler is the one in Read the data on the device above.

Send data with no visible alert

A silent push shows the user nothing. Use it to move the app icon badge, or to wake your app in the background and sync. providers.apn.override.silent keeps the alert off the payload, so nothing appears on the lock screen. Pair it with badge and APNs moves the number itself, with no code running in your app:

const { requestId } = await client.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      apn: {
        override: {
          silent: true,
          body: {
            badge: 3,
          },
        },
      },
    },
  },
});

response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
            "apn": {
                "override": {
                    "silent": True,
                    "body": {
                        "badge": 3,
                    },
                },
            },
        },
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "providers": {
        "apn": {
          "override": {
            "silent": true,
            "body": {
              "badge": 3
            }
          }
        }
      }
    }
  }'

response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      apn: {
        override: {
          silent: true,
          body: {
            badge: 3
          }
        }
      }
    }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"apn": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"silent": true,
					"body": map[string]any{
						"badge": 3,
					},
				},
			},
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("apn", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "silent", true,
                    "body", java.util.Map.of("badge", 3)
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'providers' => [
      'apn' => [
        'override' => [
          'silent' => true,
          'body' => [
            'badge' => 3,
          ],
        ],
      ],
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "apn",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "silent": true,
                          "body": {
                            "badge": 3
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"apn": {"override": {"silent": true, "body": {"badge": 3}}}}'

With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 as a silent iOS push that sets the badge to 3.

To wake your app in the background as well, add "content-available": 1 to the same body. iOS then launches your app to handle the payload, which is what you want for syncing content before the user opens it. A badge on its own does not need it. On FCM, the message already ships as data with no notification block, because Apply Recommended Courier Mobile SDK Formatting (remapData) is on by default. Courier moves title, body, and image into the data block alongside your own keys. Your app reads all of it as data and decides what to display. If that setting is off on your integration, switch it back on for a single send:

const { requestId } = await client.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      "firebase-fcm": {
        override: {
          config: {
            remapData: true,
          },
        },
      },
    },
  },
});

response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
            "firebase-fcm": {
                "override": {
                    "config": {
                        "remapData": True,
                    },
                },
            },
        },
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "providers": {
        "firebase-fcm": {
          "override": {
            "config": {
              "remapData": true
            }
          }
        }
      }
    }
  }'

response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      "firebase-fcm": {
        override: {
          config: {
            remapData: true
          }
        }
      }
    }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"firebase-fcm": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"remapData": true,
					},
				},
			},
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("firebase-fcm", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of("remapData", true)
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'providers' => [
      'firebase-fcm' => [
        'override' => [
          'config' => [
            'remapData' => true,
          ],
        ],
      ],
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "firebase-fcm",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "remapData": true
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"firebase-fcm": {"override": {"config": {"remapData": true}}}}'

With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 with FCM data remapping turned on for this send.

Your app needs background delivery configured either way: Background Modes → Remote notifications on iOS, and a FirebaseMessagingService that handles onMessageReceived on Android.

Verify the payload

Send to a real device

Send the request above to a user_id with a registered token. Simulators do not receive push.

Confirm the payload on the device

Log the full message in your delivery or tap handler and check your keys are present. On Android, every value is a string.

Check the log if a key is missing

Open and open the message. The provider request shows the exact payload Courier sent, including the data block. Fields missing there were dropped by the send, not the device. The usual cause is a template send with no data mapping.

FAQ

Why is my data missing from the push payload?

Check the template’s age. New templates map data through by default, but one created before that default uses data for variable substitution only. shows how to turn it on, or set the fields in a . Expo forwards data either way.

Why did my number arrive as a string on Android?

FCM only permits string values in its data block, so Courier stringifies everything else. 3 becomes "3" and { "a": "b" } becomes "{\"a\":\"b\"}". Parse on the device, or send flat strings to begin with.

Can I send different data to iOS and Android?

Send the shared fields in the top-level data object, then add per-platform fields in each provider’s override (firebase-fcm under override.body.data, apn under override.body.payload).

Is there a size limit on the data payload?

The provider sets it, not Courier. APNs allows 4KB for a normal push, and FCM allows 4KB for the data block. The provider rejects anything over the limit and the message goes UNDELIVERABLE. Send IDs and let the app fetch the rest.

Which provider keys does Courier use for push?

firebase-fcm, apn, expo, onesignal, and pusher-beams. Use these keys to register a token and to override a provider on a send.

Get started

Send messages

Journeys

Broadcasts

Design

Recipients

Tenants

Monitoring

Workspaces

Resources

How the data arrives per provider

The same send, side by side

Read the data on the device

Deep-link on tap

Send data with no visible alert

Verify the payload

FAQ

​How the data arrives per provider

​The same send, side by side

​Read the data on the device

​Deep-link on tap

​Send data with no visible alert

​Verify the payload

​FAQ

How the data arrives per provider

The same send, side by side

Read the data on the device

Deep-link on tap

Send data with no visible alert

Verify the payload

FAQ