Arlo

REST Pub API: Advertised offers

Advertised offers represent promotional price points for an event and are used by API resources that need to return any type of promotional pricing information. Simple events may have only one price (and therefore only one offer). Other events may have multiple base price points and discounts and resulting in a range of offers being returned from the API.

An individual offer is composed of a descriptive label plus fields indicating whether the offer represents a discount, as well as the amount, currency, applicable tax, and any custom message.

This article outlines the technical specification of offers (structure and fields), and also contains some important guidelines on how to render offer information as a list on your page, or how to choose a single offer to display if you have room for only one price.

Collection structure

Offer information is returned as a structured array containing one or more offer entries. The order of the array is not specific, and clients should always sort and display the returned offers in an order appropriate for their site (such as cheapest first, or base offers first followed by discounts).

[
   {
      "OfferID":0,
      "Label":"15% off for 3 registrations",
      "IsDiscountOffer":true,
      "OfferAmount":{
         "CurrencyCode":"AUD",
         "AmountTaxExclusive":296.65,
         "AmountTaxInclusive":326.32,
         "FormattedAmountTaxExclusive":"$296.65",
         "FormattedAmountTaxInclusive":"$326.32",
         "TaxRate":{
            "ShortName":"GST",
            "Name":"GST (10.0%)",
            "RatePercent":10
         }
         "Deposit":{
            "Percent":10,
            "AmountTaxExclusive":29.66,
            "AmountTaxInclusive":32.63
         }
      }
   },
   {
      "OfferID":1,
      "IsDiscountOffer":false,
      "OfferAmount":{
         "CurrencyCode":"AUD",
         "AmountTaxExclusive":349,
         "AmountTaxInclusive":383.9,
         "FormattedAmountTaxExclusive":"$349.00",
         "FormattedAmountTaxInclusive":"$383.90",
         "TaxRate":{
            "ShortName":"GST",
            "Name":"GST (10.0%)",
            "RatePercent":10
         }
         "Deposit":{
            "Percent":10,
            "AmountTaxExclusive":34.9,
            "AmountTaxInclusive":38.39
        }
      }
   },
   {
      "OfferID":2,
      "IsDiscountOffer":true,
      "ReplacesOfferID":1,
      "Label":"Early bird price",
      "Message":"Limited time!",
      "OfferAmount":{
         "CurrencyCode":"AUD",
         "AmountTaxExclusive":303.55,
         "AmountTaxInclusive":333.9,
         "FormattedAmountTaxExclusive":"$303.55",
         "FormattedAmountTaxInclusive":"$333.90",
         "TaxRate":{
            "ShortName":"GST",
            "Name":"GST (10.0%)",
            "RatePercent":10
         }
         "Deposit":{
            "Percent":10,
            "AmountTaxExclusive":30.36,
            "AmountTaxInclusive":33.39
        }
      }
   }
]

Fields

Field Description
OfferID The unique identifier of this offer within the list of offers.
Label A text description of the offer, such as the name of the discount. For example "Member price" or "Early bird special price!". This field is optional, and can be null for non-discount (base) offers.
IsDiscountOffer A boolean value indicating whether this offer represents a discounted amount from the base offer. A given collection of offers may have multiple base offers and multiple discounts.
ReplacesOfferID An ID reference to the offer this item replaces, if any. Applies only to discount offers that represent a new base price such as an absolute reduction in the price of an event. Not all discounts replace another offer.

This field is not used for discount offers that are available only when certain criteria are met (meaning they do not replace another offer).
OfferAmount A structure describing the amount of the discount, including currency, raw decimal and formatted string representations and tax information (if available).
Structure fields
  • CurrencyCode: A string value indicating the currency of the offer.
  • AmountTaxExclusive: Decimal value with the tax-exclusive amount of the offer.
  • AmountTaxInclusive: Decimal value with the tax-inclusive amount of the offer. If tax is not applicable, or cannot be calculated, this value will be the same as the exclusive amount.
  • FormattedAmountTaxExclusive: String value with a display-formatted representation of the tax-exclusive amount.
  • FormattedAmountTaxInclusive: String value with a display-formatted representation of the tax-inclusive amount.
  • TaxRate: A structure representing associated tax information for the offer. This field is relevant only if tax is applicable. If tax does not apply (such as zero-rated tax pricing or offers to international visitors), this field is omitted.
  • Deposit: A structure representing the deposit information for the offer. This field is relevant only if deposits are enabled.
Message An optional text message to be displayed for this offer if there are special conditions or custom notes. For example, "Limited time only!" or "Membership required".

Rendering guidelines

Our team has some recommended ways to render the different variations of offers. Administrators managing events may choose to promote a single price or multiple prices (including discounts and replaced offers). It is important that code handling API offer information can deal with these different scenarios to ensure the event pricing is promoted in the way the event administrators intended.

Different designs have different constraints on space, so we have included notes on how to display a single (best) offer when you have room for only one price, and also notes for displaying a full list of offers.

The points in this section are intended to be guidelines, and you are free to choose to render offers in any way appropriate to the design and look and feel of your site. However, we do recommend you incorporate all of the features of the API specification into your design, including offer labels, replaced offers, tax information, and custom messages as appropriate.

Single (best) offer format guidelines

When rendering lists with many events or in compact promotional widgets, a design may have room for one price only. In these situations, more offers may be returned from the API than there is room for display.

An example list is shown below includes only room for one price per item.

Example list of items, showing the single best offer per item.

To produce a list like this using a single offer per item, follow these guidelines:

  1. Sort each event's list of offers by amount (using AmountTaxInclusive decimal value) to produce a new array of offers with the cheapest offer at the start.

  2. Use the first element of the array (representing the cheapest offer) as the single promoted offer for the event.

  3. If the cheapest offer is a discount (where IsDiscountOffer == true), use the special display format From {FormattedAmount}. For example "From $99.95" to indicate the value is a promotional offer, and not necessarily the standard price of the event.

Full offer listing format guidelines

The guidelines in this section are designed to be used in pages where a full listing of offers is required. This section covers the different parts of an offer line, and provides three examples of increasing complexity and recommended rendering strategy for each.

Offer display components

Before covering the different scenarios for a full listing of offers, it's important to first describe the different components of an offer line and our recommendation for rendering them.

Rendered offer lines usually include four display parts:

  • The label of an offer (which can be blank). This value comes from the Label field.

  • The amount of the offer, which may be formatted string such as $200.00, or a custom format of your own such as USD 200.00 in multi-currency lists. This value comes from the OfferAmount field.

  • Details of any taxes included or excluded in the amount. This information can often be left out if your site has a covering statement elsewhere indicating whether all prices are tax inclusive or exclusive, or if tax is not relevant for your event pricing. This value comes from the OfferAmount.TaxRate field.

  • A special message or note to display alongside the offer (which can be blank). This value comes from the Message field.

Simple list, no discounts

The simplest scenario is an offers array containing only one offer. This is typical for events with one standard price, and no promoted discounts.

[
   {
      "OfferID":0,
      "IsDiscountOffer":false,
      "OfferAmount":{
         "CurrencyCode":"AUD",
         "AmountTaxExclusive":349,
         "AmountTaxInclusive":383.9,
         "FormattedAmountTaxExclusive":"$349.00",
         "FormattedAmountTaxInclusive":"$383.90",
         "TaxRate":{
            "ShortName":"GST",
            "Name":"GST (10.0%)",
            "RatePercent":10
         }
         "Deposit":{
            "Percent":10,
            "AmountTaxExclusive":34.9,
            "AmountTaxInclusive":38.39
         }
      }
   }   
]

Can be rendered in a single line as:

Note:

  • The offer in this example has no label defined.

Simple list, with discounts

A more complex scenario is an offers array containing several offers, including one discount. The example below has two offers.

[
   {
      "OfferID":0,
      "Label":"15% off for 3 registrations",
      "IsDiscountOffer":true,
      "OfferAmount":{
         "CurrencyCode":"AUD",
         "AmountTaxExclusive":296.65,
         "AmountTaxInclusive":326.32,
         "FormattedAmountTaxExclusive":"$296.65",
         "FormattedAmountTaxInclusive":"$326.32",
         "TaxRate":{
            "ShortName":"GST",
            "Name":"GST (10.0%)",
            "RatePercent":10
         }
      }
   },
   {
      "OfferID":1,
      "IsDiscountOffer":false,
      "OfferAmount":{
         "CurrencyCode":"AUD",
         "AmountTaxExclusive":349,
         "AmountTaxInclusive":383.9,
         "FormattedAmountTaxExclusive":"$349.00",
         "FormattedAmountTaxInclusive":"$383.90",
         "TaxRate":{
            "ShortName":"GST",
            "Name":"GST (10.0%)",
            "RatePercent":10
         }
         "Deposit":{
            "Percent":10,
            "AmountTaxExclusive":34.9,
            "AmountTaxInclusive":38.39
         }
      }
   }
]

Can be rendered in multiple lines as:

Notes:

  • The base offer in this example has no label defined.

  • Discount offers (where IsDiscountOffer == true) are formatted in a different color to the non-discounted offers to promote them as special values.

Advanced list, with discounts and replaced offers

The most complex scenario is an array that involves multiple offers, and includes one or more offers replacing another in the list. The example below includes three offers, with one offer (the base offer) being replaced by another (the early bird offer).

[
   {
      "OfferID":0,
      "Label":"15% off for 3 registrations",
      "IsDiscountOffer":true,
      "OfferAmount":{
         "CurrencyCode":"AUD",
         "AmountTaxExclusive":296.65,
         "AmountTaxInclusive":326.32,
         "FormattedAmountTaxExclusive":"$296.65",
         "FormattedAmountTaxInclusive":"$326.32",
         "TaxRate":{
            "ShortName":"GST",
            "Name":"GST (10.0%)",
            "RatePercent":10
         }
      }
   },
   {
      "OfferID":2,
      "IsDiscountOffer":false,
      "OfferAmount":{
         "CurrencyCode":"AUD",
         "AmountTaxExclusive":349,
         "AmountTaxInclusive":383.9,
         "FormattedAmountTaxExclusive":"$349.00",
         "FormattedAmountTaxInclusive":"$383.90",
         "TaxRate":{
            "ShortName":"GST",
            "Name":"GST (10.0%)",
            "RatePercent":10
         }
         "Deposit":{
            "Percent":10,
            "AmountTaxExclusive":34.9,
            "AmountTaxInclusive":38.39
         }
      }
   },
   {
      "OfferID":1,
      "IsDiscountOffer":true,
      "ReplacesOfferID":2,
      "Label": "Special early bird offer!",
      "Message": "Limited time!",
      "OfferAmount":{
         "CurrencyCode":"AUD",
         "AmountTaxExclusive":303.55,
         "AmountTaxInclusive":333.9,
         "FormattedAmountTaxExclusive":"$303.55",
         "FormattedAmountTaxInclusive":"$333.90",
         "TaxRate":{
            "ShortName":"GST",
            "Name":"GST (10.0%)",
            "RatePercent":10
         }
      }
   }
]

Can be rendered as:

Notes:

  • The base offer in this example has no label defined.

  • Replaced offers are rendered with a strikeout style, with tax information omitted (for berevity) with the replacing offer on the same line.

  • The replacing offer includes the use of a custom Message value.