Coupons

Value vouchers - list, detail, shipping-cost link. A product type alongside tickets, events and tours.

A coupon in go~mus is a value voucher - a product with a sale price and a redeemable balance after the sale. Coupons are a product type alongside tickets, events and tours: same order mechanics, separate endpoint for the master data.

Full endpoint and schema reference: Swagger.

Endpoints at a glance

EndpointWhat
GET /api/v4/couponsList all coupons available for online sale
GET /api/v4/coupons/:idSingle coupon detail incl. description and content

Anatomy of a coupon object

  • id - stable primary key, use it in order items
  • title - title in the index
  • description - in the detail response, long text for detail pages
  • price_cents - sale price in cents (what buyers pay)
  • value_cents - redeemable balance after sale in cents (may exceed price for promotions)
  • vat_pct - tax rate
  • shipped_with_merchandise_id - if set, the id of a merchandise article that must be booked alongside as a shipping-cost representation
  • content (detail only) - multi-locale shop content (shop_title, shop_sub_title, shop_description)

Common tasks

List coupons

curl "https://demo.gomus.de/api/v4/coupons?locale=de"

Pagination via page and per_page as on the other resources.

Coupon detail

curl "https://demo.gomus.de/api/v4/coupons/4?locale=de"

Add a coupon to an order

Coupon items follow the same order schema as tickets:

{
  "items": [
    { "type": "Coupon", "attributes": { "id": 4, "quantity": 1 } }
  ]
}

If shipped_with_merchandise_id is set on the coupon, the referenced merchandise article must be added to the order as a separate item, otherwise the order goes through without shipping costs.

Relationships

Coupon
 ├── Merchandise ......... via shipped_with_merchandise_id (shipping-cost article)
 └── OrderItem ........... when sold, the coupon lives as an item on an order

Pitfalls

  • price_cents ≠ value_cents. price is what the buyer pays, value is what the coupon is worth after sale. Promotions like "pay 50 EUR, redeem 60 EUR" use this delta intentionally - the difference is marketing margin, not a bug.
  • Shipping costs via merchandise. If shipped_with_merchandise_id is set, the referenced merchandise item must be added explicitly to the order. Without it the order looks free but breaks at shipping time.