Notifications API

Notifications are records attached to an order — comments you want to keep on file, or messages emailed to the customer (invoices, tracking numbers, shipping updates, and so on). Use them to track changes to an order or to trigger customer-facing emails.

Requests are authenticated with your secret API key, sent as the HTTP Basic username with an empty password. With curl: -u {API_KEY}:. See Authentication for details. Every notification belongs to an order, identified by its GUID token.

The base URL is always https://app.snipcart.com/api.

Table of contents

GET /orders/{token}/notifications

Returns the list of notifications belonging to the order, most recent first.

Resource URL

GET https://app.snipcart.com/api/orders/{token}/notifications

Headers

Name Required Description
Accept Yes Must be application/json. The API only returns JSON.

Path Parameters

Name Required Type Description
token Yes guid The order token. Must be a valid GUID.

Query Parameters

Name Required Type Description
offset No integer Number of items to skip. Default is 0.
limit No integer Maximum number of items to return. Default is 20.

Example request 

curl "https://app.snipcart.com/api/orders/{token}/notifications?offset=0&limit=10" \
  -H "Accept: application/json" \
  -u {API_KEY}:

Example response 

{
  "totalItems": 3,
  "offset": 0,
  "limit": 10,
  "sort": [],
  "items": [
    {
      "id": "0c3ac0bb-a94a-45c5-a4d8-a7934a7f180a",
      "creationDate": "2017-07-09T14:59:57.987Z",
      "type": "Comment",
      "deliveryMethod": "None",
      "message": "Customer called to confirm shipping address."
    },
    {
      "id": "8a52d2c5-acbe-478d-8e96-06fbd6755efe",
      "creationDate": "2017-07-09T14:38:39.227Z",
      "type": "Comment",
      "deliveryMethod": "Email",
      "body": "Email HTML body will appear here...",
      "message": "Thanks for your order!",
      "subject": "Information regarding your order SNIP4962 on Snipcart.",
      "sentOn": "2017-07-09T14:38:39.947Z"
    },
    {
      "id": "e013a0d8-dbc2-45dc-85e5-900c0ce55da7",
      "creationDate": "2017-06-07T19:09:29Z",
      "type": "Invoice",
      "deliveryMethod": "Email",
      "body": "Invoice HTML will appear here...",
      "subject": "Order SNIP4962 on Snipcart",
      "sentOn": "2017-06-07T19:09:31.933Z"
    }
  ]
}

⚠️ Important: Fields are omitted from the response when they have no value. A private notification (for example a Comment with deliveryMethod of None) will not include subject, body, or sentOn. Only creationDate and type are always present.

POST /orders/{token}/notifications

Creates a new notification on the order. Depending on the type and deliveryMethod, the notification can either be emailed to the customer or kept private for internal use. The created notification is returned.

Resource URL

POST https://app.snipcart.com/api/orders/{token}/notifications

Headers

Name Required Description
Accept Yes Must be application/json.
Content-Type Yes Must be application/json. The request body is JSON.

Path Parameters

Name Required Type Description
token Yes guid The order token. Must be a valid GUID.

Body Parameters

Name Required Type Description
type Yes enum The type of notification. One of: Other, Invoice, Comment, TrackingNumber, OrderCancelled, Refund, OrderShipped, OrderReceived, OrderPaymentExpired, OrderStatusChanged, RecoveryCampaign, DigitalDownload, Logs, SubscriptionV3PaymentFailed, SubscriptionV3Cancelled, WithdrawalConfirmation, WithdrawalAccepted, WithdrawalDeclined. Use Comment to attach a free-form note (optionally emailed). See the delivery table below for which types produce an email.
deliveryMethod No enum How to deliver the notification. One of: None (private, no email), Email (sent to the customer), Bcc (used with Invoice to BCC the merchant). Defaults to None when omitted.
message No string The free-form message of the notification. Most relevant for Comment.
subject No string The email subject line. For email-producing types this is normally generated from a template, but you may supply your own.
body No string The notification body. For email-producing types the rendered HTML is filled in automatically on delivery.
refundId No guid Links the notification to an existing refund on the order (used with type of Refund).

Notification types and email delivery

deliveryMethod only triggers an actual email for the types below. Other types are recorded on the order but never emailed even if deliveryMethod is Email — the delivery service maps them to a no-op.

type Emailed when deliveryMethod is Email?
Comment Yes
Invoice Yes (also supports Bcc)
Refund Yes
TrackingNumber Yes
OrderShipped Yes
OrderReceived Yes
OrderPaymentExpired Yes
DigitalDownload Yes
SubscriptionV3PaymentFailed Yes
SubscriptionV3Cancelled Yes
WithdrawalConfirmation Yes
WithdrawalDeclined Yes
Other No (recorded only)
OrderCancelled No (recorded only)
OrderStatusChanged No (recorded only)
RecoveryCampaign No (recorded only)
Logs No (recorded only)
WithdrawalAccepted No (recorded only)

⚠️ Important: If email delivery fails, the notification is still saved on the order, but its deliveryMethod is reset to None and sentOn is left empty. Check the response to confirm the message was actually sent.

Example request 

curl https://app.snipcart.com/api/orders/{token}/notifications \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -u {API_KEY}: \
  -d '{"type": "Comment", "deliveryMethod": "Email", "message": "Thanks for your order!"}'

Example response 

{
  "id": "bff8418c-1ed2-4ba1-8b40-2a8bbf7dfadc",
  "creationDate": "2017-07-09T15:04:27.097Z",
  "type": "Comment",
  "deliveryMethod": "Email",
  "body": "The rendered email HTML will appear here...",
  "message": "Thanks for your order!",
  "subject": "Information regarding your order SNIP4962 on Snipcart.",
  "sentOn": "2017-07-09T15:04:27.490Z"
}

Was this article helpful?