comecerodocs
Notification subscriptions

Create a notification subscription

POST
/notification_subscriptions

Turns on one kind of customer email, such as the shipment confirmation. Send active: true, because a new subscription is inactive by default. Only one subscription per type may be active (409). A from address that is not verified is refused (422). Secret and trusted tokens may call it; a limited token may not (403).

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Request Body

application/json
  1. body

The fields you can set on a notification subscription. On create, type and method are required. On update, send only the fields to change.

type*notification_type

The kind of customer email. order:confirmation (receipt for a new order), payment:confirmation, refund:confirmation, shipment:confirmation, cart:link and invoice:link (a link to pay), customer:link (a link to the customer's account), subscription:prebill_notification (a renewal is coming), subscription:cancel_confirmation and subscription:payment_failure (a renewal payment failed).

Value in"order:confirmation""shipment:confirmation""payment:confirmation""refund:confirmation""cart:link""invoice:link""customer:link""subscription:prebill_notification""subscription:cancel_confirmation""subscription:payment_failure"
method*"email"

How to send. Only email.

Value in"email"
active?boolean

Whether the email is sent. On create the default is false. Only one subscription per type may be active (409).

Defaultfalse
from?|

A sender address. It must be on your list of verified notification addresses (Settings, General), or the request fails with 422.

Formatemail
from_name?|

The sender name.

Lengthlength <= 25
reply_to?|

The reply-to address.

Formatemail
bcc?|

Up to 4 addresses, comma-separated, for a blind copy.

subject?|

The subject line. It may hold placeholders such as {{order.order_id}}.

Lengthlength <= 75
template_id?|

The id of your template for the body. Leave it out or send null to use the built-in template.

comments?|

Your own notes.

Lengthlength <= 256

Response Body

The new notification subscription.

application/json
  1. response

Turns on one kind of customer email and sets who it comes from, its subject and its template. Only one subscription per type may be active.

object?"notification_subscription"

Always notification_subscription.

Value in"notification_subscription"
url?string

The URL of this notification subscription in the API.

Formaturi
notification_subscription_id?string

The notification subscription id.

date_created?string

When it was created.

Formatdate-time
date_modified?string

When it last changed.

Formatdate-time
test?boolean

true for a test mode subscription. It only sends test mode emails.

type?notification_type

The kind of customer email. order:confirmation (receipt for a new order), payment:confirmation, refund:confirmation, shipment:confirmation, cart:link and invoice:link (a link to pay), customer:link (a link to the customer's account), subscription:prebill_notification (a renewal is coming), subscription:cancel_confirmation and subscription:payment_failure (a renewal payment failed).

Value in"order:confirmation""shipment:confirmation""payment:confirmation""refund:confirmation""cart:link""invoice:link""customer:link""subscription:prebill_notification""subscription:cancel_confirmation""subscription:payment_failure"
active?boolean

Whether the email is sent. On create the default is false.

account_id?string

The account it belongs to.

method?"email"

How to send. Only email.

Value in"email"
from?|

The sender address, one of your verified notification addresses. When null, emails go from notification@comecero.com.

from_name?|

The sender name, at most 25 characters. When null, your public company name.

reply_to?|

The reply-to address. When null and emails go from Comecero's address, your support email is used.

bcc?|

Up to 4 addresses, comma-separated, that get a blind copy of every email.

subject?|

The subject line, at most 75 characters. It may hold placeholders such as {{order.order_id}}. When null, the template's default subject is used, then a built-in one.

template?||

Your template for the body: its URL, the full object with expand=template, or null to use Comecero's built-in template (in the customer's language where one exists). Left out when the token may not read templates.

comments?|

Your own notes, at most 256 characters.

formatted?

Dates as display text. Only returned with formatted=true.

curl -X POST 'https://api.comecero.com/api/v1/notification_subscriptions' \  -H 'Content-Type: application/json' \  -d '{  "type": "order:confirmation",  "method": "email",  "active": true}'
Example Response
{  "object": "notification_subscription",  "url": "https://api.comecero.com/api/v1/notification_subscriptions/1102500112233NSd4Kw9Tz",  "notification_subscription_id": "1102500112233NSd4Kw9Tz",  "date_created": "2026-10-01T09:00:00Z",  "date_modified": "2026-10-01T09:00:00Z",  "test": true,  "type": "shipment:confirmation",  "active": true,  "account_id": "AB1234",  "method": "email",  "from": null,  "from_name": "Example Shop",  "reply_to": "support@example.com",  "bcc": null,  "subject": "Your order {{order.order_id}} has shipped",  "template": null,  "comments": null}

List notification subscriptions GET

Lists your notification subscriptions: which customer emails are on, and how each is sent. The list is offset-based. Secret and trusted tokens may call it; a limited token may not (`403`).

Get a notification subscription GET

Gets one notification subscription. Secret and trusted tokens may call it; a limited token may not (`403`).