comecerodocs
Promotions

Create a promotion

POST
/promotions

Creates a coupon, cross-sell or up-sell. A new promotion is inactive unless you send active: true. For a coupon with a generator_prefix, a generator_secret_key is made when you do not send one. Secret and trusted tokens may call it.

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Query Parameters

timezone?string

An IANA time zone name, such as America/New_York or UTC. It sets how date_start and date_end are read and the time zone of every date in the response. The default is the account's time zone (Settings, Technical), or UTC when it has none. A name that is not known is a 400.

show?string

Comma-separated fields to return; all others are left out. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.

hide?string

Comma-separated fields to leave out of the response. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.

formatted?boolean

When true, the object also has a formatted child with amounts and dates as display text in the shopper's language and currency (for example $19.99 or November 7, 2026). The default is false. See Localized formatting.

Defaultfalse

Request Body

The new promotion.

application/json
  1. body

The fields you can set on a promotion. On create, type and config are required. On update, send only the fields you want to change.

type*string

The kind of promotion. Required on create. Cannot be changed later.

Value in"coupon""cross_sell""up_sell"
name?|

Your name for the promotion.

Lengthlength <= 50
active?boolean

True to make the promotion usable. The default on create is false.

apply_to_recurring?boolean

True to also discount a subscription's later billings. Not allowed for order and shipping coupons. The default is false.

apply_to_recurring_count?|

How many later billings get the discount, 1 to 100. Send null to discount all of them. Only allowed when apply_to_recurring is true.

Range1 <= value <= 100
expires?|

When the promotion stops working, as an ISO 8601 date or date and time, read in the timezone you send. Must be in the future. Send null for never.

Formatdate-time
comments?|

Your notes.

Lengthlength <= 250
config*||

The rules for the promotion's type. Required on create. On update it replaces the old rules, except that a coupon's code and generator_prefix cannot change.

Response Body

The new promotion.

application/json
  1. response

A discount rule: a coupon shoppers enter, a cross-sell offered next to another product, or an up-sell offered in place of one. A limited token gets only object, url, promotion_id, apply_to_recurring and apply_to_recurring_count.

object*"promotion"

The object type. Always promotion.

Value in"promotion"
url*string

The URL of this promotion in the API.

Formaturi
promotion_id*string

The id of the promotion.

name?|

Your name for the promotion. Not returned to limited tokens.

test?boolean

True for a test-mode promotion. Not returned to limited tokens.

account_id?string

The account the promotion belongs to. Not returned to limited tokens.

date_created?string

When the promotion was created. Not returned to limited tokens.

Formatdate-time
date_modified?string

When the promotion was last changed. Not returned to limited tokens.

Formatdate-time
type?string

The kind of promotion. Not returned to limited tokens.

Value in"coupon""cross_sell""up_sell"
active?boolean

True when the promotion can be used. Not returned to limited tokens.

apply_to_recurring*boolean

True when the discount also applies to a subscription's later billings.

apply_to_recurring_count*|

How many later billings get the discount, or null for all of them. Only used when apply_to_recurring is true.

use_count?integer

How many times the promotion has been used. Not returned to limited tokens.

expires?|

When the promotion stops working, or null for never. Not returned to limited tokens.

Formatdate-time
comments?|

Your notes. Not returned to limited tokens.

config?||

The rules of the promotion, by type. Not returned to limited tokens.

formatted?

Present only when you send formatted=true.

curl -X POST 'https://api.comecero.com/api/v1/promotions' \  -H 'Content-Type: application/json' \  -d '{  "type": "coupon",  "name": "Ten percent off",  "active": true,  "expires": "2026-12-31T23:59:59Z",  "config": {    "type": "order",    "code": "SAVE10",    "discount_percent": 0.1,    "max_uses_per_customer": 1  }}'
Example Response
{  "object": "promotion",  "url": "https://api.comecero.com/api/v1/promotions/0070576784690PtKDqfI",  "promotion_id": "0070576784690PtKDqfI",  "name": "Ten percent off",  "test": true,  "account_id": "AB1234",  "date_created": "2026-11-02T20:13:16Z",  "date_modified": "2026-11-02T20:13:16Z",  "type": "coupon",  "active": true,  "apply_to_recurring": false,  "apply_to_recurring_count": null,  "use_count": 4,  "expires": "2026-12-31T23:59:59Z",  "comments": null,  "config": {    "type": "order",    "code": "SAVE10",    "generator_prefix": null,    "generator_secret_key": null,    "discount_percent": 0.1,    "discount_amount": null,    "product_ids": null,    "exclude_product_ids": false,    "max_uses_per_customer": 1,    "max_uses_global": null  }}

List promotions GET

Returns your coupons, cross-sells and up-sells, oldest first unless you choose another `sort_by`. Secret and trusted tokens may call it.

Get a promotion GET

Returns one promotion. A limited token gets only whether it applies to recurring billings, which a cart needs to tell the shopper. Secret, trusted and limited tokens may call it.