Push API

Schedule & retrieve Tapcart push notifications from anywhere

Table of Contents

Authentication & Required Headers
Schedule a Segment Push
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`

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

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

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 — 201 Created

{
  "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"}`