Discounts API

Promotions and discount codes — sales, order deals and free gifts.

Module code discounts · 12 actions · 10 data models · 13 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: discounts (everything), discounts:read (read only) or discounts:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

discounts.add_voucher_codes

Add voucher codes — Type codes, or generate up to fifty with an optional prefix.

Needs discounts:write · changes data

• Canonical address: POST /api/v1/actions/discounts.add_voucher_codes

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: discounts.voucher_codes_added

What it writes: voucher_code (insert) — Writes the codes

curl -X POST https://app.getera.io/api/v1/voucher_codes/actions/add_voucher_codes \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"voucherId":"VOUCHER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "discounts.voucher_codes_added"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.voucherCodes.addVoucherCodes({
  voucherId: "VOUCHER_ID"
})

era voucher_codes add_voucher_codes \
  --voucher-id "VOUCHER_ID"

{
  "name": "era__discounts__add_voucher_codes",
  "arguments": {
    "voucherId": "VOUCHER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold discounts:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, no_codes, too_many_codes, duplicate_codes, code_taken · 429 slow down

discounts.announce_promotion

Announce a promotion starting or ending — Machine: the shop sweep announces a start or an end once, as Saleor’s scheduled task does.

Needs discounts:write · reaches outside (sends, publishes or charges)

• Canonical address: POST /api/v1/actions/discounts.announce_promotion

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: discounts.promotion_started, discounts.promotion_ended

What it writes: promotion (update) — Stamps when it was announced

curl -X POST https://app.getera.io/api/v1/promotions/PROMOTION_ID/actions/announce_promotion \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "discounts.promotion_started",
    "discounts.promotion_ended"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.promotions.announcePromotion("PROMOTION_ID")

era promotions announce_promotion PROMOTION_ID

{
  "name": "era__discounts__announce_promotion",
  "arguments": {
    "id": "PROMOTION_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold discounts:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, nothing_to_announce · 429 slow down

discounts.delete_promotion

Delete a promotion — Its rules go with it. Orders already sold keep what they were charged.

Needs discounts:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• REST alias: DELETE /api/v1/promotions/{id}
• Canonical address: POST /api/v1/actions/discounts.delete_promotion

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: discounts.promotion_deleted

What it writes: promotion (delete) — Removes the promotion and its rules

curl -X POST https://app.getera.io/api/v1/promotions/PROMOTION_ID/actions/delete_promotion \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "discounts.promotion_deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.promotions.deletePromotion("PROMOTION_ID")

era promotions delete_promotion PROMOTION_ID

{
  "name": "era__discounts__delete_promotion",
  "arguments": {
    "id": "PROMOTION_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold discounts:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found · 429 slow down

discounts.delete_promotion_rule

Delete a promotion rule — The prices it painted go back to normal.

Needs discounts:write · removes or cannot be undone · asks a person to confirm when Era runs it

• REST alias: DELETE /api/v1/promotion_rules/{id}
• Canonical address: POST /api/v1/actions/discounts.delete_promotion_rule

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: discounts.rule_deleted

What it writes: promotion_rule (delete) — Removes the rule

curl -X POST https://app.getera.io/api/v1/promotion_rules/PROMOTION_RULE_ID/actions/delete_promotion_rule \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "discounts.rule_deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.promotionRules.deletePromotionRule("PROMOTION_RULE_ID")

era promotion_rules delete_promotion_rule PROMOTION_RULE_ID

{
  "name": "era__discounts__delete_promotion_rule",
  "arguments": {
    "id": "PROMOTION_RULE_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold discounts:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found · 429 slow down

discounts.delete_voucher

Delete a voucher — Its codes stop working. Orders keep the code text they were sold with.

Needs discounts:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• REST alias: DELETE /api/v1/vouchers/{id}
• Canonical address: POST /api/v1/actions/discounts.delete_voucher

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: discounts.voucher_deleted

What it writes: voucher (delete) — Removes the voucher and its codes

curl -X POST https://app.getera.io/api/v1/vouchers/VOUCHER_ID/actions/delete_voucher \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "discounts.voucher_deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.vouchers.deleteVoucher("VOUCHER_ID")

era vouchers delete_voucher VOUCHER_ID

{
  "name": "era__discounts__delete_voucher",
  "arguments": {
    "id": "VOUCHER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold discounts:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found · 429 slow down

discounts.delete_voucher_codes

Remove voucher codes — Used ones too, as in Saleor — the result says how many had been used.

Needs discounts:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/discounts.delete_voucher_codes

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: discounts.voucher_codes_deleted

What it writes: voucher_code (delete) — Removes the codes

curl -X POST https://app.getera.io/api/v1/voucher_codes/actions/delete_voucher_codes \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"voucherId":"VOUCHER_ID","codeIds":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "discounts.voucher_codes_deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.voucherCodes.deleteVoucherCodes({
  voucherId: "VOUCHER_ID",
  codeIds: {}
})

era voucher_codes delete_voucher_codes --data '{"voucherId":"VOUCHER_ID","codeIds":{}}'

{
  "name": "era__discounts__delete_voucher_codes",
  "arguments": {
    "voucherId": "VOUCHER_ID",
    "codeIds": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold discounts:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found · 429 slow down

discounts.import_voucher_codes

Import voucher codes — Codes from a CSV file — the first column, a header optional. All or none.

Needs discounts:write · changes data

• Canonical address: POST /api/v1/actions/discounts.import_voucher_codes

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: discounts.voucher_codes_added

What it writes: voucher_code (insert) — Writes the codes

curl -X POST https://app.getera.io/api/v1/voucher_codes/actions/import_voucher_codes \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"voucherId":"VOUCHER_ID","codes":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "discounts.voucher_codes_added"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.voucherCodes.importVoucherCodes({
  voucherId: "VOUCHER_ID",
  codes: {}
})

era voucher_codes import_voucher_codes --data '{"voucherId":"VOUCHER_ID","codes":{}}'

{
  "name": "era__discounts__import_voucher_codes",
  "arguments": {
    "voucherId": "VOUCHER_ID",
    "codes": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold discounts:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, no_codes, import_too_large, duplicate_codes, code_taken · 429 slow down

discounts.save_promotion

Save a promotion — A catalogue sale that paints prices, or an order deal on the basket total.

Needs discounts:write · changes data

• REST alias: PATCH /api/v1/promotions/{id}
• Canonical address: POST /api/v1/actions/discounts.save_promotion

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: discounts.promotion_created, discounts.promotion_updated

What it writes: promotion (upsert) — Creates or edits the promotion

curl -X POST https://app.getera.io/api/v1/promotions/PROMOTION_ID/actions/save_promotion \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "discounts.promotion_created",
    "discounts.promotion_updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.promotions.savePromotion("PROMOTION_ID", {
  name: "Name"
})

era promotions save_promotion PROMOTION_ID \
  --name "Name"

{
  "name": "era__discounts__save_promotion",
  "arguments": {
    "id": "PROMOTION_ID",
    "name": "Name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold discounts:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 invalid_name, not_found, end_before_start · 429 slow down

discounts.save_promotion_rule

Save a promotion rule — What it covers, in which channels, and what it gives.

Needs discounts:write · changes data

• REST alias: PATCH /api/v1/promotion_rules/{id}
• Canonical address: POST /api/v1/actions/discounts.save_promotion_rule

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: discounts.rule_created, discounts.rule_updated

What it writes: promotion_rule (upsert) — Creates or edits the rule; promotion_rule_channel (insert) — Replaces its channels; promotion_rule_target (insert) — Replaces what it covers; promotion_rule_gift (insert) — Replaces its gifts

curl -X POST https://app.getera.io/api/v1/promotion_rules/PROMOTION_RULE_ID/actions/save_promotion_rule \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"promotionId":"PROMOTION_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "discounts.rule_created",
    "discounts.rule_updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.promotionRules.savePromotionRule("PROMOTION_RULE_ID", {
  promotionId: "PROMOTION_ID"
})

era promotion_rules save_promotion_rule PROMOTION_RULE_ID \
  --promotion-id "PROMOTION_ID"

{
  "name": "era__discounts__save_promotion_rule",
  "arguments": {
    "id": "PROMOTION_RULE_ID",
    "promotionId": "PROMOTION_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold discounts:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, channel_not_found, predicate_required, predicate_not_allowed, invalid_range, invalid_predicate, reward_type_not_allowed, reward_type_required, mixed_currencies, gift_rule_invalid, reward_value_required, channels_required, invalid_percentage · 429 slow down

discounts.save_voucher

Save a voucher — A code customers type — its reach, its limits, its dates.

Needs discounts:write · changes data

• REST alias: PATCH /api/v1/vouchers/{id}
• Canonical address: POST /api/v1/actions/discounts.save_voucher

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: discounts.voucher_created, discounts.voucher_updated

What it writes: voucher (upsert) — Creates or edits the voucher; voucher_code (insert) — Writes its first codes on create

curl -X POST https://app.getera.io/api/v1/vouchers/VOUCHER_ID/actions/save_voucher \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "discounts.voucher_created",
    "discounts.voucher_updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.vouchers.saveVoucher("VOUCHER_ID", {
  name: "Name"
})

era vouchers save_voucher VOUCHER_ID \
  --name "Name"

{
  "name": "era__discounts__save_voucher",
  "arguments": {
    "id": "VOUCHER_ID",
    "name": "Name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold discounts:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, end_before_start, invalid_percentage, duplicate_codes, code_taken · 429 slow down

discounts.set_voucher_catalogue

Limit a voucher to part of the catalogue — The products, variants, categories and collections a specific-products voucher covers.

Needs discounts:write · changes data

• Canonical address: POST /api/v1/actions/discounts.set_voucher_catalogue

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: discounts.voucher_updated

What it writes: voucher_catalogue (insert) — Replaces what it covers

curl -X POST https://app.getera.io/api/v1/voucher_catalogues/actions/set_voucher_catalogue \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"voucherId":"VOUCHER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "discounts.voucher_updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.voucherCatalogues.setVoucherCatalogue({
  voucherId: "VOUCHER_ID"
})

era voucher_catalogues set_voucher_catalogue \
  --voucher-id "VOUCHER_ID"

{
  "name": "era__discounts__set_voucher_catalogue",
  "arguments": {
    "voucherId": "VOUCHER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold discounts:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, catalogue_not_allowed · 429 slow down

discounts.set_voucher_channels

Set a voucher’s value per channel — How much it takes off in each channel, and the minimum spend there.

Needs discounts:write · changes data

• Canonical address: POST /api/v1/actions/discounts.set_voucher_channels

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: discounts.voucher_updated

What it writes: voucher_channel_listing (upsert) — Replaces the per-channel values

curl -X POST https://app.getera.io/api/v1/voucher_channel_listings/actions/set_voucher_channels \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"voucherId":"VOUCHER_ID","listings":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "discounts.voucher_updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.voucherChannelListings.setVoucherChannels({
  voucherId: "VOUCHER_ID",
  listings: {}
})

era voucher_channel_listings set_voucher_channels --data '{"voucherId":"VOUCHER_ID","listings":{}}'

{
  "name": "era__discounts__set_voucher_channels",
  "arguments": {
    "voucherId": "VOUCHER_ID",
    "listings": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold discounts:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, channel_not_found, value_required, invalid_percentage · 429 slow down

Data models

PromotionRuleChannel

Table promotion_rule_channel · Resource promotion_rule_channels

• GET /api/v1/promotion_rule_channels
• GET /api/v1/promotion_rule_channels/{id}

Primary key: id

Unique: rule_id, channel_id

PromotionRuleGift

Table promotion_rule_gift · Resource promotion_rule_gifts

• GET /api/v1/promotion_rule_gifts
• GET /api/v1/promotion_rule_gifts/{id}

Primary key: id

Unique: rule_id, item_variant_id

PromotionRuleTarget

Table promotion_rule_target · Resource promotion_rule_targets

• GET /api/v1/promotion_rule_targets
• GET /api/v1/promotion_rule_targets/{id}

Primary key: id

Checks:

• CHECK ((num_nonnulls(item_id, item_variant_id, category_id, collection_id) = 1))

PromotionRule

Table promotion_rule · Resource promotion_rules

• GET /api/v1/promotion_rules
• GET /api/v1/promotion_rules/{id}
• PATCH /api/v1/promotion_rules/{id} → discounts.save_promotion_rule
• DELETE /api/v1/promotion_rules/{id} → discounts.delete_promotion_rule

Primary key: id

Checks:

• CHECK (((reward_value_type <> 'percentage'::text) OR (reward_value IS NULL) OR (reward_value <= (100)::numeric)))
• CHECK (((reward_value IS NULL) OR (reward_value >= (0)::numeric)))

Promotion

Table promotion · Resource promotions

• GET /api/v1/promotions
• GET /api/v1/promotions/{id}
• PATCH /api/v1/promotions/{id} → discounts.save_promotion
• DELETE /api/v1/promotions/{id} → discounts.delete_promotion

Primary key: id

Checks:

• CHECK (((end_date IS NULL) OR (end_date > start_date)))

VoucherCatalogue

Table voucher_catalogue · Resource voucher_catalogues

• GET /api/v1/voucher_catalogues
• GET /api/v1/voucher_catalogues/{id}

Primary key: id

Checks:

• CHECK ((num_nonnulls(item_id, item_variant_id, category_id, collection_id) = 1))

VoucherChannelListing

Table voucher_channel_listing · Resource voucher_channel_listings

• GET /api/v1/voucher_channel_listings
• GET /api/v1/voucher_channel_listings/{id}

Primary key: id

Unique: voucher_id, channel_id

Checks:

• CHECK ((currency ~ '^[A-Z]{3}$'::text))
• CHECK ((discount_value > (0)::numeric))
• CHECK (((min_spent_amount IS NULL) OR (min_spent_amount >= 0)))

VoucherCode

Table voucher_code · Resource voucher_codes

• GET /api/v1/voucher_codes
• GET /api/v1/voucher_codes/{id}

Primary key: id

Checks:

• CHECK (((length(code) >= 1) AND (length(code) <= 255)))
• CHECK ((used >= 0))

VoucherCustomer

Table voucher_customer · Resource voucher_customers

• GET /api/v1/voucher_customers
• GET /api/v1/voucher_customers/{id}

Primary key: id

Unique: voucher_code_id, order_id

Voucher

Table voucher · Resource vouchers

• GET /api/v1/vouchers
• GET /api/v1/vouchers/{id}
• PATCH /api/v1/vouchers/{id} → discounts.save_voucher
• DELETE /api/v1/vouchers/{id} → discounts.delete_voucher

Primary key: id

Checks:

• CHECK (((end_date IS NULL) OR (end_date > start_date)))
• CHECK (((min_checkout_items_quantity IS NULL) OR (min_checkout_items_quantity >= 0)))
• CHECK (((usage_limit IS NULL) OR (usage_limit >= 1)))

Events

Workflows and webhooks react to these events.