---
updatedAt: 2026-08-19T17:02:47.000Z
agentTools:
  projectIndex: https://dev.tapcart.com/llms.txt
---

# Push API

Schedule & retrieve Tapcart push notifications from anywhere

## Table of Contents

* [Authentication & Required Headers](#authentication--required-headers)
* [Schedule a Segment Push](#schedule-a-segment-push)
* [Errors](#errors)

***

## Authentication & Required Headers

These endpoints use API key authentication. Provide the API key assigned to the merchant app.

| Header         | Description                                                       | Required    |
| -------------- | ----------------------------------------------------------------- | ----------- |
| `api-key`      | The merchant API key.                                             | Yes         |
| `partner-name` | The partner name associated with the API key, such as `merchant`. | Yes         |
| `app-id`       | The Tapcart app ID.                                               | Recommended |
| `Content-Type` | Set to `application/json`.                                        | For `POST`  |

```text
api-key: <merchant-api-key>
partner-name: merchant
app-id: <tapcart-app-id>
Content-Type: application/json
```

> For the Schedule a Segment Push endpoint, `appId` is required in the JSON request body.

***

## Schedule a Segment Push

```http
POST https://api.tapcart.com/push/custom-segment
```

Creates a push campaign for an existing audience segment. Set `scheduled` to a future ISO 8601 timestamp to schedule delivery; omit it to begin processing immediately.

| Field                      | Type     | Required    | Description                                                                   |
| -------------------------- | -------- | ----------- | ----------------------------------------------------------------------------- |
| `appId`                    | `string` | Yes         | Tapcart app ID.                                                               |
| `message`                  | `string` | Yes         | Push notification body.                                                       |
| `destination`              | `string` | Yes         | App deep-link destination.                                                    |
| `customSegmentId`          | `string` | Yes         | ID of the segment to target.                                                  |
| `title`                    | `string` | Recommended | Push notification title.                                                      |
| `scheduled`                | `string` | No          | Future ISO 8601 delivery time, such as `2026-08-18T14:00:00.000Z`.            |
| `timezone`                 | `string` | No          | IANA timezone, such as `America/New_York`.                                    |
| `channel`                  | `string` | No          | `only_push`, `only_inbox`, or `both_push_and_inbox`. Defaults to `only_push`. |
| `destinationType`          | `string` | No          | Destination type. Defaults to `internal`.                                     |
| `attachment`               | `string` | No          | HTTPS URL for associated media.                                               |
| `inboxDisplayDurationDays` | `number` | No          | Number of days an inbox message remains visible.                              |

**Example request**

```bash
curl --request POST \
  --url "https://api.tapcart.com/push/custom-segment" \
  --header "api-key: <merchant-api-key>" \
  --header "partner-name: merchant" \
  --header "app-id: abc123" \
  --header "Content-Type: application/json" \
  --data '{
    "appId": "abc123",
    "title": "Weekend drop",
    "message": "20% off ends Sunday — tap to shop.",
    "destination": "/collections?id=477473997115",
    "destinationType": "internal",
    "customSegmentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "channel": "both_push_and_inbox",
    "scheduled": "2026-08-18T14:00:00.000Z",
    "timezone": "America/New_York",
    "inboxDisplayDurationDays": 30,
    "attachment": "https://cdn.example.com/weekend-drop.jpg"
  }'
```

**Example response —&#x20;**`201 Created`

```json
{
  "id": "Ab12Cd34Ef",
  "status": "processing"
}
```

> Identical push requests are deduplicated for 30 minutes. A duplicate request returns `409 Conflict`.

***

## Errors

| Status | Meaning                                                          | Example                                                                                     |
| ------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `400`  | Missing required parameter or authentication header.             | `{"status":"failed","message":"Missing partner-name or api-key header"}`                    |
| `401`  | Invalid API key, partner name, or app scope.                     | `{"status":401,"message":"Unauthorized."}`                                                  |
| `404`  | Requested segment does not exist for the app.                    | `{"status":"failed","message":"Segment not found"}`                                         |
| `409`  | Duplicate push request received within the deduplication window. | `{"status":"failed","message":"Duplicate push detected. Wait 30 minutes before retrying."}` |
| `422`  | Invalid request fields.                                          | `{"status":"failed","message":"Invalid request parameters"}`                                |
| `500`  | Unexpected error.                                                | `{"status":"failed","message":"An unexpected error occurred"}`                              |