POST
Create a discount campaign
Company space For: Manager · Permission: discount_campaigns.create Conditions
  • The name, activation mode, discount type, tier basis, application scope, combination policy and start date are required. The access mode is public when left out.
  • A code is required when activation_mode is code and refused when it is automatic.
  • The code is stored in capitals and must be unique among the company’s campaigns.
  • ends_at must be after starts_at.
  • Dates without an offset are read in the company time zone and stored in UTC.
What else happens
  • The campaign is created in draft status, with the company currency and its exponent copied onto it and the member making the call recorded as creator. It has no tiers yet.
Part of Run discount campaigns.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

response
enum<string>
default:none

Response mode. Default none; none answers 204 No Content.

Available options:
none,
resource
fields
string

Comma-separated JSON keys of the root resource (id is always rendered). Available: id, name, description, activation_mode, code, status, discount_type, tier_basis, currency_code, currency_exponent, application_scope, access_mode, combination_policy, usage_limit, usage_pool_limit, usage_limit_per_customer, starts_at, ends_at, metadata, created_at, updated_at, stockable_units.

include
string

Comma-separated include paths, each optionally followed by its fields in parentheses: units(id,sku),units.uomUnit(id,name). Max depth 6, max 40 paths. Available: conditions, tiers.

Body

application/json
name
string
required

Name of the campaign, up to 255 characters. Required.

Maximum string length: 255
activation_mode
enum<string>
required

Required. automatic: applies by itself to eligible orders. code: applies only when the customer gives the campaign code.

Available options:
automatic,
code
discount_type
enum<string>
required

Required. percentage: tiers give a percentage. fixed: tiers give a fixed amount.

Available options:
percentage,
fixed
tier_basis
enum<string>
required

Required. order: tier minimums are compared with the whole order. eligible_stockables: they are compared with the targeted lines only.

Available options:
order,
eligible_stockables
application_scope
enum<string>
required

Required. order: the discount applies to the whole order. stockables: it applies only to chosen product units.

Available options:
order,
stockables
combination_policy
enum<string>
required

Required. exclusive or stackable, which decides whether the campaign can be combined with other campaigns.

Available options:
exclusive,
stackable
starts_at
string<date-time>
required

Start of eligibility, as a date and time. Required. A value without an offset is read in the company time zone.

description
string | null

Free-text description. Optional.

code
string | null

Code the customer gives, up to 64 characters, stored in capitals and unique within the company. Required when activation_mode is code; refused when it is automatic.

Maximum string length: 64
access_mode
enum<string> | null

public (everyone, the default when omitted) or restricted (only customers given access).

Available options:
public,
restricted
usage_limit
integer | null

Maximum number of orders that can use the campaign in total, at least 1. Null or omitted means no limit.

Required range: x >= 1
usage_pool_limit
integer | null

Maximum number of orders without a customer that can use the campaign, at least 1. Null or omitted means no limit.

Required range: x >= 1
usage_limit_per_customer
integer | null

Maximum number of orders per customer, at least 1. Null or omitted means no limit.

Required range: x >= 1
ends_at
string<date-time> | null

End of eligibility, as a date and time, after starts_at. Optional; omitted means no end date.

metadata
string[] | null

Free-form object stored with the campaign. Optional.

Response

Resource (only with response=resource).

id

Identifier of the campaign (27-character KSUID string).

name

Name of the campaign.

description

Free-text description, or null when none was given.

activation_mode

How the campaign starts to apply: automatic (to every eligible order) or code (only when the customer gives the campaign code). Cannot be changed after creation.

code

Code the customer gives, stored in capitals. Null for an automatic campaign.

status

Lifecycle status: draft (being set up, not applied), active (applied to orders), paused (temporarily not applied) or archived (retired, read-only). Changed only by the activate, pause, archive and draft actions.

discount_type

How the discount is computed: percentage (tiers give a percentage) or fixed (tiers give a fixed amount). Cannot be changed after creation.

tier_basis

Amount compared with the tier minimums: order (the whole order) or eligible_stockables (only the lines targeted by the campaign).

currency_code

Currency of the campaign amounts, copied from the company when the campaign was created.

currency_exponent
integer

Number of decimal places of the currency (0 for XOF). An amount in minor units divided by 10 to this power gives the amount in the currency.

application_scope

What the discount applies to: order (the whole order) or stockables (only the product units chosen for the campaign). Cannot be changed after creation.

access_mode

Who may use the campaign: public (everyone) or restricted (only customers given access). Cannot be changed after creation.

combination_policy

Whether the campaign can be combined with other campaigns: exclusive or stackable.

usage_limit
integer | null

Maximum number of orders that can use the campaign in total. Null means no limit.

usage_pool_limit
integer | null

Maximum number of orders without a customer that can use the campaign. Null means no limit.

usage_limit_per_customer
integer | null

Maximum number of orders each customer can use the campaign on. Null means no limit.

starts_at

Moment the campaign starts to be eligible, in ISO 8601 (UTC).

ends_at

Moment the campaign stops being eligible, in ISO 8601 (UTC). Null means no end date.

metadata
object | null

Free-form data stored with the campaign by the client, or null.

conditions
array

Conditions an order must meet for the campaign to apply. Returned only when selected with ?include=conditions.

tiers
array

Discount levels of the campaign, ordered by minimum amount. Returned only when selected with ?include=tiers.

stockable_units
any[]

Identifiers of the product units targeted by the campaign (27-character KSUID strings). Empty when application_scope is order, since targets can only be set on a stockables campaign.

created_at

Date and time the record was created (ISO 8601, UTC).

updated_at

Date and time the record was last changed (ISO 8601, UTC).