Discounts
List discounts
Credential: a company's API key or OAuth token.
Retrieves a paginated list of your company's discounts, each with its amounts per currency and its assignments, ordered by priority (lowest first), then name.
Pass ?active=true or ?active=false, ?type= and ?scope= to narrow
the list; total counts the filtered set.
Required Scope
products-read
query Parameters
pagePage number (1-indexed)
limitMaximum number of items per page
activetrue lists active discounts only, false inactive ones only. Omitted: both.
typeOnly discounts of this type.
scopeOnly discounts of this scope.
List discounts › Responses
Paginated list of discounts for the company
Page of discounts, ordered by priority (lowest first), then name.
totalTotal number of matching discounts
pageCurrent page number
limitItems per page
totalPagesTotal number of pages
Create a discount
Credential: a company's API key or OAuth token.
Creates a discount. A percentage discount states percentagePct; a
fixed or per_unit discount states one positive amount per currency in
amounts, and is never converted between currencies. The type cannot change
after creation. A per_unit discount takes line scope only; document
scope is refused with DISCOUNT_PER_UNIT_NEEDS_LINE_SCOPE.
A new discount has no assignments, so it applies nowhere until one is added
with POST /v1/discounts/{discountId}/assignments.
A discount is applied only to a document line or a document that references its id. Creating, changing or assigning a discount changes no document on its own.
Required Scope
products-write
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Create a discount › Request Body
namePrinted as the reason on the e-invoice allowance.
typepercentage takes a percent off; fixed takes an amount off, per eligible line for a line discount or once per document for a document discount; per_unit takes an amount off each unit on a line and takes line scope only. The type cannot change after the discount is created.
scopeline applies to each eligible line on its own. document applies once per document, after every line discount, when the customer matches and at least one line has an eligible product. A per_unit discount with document scope is refused with DISCOUNT_PER_UNIT_NEEDS_LINE_SCOPE.
percentagePctRequired for a percentage discount, refused for other types: the percent off, above 0 and at most 100, with at most 4 decimals. Outside that range: DISCOUNT_INVALID_PERCENTAGE.
priorityThe order the server applies discounts in when it picks them itself; lowest first. Defaults to 0.
combinableFalse: a line may not reference this discount together with another one. Defaults to true.
activeAn inactive discount applies nowhere. Defaults to true.
requiresCodeTrue: the discount applies only through one of its codes. A document or an applicability check that names it by its id alone is refused with the reason codeRequired, and GET /v1/discounts/applicable leaves it out. Defaults to false.
maxRedemptionsTotal uses allowed. Null or omitted: no limit.
maxPerCustomerUses allowed per customer. Null or omitted: no limit.
durationInPeriodsHow many billing periods the discount lasts on a subscription that references it. Null or omitted: for as long as the reference stands.
Fixed and per-unit discounts only: one positive amount per currency, each currency at most once. Amounts are never converted between currencies. Refused on a percentage discount.
Create a discount › Responses
Discount created
idThe discount ID.
namePrinted as the reason on the e-invoice allowance.
typepercentage takes a percent off; fixed takes an amount off, per eligible line for a line discount or once per document for a document discount; per_unit takes an amount off each unit on a line and takes line scope only. The type cannot change after the discount is created.
scopeline applies to each eligible line on its own. document applies once per document, after every line discount, when the customer matches and at least one line has an eligible product. A per_unit discount with document scope is refused with DISCOUNT_PER_UNIT_NEEDS_LINE_SCOPE.
percentagePctPercentage discounts only: the percent taken off, above 0 and at most 100. Null for other types.
priorityThe order the server applies discounts in when it picks them itself; lowest first.
combinableFalse: a line may not reference this discount together with another one.
activeAn inactive discount applies nowhere.
requiresCodeTrue: the discount applies only through one of its codes. A document or an applicability check that names it by its id alone is refused with the reason codeRequired, and GET /v1/discounts/applicable leaves it out.
maxRedemptionsTotal uses allowed. Null: no limit.
maxPerCustomerUses allowed per customer. Null: no limit.
durationInPeriodsHow many billing periods the discount lasts on a subscription that references it. Null: for as long as the reference stands.
Fixed and per-unit discounts: one positive amount per currency, sorted by currency. Empty for a percentage discount. A discount is applied only to a document line or document that references its id; creating or assigning it changes no document on its own.
Where the discount applies: each assignment names a product, a customer and a window of days, any of them null for "all". A discount with no assignment applies nowhere.
Get a discount
Credential: a company's API key or OAuth token.
Returns a discount with its amounts per currency and its assignments.
Required Scope
products-read
path Parameters
discountIdDiscount ID
Get a discount › Responses
Discount details
idThe discount ID.
namePrinted as the reason on the e-invoice allowance.
typepercentage takes a percent off; fixed takes an amount off, per eligible line for a line discount or once per document for a document discount; per_unit takes an amount off each unit on a line and takes line scope only. The type cannot change after the discount is created.
scopeline applies to each eligible line on its own. document applies once per document, after every line discount, when the customer matches and at least one line has an eligible product. A per_unit discount with document scope is refused with DISCOUNT_PER_UNIT_NEEDS_LINE_SCOPE.
percentagePctPercentage discounts only: the percent taken off, above 0 and at most 100. Null for other types.
priorityThe order the server applies discounts in when it picks them itself; lowest first.
combinableFalse: a line may not reference this discount together with another one.
activeAn inactive discount applies nowhere.
requiresCodeTrue: the discount applies only through one of its codes. A document or an applicability check that names it by its id alone is refused with the reason codeRequired, and GET /v1/discounts/applicable leaves it out.
maxRedemptionsTotal uses allowed. Null: no limit.
maxPerCustomerUses allowed per customer. Null: no limit.
durationInPeriodsHow many billing periods the discount lasts on a subscription that references it. Null: for as long as the reference stands.
Fixed and per-unit discounts: one positive amount per currency, sorted by currency. Empty for a percentage discount. A discount is applied only to a document line or document that references its id; creating or assigning it changes no document on its own.
Where the discount applies: each assignment names a product, a customer and a window of days, any of them null for "all". A discount with no assignment applies nowhere.
Delete a discount
Credential: a company's API key or OAuth token.
Deletes a discount with its amounts and assignments. A discount a document or
a redemption already records is refused with DISCOUNT_IN_USE; deactivate it
with active: false instead.
Required Scope
products-write
path Parameters
discountIdDiscount ID
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Delete a discount › Responses
Discount deleted
Update a discount
Credential: a company's API key or OAuth token.
Updates a discount. Only the fields provided are changed; maxRedemptions or
maxPerCustomer sent as null removes that limit, and any other field sent as
null is refused with 400. The type cannot change:
a different type is refused with DISCOUNT_TYPE_IMMUTABLE. A per_unit
discount cannot move to document scope (DISCOUNT_PER_UNIT_NEEDS_LINE_SCOPE).
The edit is saved and the response's warnings carries
DISCOUNT_IN_USE_ON_OPEN_DOCUMENTS when open quotes, order confirmations or
invoice drafts reference the discount: total counts them and documents
lists the newest 50 of those your key may read (quotes-read,
order-confirmations-read, invoices-read). A sent quote or order confirmation keeps its discount
figures until it is converted; an invoice draft takes the new value the next
time it is saved. warnings is empty when nothing is open.
An edit that changes what the discount takes off or where it applies (percent,
scope, active, combinable, requiresCode) gives that warning; a rename or a change to
priority or limits gives none.
A subscription freezes a discount's terms for each billing period. An edit that
changes what the discount takes off for a subscription that references it
(percent, the amount in its currency, scope, combinable) is refused with
409 DISCOUNT_IN_USE_ON_SUBSCRIPTIONS and nothing is saved, unless the
request accepts applyToSubscriptions. Then each such subscription takes
the new terms from its next billing period, as a new version, and
subscriptionChanges lists them with that date. A period already running
keeps the old terms. The refusal's details.total counts the subscriptions;
details.subscriptions lists them, and subscriptionChanges gives their
name and customerName, only to a key with subscriptions-read.
Accepting needs subscriptions-write as well: without it,
applyToSubscriptions is ignored and the edit is refused.
Required Scope
products-write
path Parameters
discountIdDiscount ID
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Update a discount › Request Body
namePrinted as the reason on the e-invoice allowance.
typeAccepted only when it equals the current type. The type cannot change after creation: a different value is refused with DISCOUNT_TYPE_IMMUTABLE.
scopeline applies to each eligible line on its own. document applies once per document, after every line discount, when the customer matches and at least one line has an eligible product. A per_unit discount with document scope is refused with DISCOUNT_PER_UNIT_NEEDS_LINE_SCOPE.
percentagePctPercentage discounts only: above 0 and at most 100, with at most 4 decimals. Outside that range: DISCOUNT_INVALID_PERCENTAGE.
priorityThe order the server applies discounts in when it picks them itself.
combinableFalse: a line may not reference this discount together with another one.
activeAn inactive discount applies nowhere.
requiresCodeTrue: the discount applies only through one of its codes. A document or an applicability check that names it by its id alone is refused with the reason codeRequired, and GET /v1/discounts/applicable leaves it out.
maxRedemptionsNull removes the limit.
maxPerCustomerNull removes the limit.
durationInPeriodsNull: lasts for as long as a subscription references it.
applyToSubscriptionsTrue accepts moving the subscriptions that reference the discount onto the edited terms: each takes them from its next billing period, as a new version. Omitted or false: an edit that changes what the discount takes off (percent, amount, scope, combinable) while subscriptions reference it is refused with DISCOUNT_IN_USE_ON_SUBSCRIPTIONS and nothing is saved.
Update a discount › Responses
Discount updated
idThe discount ID.
namePrinted as the reason on the e-invoice allowance.
typepercentage takes a percent off; fixed takes an amount off, per eligible line for a line discount or once per document for a document discount; per_unit takes an amount off each unit on a line and takes line scope only. The type cannot change after the discount is created.
scopeline applies to each eligible line on its own. document applies once per document, after every line discount, when the customer matches and at least one line has an eligible product. A per_unit discount with document scope is refused with DISCOUNT_PER_UNIT_NEEDS_LINE_SCOPE.
percentagePctPercentage discounts only: the percent taken off, above 0 and at most 100. Null for other types.
priorityThe order the server applies discounts in when it picks them itself; lowest first.
combinableFalse: a line may not reference this discount together with another one.
activeAn inactive discount applies nowhere.
requiresCodeTrue: the discount applies only through one of its codes. A document or an applicability check that names it by its id alone is refused with the reason codeRequired, and GET /v1/discounts/applicable leaves it out.
maxRedemptionsTotal uses allowed. Null: no limit.
maxPerCustomerUses allowed per customer. Null: no limit.
durationInPeriodsHow many billing periods the discount lasts on a subscription that references it. Null: for as long as the reference stands.
Fixed and per-unit discounts: one positive amount per currency, sorted by currency. Empty for a percentage discount. A discount is applied only to a document line or document that references its id; creating or assigning it changes no document on its own.
Where the discount applies: each assignment names a product, a customer and a window of days, any of them null for "all". A discount with no assignment applies nowhere.
Warnings about the edit, empty when there is nothing to warn about. DISCOUNT_IN_USE_ON_OPEN_DOCUMENTS lists the open quotes (not converted, rejected or expired), order confirmations (not converted) and invoice drafts that reference the discount. The edit is saved either way. A sent quote or order confirmation keeps its discount figures until it is converted; an invoice draft takes the new value the next time it is saved. Given when the edit changed what the discount takes off or where it applies (percent, amounts, scope, active, combinable, requiresCode); a rename or a change to priority or limits gives none.
With applyToSubscriptions: true, the subscriptions whose terms the edit changed: each takes the new terms from its next billing period. Empty otherwise.
Set a discount's amount in one currency
Credential: a company's API key or OAuth token.
Sets a fixed or per-unit discount's amount in the path's currency, adding it
or replacing the amount already there. The amount is positive and applies to
documents in that currency only. Refused on a percentage discount with
DISCOUNT_AMOUNT_NOT_ALLOWED.
The edit is saved and the response's warnings carries
DISCOUNT_IN_USE_ON_OPEN_DOCUMENTS when open quotes, order confirmations or
invoice drafts reference the discount: total counts them and documents
lists the newest 50 of those your key may read (quotes-read,
order-confirmations-read, invoices-read). A sent quote or order confirmation keeps its discount
figures until it is converted; an invoice draft takes the new value the next
time it is saved. warnings is empty when nothing is open.
Restating the amount already stored gives no warning.
A subscription freezes a discount's terms for each billing period. An edit that
changes what the discount takes off for a subscription that references it
(percent, the amount in its currency, scope, combinable) is refused with
409 DISCOUNT_IN_USE_ON_SUBSCRIPTIONS and nothing is saved, unless the
request accepts applyToSubscriptions. Then each such subscription takes
the new terms from its next billing period, as a new version, and
subscriptionChanges lists them with that date. A period already running
keeps the old terms. The refusal's details.total counts the subscriptions;
details.subscriptions lists them, and subscriptionChanges gives their
name and customerName, only to a key with subscriptions-read.
Accepting needs subscriptions-write as well: without it,
applyToSubscriptions is ignored and the edit is refused.
Required Scope
products-write
path Parameters
discountIdDiscount ID
currencyISO 4217 alpha-3 currency code
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Set a discount's amount in one currency › Request Body
amountThe amount in the path's currency. What the discount takes off in this currency, in major units, as a positive decimal string. Each currency carries its own amount: a document in a currency the discount has no amount for is refused, never converted at an exchange rate.
applyToSubscriptionsTrue accepts moving the subscriptions that reference the discount onto the edited terms: each takes them from its next billing period, as a new version. Omitted or false: an edit that changes what the discount takes off (percent, amount, scope, combinable) while subscriptions reference it is refused with DISCOUNT_IN_USE_ON_SUBSCRIPTIONS and nothing is saved.
Set a discount's amount in one currency › Responses
The discount with its amounts
idThe discount ID.
namePrinted as the reason on the e-invoice allowance.
typepercentage takes a percent off; fixed takes an amount off, per eligible line for a line discount or once per document for a document discount; per_unit takes an amount off each unit on a line and takes line scope only. The type cannot change after the discount is created.
scopeline applies to each eligible line on its own. document applies once per document, after every line discount, when the customer matches and at least one line has an eligible product. A per_unit discount with document scope is refused with DISCOUNT_PER_UNIT_NEEDS_LINE_SCOPE.
percentagePctPercentage discounts only: the percent taken off, above 0 and at most 100. Null for other types.
priorityThe order the server applies discounts in when it picks them itself; lowest first.
combinableFalse: a line may not reference this discount together with another one.
activeAn inactive discount applies nowhere.
requiresCodeTrue: the discount applies only through one of its codes. A document or an applicability check that names it by its id alone is refused with the reason codeRequired, and GET /v1/discounts/applicable leaves it out.
maxRedemptionsTotal uses allowed. Null: no limit.
maxPerCustomerUses allowed per customer. Null: no limit.
durationInPeriodsHow many billing periods the discount lasts on a subscription that references it. Null: for as long as the reference stands.
Fixed and per-unit discounts: one positive amount per currency, sorted by currency. Empty for a percentage discount. A discount is applied only to a document line or document that references its id; creating or assigning it changes no document on its own.
Where the discount applies: each assignment names a product, a customer and a window of days, any of them null for "all". A discount with no assignment applies nowhere.
Warnings about the edit, empty when there is nothing to warn about. DISCOUNT_IN_USE_ON_OPEN_DOCUMENTS lists the open quotes (not converted, rejected or expired), order confirmations (not converted) and invoice drafts that reference the discount. The edit is saved either way. A sent quote or order confirmation keeps its discount figures until it is converted; an invoice draft takes the new value the next time it is saved. Given when the edit changed what the discount takes off or where it applies (percent, amounts, scope, active, combinable, requiresCode); a rename or a change to priority or limits gives none.
With applyToSubscriptions: true, the subscriptions whose terms the edit changed: each takes the new terms from its next billing period. Empty otherwise.
Remove a discount's amount in one currency
Credential: a company's API key or OAuth token.
Removes the amount in the path's currency. A document in that currency that
references the discount is then refused with DISCOUNT_NO_AMOUNT_IN_CURRENCY.
The edit is saved and the response's warnings carries
DISCOUNT_IN_USE_ON_OPEN_DOCUMENTS when open quotes, order confirmations or
invoice drafts reference the discount: total counts them and documents
lists the newest 50 of those your key may read (quotes-read,
order-confirmations-read, invoices-read). A sent quote or order confirmation keeps its discount
figures until it is converted; an invoice draft takes the new value the next
time it is saved. warnings is empty when nothing is open.
A subscription freezes a discount's terms for each billing period. An edit that
changes what the discount takes off for a subscription that references it
(percent, the amount in its currency, scope, combinable) is refused with
409 DISCOUNT_IN_USE_ON_SUBSCRIPTIONS and nothing is saved, unless the
request accepts applyToSubscriptions. Then each such subscription takes
the new terms from its next billing period, as a new version, and
subscriptionChanges lists them with that date. A period already running
keeps the old terms. The refusal's details.total counts the subscriptions;
details.subscriptions lists them, and subscriptionChanges gives their
name and customerName, only to a key with subscriptions-read.
Accepting needs subscriptions-write as well: without it,
applyToSubscriptions is ignored and the edit is refused.
Required Scope
products-write
path Parameters
discountIdDiscount ID
currencyISO 4217 alpha-3 currency code
query Parameters
applyToSubscriptionsTrue accepts moving the subscriptions that reference the discount onto the edited terms: each takes them from its next billing period, as a new version. Omitted or false: an edit that changes what the discount takes off (percent, amount, scope, combinable) while subscriptions reference it is refused with DISCOUNT_IN_USE_ON_SUBSCRIPTIONS and nothing is saved.
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Remove a discount's amount in one currency › Responses
The discount with its remaining amounts
idThe discount ID.
namePrinted as the reason on the e-invoice allowance.
typepercentage takes a percent off; fixed takes an amount off, per eligible line for a line discount or once per document for a document discount; per_unit takes an amount off each unit on a line and takes line scope only. The type cannot change after the discount is created.
scopeline applies to each eligible line on its own. document applies once per document, after every line discount, when the customer matches and at least one line has an eligible product. A per_unit discount with document scope is refused with DISCOUNT_PER_UNIT_NEEDS_LINE_SCOPE.
percentagePctPercentage discounts only: the percent taken off, above 0 and at most 100. Null for other types.
priorityThe order the server applies discounts in when it picks them itself; lowest first.
combinableFalse: a line may not reference this discount together with another one.
activeAn inactive discount applies nowhere.
requiresCodeTrue: the discount applies only through one of its codes. A document or an applicability check that names it by its id alone is refused with the reason codeRequired, and GET /v1/discounts/applicable leaves it out.
maxRedemptionsTotal uses allowed. Null: no limit.
maxPerCustomerUses allowed per customer. Null: no limit.
durationInPeriodsHow many billing periods the discount lasts on a subscription that references it. Null: for as long as the reference stands.
Fixed and per-unit discounts: one positive amount per currency, sorted by currency. Empty for a percentage discount. A discount is applied only to a document line or document that references its id; creating or assigning it changes no document on its own.
Where the discount applies: each assignment names a product, a customer and a window of days, any of them null for "all". A discount with no assignment applies nowhere.
Warnings about the edit, empty when there is nothing to warn about. DISCOUNT_IN_USE_ON_OPEN_DOCUMENTS lists the open quotes (not converted, rejected or expired), order confirmations (not converted) and invoice drafts that reference the discount. The edit is saved either way. A sent quote or order confirmation keeps its discount figures until it is converted; an invoice draft takes the new value the next time it is saved. Given when the edit changed what the discount takes off or where it applies (percent, amounts, scope, active, combinable, requiresCode); a rename or a change to priority or limits gives none.
With applyToSubscriptions: true, the subscriptions whose terms the edit changed: each takes the new terms from its next billing period. Empty otherwise.
Check whether a discount applies to a product for a customer on a day
Credential: a company's API key or OAuth token.
Answers whether this discount applies, and when it does not, the first check
that failed, in this order: unknown, inactive, codeRequired,
notAssigned or notInGroup, outsideWindow, maxRedemptionsReached,
maxPerCustomerReached. notInGroup means an assignment would match if the
product or the customer were in the group it names.
A discount of another company answers unknown.
remaining and remainingForCustomer are the uses left under
maxRedemptions and maxPerCustomer, null when the discount has no such
limit. Asking holds no use: a booking that would pass a limit is still refused.
Required Scope
products-read
path Parameters
discountIdDiscount ID
query Parameters
customerIdThe customer the document is for.
productIdThe line's product.
asOfThe calendar day to judge on (YYYY-MM-DD), normally the document's date. An assignment covers it when startsAt ≤ asOf ≤ endsAt, both ends inclusive.
Check whether a discount applies to a product for a customer on a day › Responses
Whether the discount applies
applicableWhether the discount applies to this customer and product on this day.
reasonNull when it applies. Otherwise the first check that failed: unknown (no such discount in your company), inactive, codeRequired (the discount applies only through a code), notAssigned (no assignment names this product and customer, or all), notInGroup (an assignment would match, but the product or the customer is not in the group it targets), outsideWindow (an assignment matches, but not on this day), maxRedemptionsReached (no use left under maxRedemptions), maxPerCustomerReached (no use left for this customer under maxPerCustomer).
remainingUses left under maxRedemptions, counted from booked invoices whose uses no full credit note has given back. Null when the discount has no total limit, or no such discount exists in your company.
remainingForCustomerUses left for this customer under maxPerCustomer. Null when the discount has no per-customer limit, or no such discount exists in your company.
Assign a discount
Credential: a company's API key or OAuth token.
Adds an assignment: the products, the customers and the window of days the
discount applies to. The products are one product (productId), every product
in a product group (productGroupId), or every product when both are null;
the customers are one customer, a customer group or every customer the same
way. Setting both fields of a pair is refused with
400 DISCOUNT_ASSIGNMENT_TARGET_CONFLICT. A null startsAt means from any
day and a null endsAt never ending. Both dates are inclusive calendar days.
A group is read when a document is checked, so a product or customer moved into the group later is covered from then on. Deleting the group deletes the assignments aimed at it.
A discount can carry several assignments, so one discount can serve several products or customers.
The edit is saved and the response's warnings carries
DISCOUNT_IN_USE_ON_OPEN_DOCUMENTS when open quotes, order confirmations or
invoice drafts reference the discount: total counts them and documents
lists the newest 50 of those your key may read (quotes-read,
order-confirmations-read, invoices-read). A sent quote or order confirmation keeps its discount
figures until it is converted; an invoice draft takes the new value the next
time it is saved. warnings is empty when nothing is open.
Required Scope
products-write
path Parameters
discountIdDiscount ID
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Assign a discount › Request Body
productIdThe product the discount applies to. Null or omitted, with no product group: every product.
productGroupIdThe product group the discount applies to: every product in it. Set at most one of productId and productGroupId; both is refused with DISCOUNT_ASSIGNMENT_TARGET_CONFLICT.
customerIdThe customer the discount applies to. Null or omitted, with no customer group: every customer.
customerGroupIdThe customer group the discount applies to: every customer in it. Set at most one of customerId and customerGroupId; both is refused with DISCOUNT_ASSIGNMENT_TARGET_CONFLICT.
startsAtFirst calendar day it applies, inclusive (YYYY-MM-DD). Null or omitted: from any day.
endsAtLast calendar day it applies, inclusive (YYYY-MM-DD). Null or omitted: it never ends.
Assign a discount › Responses
Assignment created
idThe assignment ID.
discountIdThe discount this assignment belongs to.
productIdThe product the discount applies to. Null, with no product group: every product.
productGroupIdThe product group the discount applies to: every product whose group it is, at the time a document is checked. Null: no group target. Never set together with productId.
customerIdThe customer the discount applies to. Null, with no customer group: every customer.
customerGroupIdThe customer group the discount applies to: every customer whose group it is, at the time a document is checked. Null: no group target. Never set together with customerId.
startsAtFirst calendar day the discount applies, inclusive (YYYY-MM-DD). Null: from any day.
endsAtLast calendar day the discount applies, inclusive (YYYY-MM-DD). Null: it never ends.
Warnings about the edit, empty when there is nothing to warn about. DISCOUNT_IN_USE_ON_OPEN_DOCUMENTS lists the open quotes (not converted, rejected or expired), order confirmations (not converted) and invoice drafts that reference the discount. The edit is saved either way. A sent quote or order confirmation keeps its discount figures until it is converted; an invoice draft takes the new value the next time it is saved. Given when an assignment is added, or an edit moves its product, product group, customer, customer group or dates.
Remove an assignment
Credential: a company's API key or OAuth token.
Removes an assignment. A discount left with no assignment applies nowhere.
The edit is saved and the response's warnings carries
DISCOUNT_IN_USE_ON_OPEN_DOCUMENTS when open quotes, order confirmations or
invoice drafts reference the discount: total counts them and documents
lists the newest 50 of those your key may read (quotes-read,
order-confirmations-read, invoices-read). A sent quote or order confirmation keeps its discount
figures until it is converted; an invoice draft takes the new value the next
time it is saved. warnings is empty when nothing is open.
Removing an assignment gives that warning whenever open documents reference the discount.
Required Scope
products-write
path Parameters
discountIdDiscount ID
assignmentIdAssignment ID
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Remove an assignment › Responses
Assignment removed
Warnings about the edit, empty when there is nothing to warn about. DISCOUNT_IN_USE_ON_OPEN_DOCUMENTS lists the open quotes (not converted, rejected or expired), order confirmations (not converted) and invoice drafts that reference the discount. The edit is saved either way. A sent quote or order confirmation keeps its discount figures until it is converted; an invoice draft takes the new value the next time it is saved. Given whenever open documents reference the discount, since removing an assignment narrows where it applies.
Update an assignment
Credential: a company's API key or OAuth token.
Changes an assignment. A field left out keeps its value; a field sent as null
clears it, widening the assignment to every product, every customer, any start
day or no end. To move an assignment from a product to a product group (or a
customer to a customer group), send the new field and null for the old one in
the same request: a pair holding both is refused with
400 DISCOUNT_ASSIGNMENT_TARGET_CONFLICT.
The edit is saved and the response's warnings carries
DISCOUNT_IN_USE_ON_OPEN_DOCUMENTS when open quotes, order confirmations or
invoice drafts reference the discount: total counts them and documents
lists the newest 50 of those your key may read (quotes-read,
order-confirmations-read, invoices-read). A sent quote or order confirmation keeps its discount
figures until it is converted; an invoice draft takes the new value the next
time it is saved. warnings is empty when nothing is open.
An edit that moves the product, product group, customer, customer group or dates gives that warning; one that restates them gives none.
Required Scope
products-write
path Parameters
discountIdDiscount ID
assignmentIdAssignment ID
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Update an assignment › Request Body
productIdThe product the discount applies to. Null or omitted, with no product group: every product.
productGroupIdThe product group the discount applies to: every product in it. Set at most one of productId and productGroupId; both is refused with DISCOUNT_ASSIGNMENT_TARGET_CONFLICT.
customerIdThe customer the discount applies to. Null or omitted, with no customer group: every customer.
customerGroupIdThe customer group the discount applies to: every customer in it. Set at most one of customerId and customerGroupId; both is refused with DISCOUNT_ASSIGNMENT_TARGET_CONFLICT.
startsAtFirst calendar day it applies, inclusive (YYYY-MM-DD). Null or omitted: from any day.
endsAtLast calendar day it applies, inclusive (YYYY-MM-DD). Null or omitted: it never ends.
Update an assignment › Responses
Assignment updated
idThe assignment ID.
discountIdThe discount this assignment belongs to.
productIdThe product the discount applies to. Null, with no product group: every product.
productGroupIdThe product group the discount applies to: every product whose group it is, at the time a document is checked. Null: no group target. Never set together with productId.
customerIdThe customer the discount applies to. Null, with no customer group: every customer.
customerGroupIdThe customer group the discount applies to: every customer whose group it is, at the time a document is checked. Null: no group target. Never set together with customerId.
startsAtFirst calendar day the discount applies, inclusive (YYYY-MM-DD). Null: from any day.
endsAtLast calendar day the discount applies, inclusive (YYYY-MM-DD). Null: it never ends.
Warnings about the edit, empty when there is nothing to warn about. DISCOUNT_IN_USE_ON_OPEN_DOCUMENTS lists the open quotes (not converted, rejected or expired), order confirmations (not converted) and invoice drafts that reference the discount. The edit is saved either way. A sent quote or order confirmation keeps its discount figures until it is converted; an invoice draft takes the new value the next time it is saved. Given when an assignment is added, or an edit moves its product, product group, customer, customer group or dates.
List a discount's codes
Credential: a company's API key or OAuth token.
Retrieves a paginated list of the discount's codes, active and switched off,
oldest first, each with the uses counted through it. total counts every
code of the discount.
Required Scope
products-read
path Parameters
discountIdDiscount ID
query Parameters
pagePage number (1-indexed)
limitMaximum number of items per page
List a discount's codes › Responses
Paginated list of the discount's codes
Page of the discount's codes, active and switched off, oldest first.
totalTotal number of codes the discount has
pageCurrent page number
limitItems per page
totalPagesTotal number of pages
Add a code to a discount
Credential: a company's API key or OAuth token.
Adds a code a customer can type to claim the discount. A discount can carry many codes. A code narrows the discount and never widens it: the discount's assignments, window and limits still apply, and the code may add the one customer it is for, its own limit on uses and a last day.
Refused with 409 DISCOUNT_CODE_TAKEN while another active code of your
company holds the same text, compared without case; a switched-off code frees
its text. Refused with DISCOUNT_CODE_INVALID for an empty code, one over 64
characters or one with a space inside, and with
DISCOUNT_CODE_CUSTOMER_NOT_ASSIGNED for a customer the discount's
assignments do not cover.
Required Scope
products-write
path Parameters
discountIdDiscount ID
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Add a code to a discount › Request Body
codeThe code a customer types: 1 to 64 characters with no space inside, matched without regard to case or surrounding spaces. Otherwise DISCOUNT_CODE_INVALID; an active code of your company with the same text: DISCOUNT_CODE_TAKEN.
customerIdThe one customer who may use the code. It must be a customer the discount's assignments cover, or DISCOUNT_CODE_CUSTOMER_NOT_ASSIGNED. Null or omitted: any customer.
maxRedemptionsUses allowed through this code. Null or omitted: no limit.
expiresAtLast calendar day the code may be used, inclusive (YYYY-MM-DD). Null or omitted: never expires.
activeDefaults to true.
Add a code to a discount › Responses
Code created
idThe code ID.
discountIdThe discount the code claims.
codeThe code as it was entered, without surrounding spaces.
normalizedCodeThe code trimmed and upper-cased: the text a lookup matches on.
customerIdThe one customer who may use the code. Null: any customer the discount applies to.
maxRedemptionsUses allowed through this code. Null: no limit of its own.
expiresAtLast calendar day the code may be used, inclusive (YYYY-MM-DD). Null: it never expires.
activeFalse: the code is switched off and its text may be reused by a new code.
usesUses counted through this code: booked invoices whose use no full credit note has given back.
createdAtWhen the code was created (ISO 8601).
Delete a code
Credential: a company's API key or OAuth token.
Deletes a code no use records. A code that has been used is refused with
409 DISCOUNT_CODE_IN_USE; switch it off with active: false instead.
Required Scope
products-write
path Parameters
discountIdDiscount ID
codeIdCode ID
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Delete a code › Responses
Code deleted
Update a code
Credential: a company's API key or OAuth token.
Changes whether the code is active, the customer it is for, its limit and its last day. A field left out keeps its value; a nullable field sent as null clears it. The code's text cannot change: switch it off and add a new one.
Required Scope
products-write
path Parameters
discountIdDiscount ID
codeIdCode ID
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Update a code › Request Body
activeFalse switches the code off. True switches it back on, refused with DISCOUNT_CODE_TAKEN if another active code now holds its text.
customerIdNull: any customer the discount applies to.
maxRedemptionsNull removes the limit.
expiresAtNull: never expires.
Update a code › Responses
Code updated
idThe code ID.
discountIdThe discount the code claims.
codeThe code as it was entered, without surrounding spaces.
normalizedCodeThe code trimmed and upper-cased: the text a lookup matches on.
customerIdThe one customer who may use the code. Null: any customer the discount applies to.
maxRedemptionsUses allowed through this code. Null: no limit of its own.
expiresAtLast calendar day the code may be used, inclusive (YYYY-MM-DD). Null: it never expires.
activeFalse: the code is switched off and its text may be reused by a new code.
usesUses counted through this code: booked invoices whose use no full credit note has given back.
createdAtWhen the code was created (ISO 8601).
List the discounts that apply to a product for a customer on a day
Credential: a company's API key or OAuth token.
Returns every active discount with an assignment that covers the product, the
customer and the day, ordered by priority (lowest first). An assignment with
no product and no product group covers every product; one with no customer and
no customer group covers every customer; one with a group covers the products
or customers in that group when the request is made. Its startsAt and
endsAt are inclusive calendar days.
A discount whose redemption limit has no use left, in total or for this customer, is left out. A use is counted when an invoice that references the discount is booked, and given back when a credit note leaves nothing creditable on that invoice.
The answer does not look at currency: a fixed or per-unit discount without an
amount in the document's currency is still listed, and a document that
references it in that currency is refused with
DISCOUNT_NO_AMOUNT_IN_CURRENCY.
Required Scope
products-read
query Parameters
customerIdThe customer the document is for.
productIdThe line's product.
asOfThe calendar day to judge on (YYYY-MM-DD), normally the document's date. An assignment covers it when startsAt ≤ asOf ≤ endsAt, both ends inclusive.
List the discounts that apply to a product for a customer on a day › Responses
The discounts that apply
idThe discount ID.
namePrinted as the reason on the e-invoice allowance.
typepercentage takes a percent off; fixed takes an amount off, per eligible line for a line discount or once per document for a document discount; per_unit takes an amount off each unit on a line and takes line scope only. The type cannot change after the discount is created.
scopeline applies to each eligible line on its own. document applies once per document, after every line discount, when the customer matches and at least one line has an eligible product. A per_unit discount with document scope is refused with DISCOUNT_PER_UNIT_NEEDS_LINE_SCOPE.
percentagePctPercentage discounts only: the percent taken off, above 0 and at most 100. Null for other types.
priorityThe order the server applies discounts in when it picks them itself; lowest first.
combinableFalse: a line may not reference this discount together with another one.
activeAn inactive discount applies nowhere.
requiresCodeTrue: the discount applies only through one of its codes. A document or an applicability check that names it by its id alone is refused with the reason codeRequired, and GET /v1/discounts/applicable leaves it out.
maxRedemptionsTotal uses allowed. Null: no limit.
maxPerCustomerUses allowed per customer. Null: no limit.
durationInPeriodsHow many billing periods the discount lasts on a subscription that references it. Null: for as long as the reference stands.
Fixed and per-unit discounts: one positive amount per currency, sorted by currency. Empty for a percentage discount. A discount is applied only to a document line or document that references its id; creating or assigning it changes no document on its own.
Where the discount applies: each assignment names a product, a customer and a window of days, any of them null for "all". A discount with no assignment applies nowhere.
Check a cart
Credential: a company's API key or OAuth token.
Prices a webshop cart before any order exists: what each discount and code takes off these lines, the ones that do not apply and why, and the uses left. It creates no document and holds no use; booking the invoice counts the use and checks every limit again.
The discounts in discountIds apply first, then the codes, each in the order
sent; a discount named twice applies once. A line discount, named once for the
cart, lands on every line whose product it covers. A document discount is taken
from the net of the lines it covers, a returned (negative) line included, and
is split by VAT rate only when every line it falls on carries vatRatePct.
Without customerId the shopper is a guest: only assignments for every
customer apply, a code made for one customer does not, and
remainingForCustomer is null.
A code your company does not have, or a discount that does not apply, comes
back in refusals with its reason while the rest of the cart is still priced.
Limited to 600 uses a minute per API key (or OAuth grant, else OAuth client),
shared with the code lookup. A check uses one per code it names, and one when it
names none; a lookup uses one. A check that needs more than is left is refused
whole and tries none of its codes: the answer is
429 DISCOUNT_CHECK_RATE_LIMITED with a Retry-After header.
Required Scope
discounts-checkorproducts-read
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Check a cart › Request Body
currency^[A-Za-z]{3}$ · requiredThe cart's currency, ISO 4217 alpha-3. A fixed or per-unit discount needs an amount in it.
dateThe calendar day the cart is priced on (YYYY-MM-DD).
1 to 200 lines.
customerIdThe customer buying. Omitted: a guest, to whom only assignments for every customer apply, a code made for one customer does not apply, and no per-customer use is counted.
codesCodes the shopper typed, at most 20, matched without regard to case or surrounding spaces. They apply after discountIds, in the order sent.
discountIdsDiscounts applied by id, at most 50, in the order sent and before the codes.
Check a cart › Responses
What the cart takes off, and what does not apply
Every line of the request, in order.
One row per discount the cart named.
Look up a discount code
Credential: a company's API key or OAuth token.
Answers the code a customer typed, the discount it claims, and whether it
applies. The code is matched without regard to case or surrounding spaces, so
summer25 finds SUMMER25. Built for a webshop's "apply code" field: it
answers one code and lists nothing.
Pass customerId for a known customer; without it the shopper is a guest, to
whom only assignments for every customer apply and a code made for one
customer does not. Pass productId to judge the discount for one product,
and asOf for a day other than today.
A code your company does not have answers 200 with reason: codeUnknown,
code: null and discount: null; another company's code answers the
same. The reasons are checked in this order: codeUnknown, inactive,
notAssigned or notInGroup, outsideWindow, maxRedemptionsReached,
maxPerCustomerReached, codeInactive, codeExpired,
codeCustomerMismatch, codeMaxRedemptionsReached.
Asking holds no use: a booking that would pass a limit is still refused.
Required Scope
discounts-checkorproducts-read
path Parameters
codeThe code as the customer typed it
query Parameters
customerIdThe customer who would use the code. Omitted: a guest, to whom only assignments for every customer apply.
productIdA product to judge the discount's assignments for. Omitted: any product.
asOfThe calendar day to judge on (YYYY-MM-DD), normally the order date. Omitted: today.
Look up a discount code › Responses
The code and whether it applies
codeNull when your company has no such code.
discountThe discount the code claims. Null when your company has no such code.
applicableWhether the code applies for this customer, product and day.
reasonNull when it applies. Otherwise the first check that failed: codeUnknown (no such code in your company), then the discount's own inactive, notAssigned, notInGroup (an assignment would match, but the product or the customer is not in the group it targets), outsideWindow, maxRedemptionsReached, maxPerCustomerReached, then the code's codeInactive, codeExpired (past its last day), codeCustomerMismatch (the code is for another customer, or for a customer and none was given) and codeMaxRedemptionsReached.
remainingUses left under the discount's maxRedemptions. Null: no total limit.
remainingForCustomerUses left for this customer under the discount's maxPerCustomer. Null: no such limit, or no customer given.
remainingForCodeUses left under the code's own maxRedemptions. Null: no limit of its own.