Marketing API Version

Offer Ads

Offer Ads help advertise discounts and promotions with consumers. People can claim, save and redeem your offers, and if they don’t, we remind them about it before it expires with a Facebook notification.

To create an offer ad, create an offer and promote it with link_data, known as Ad Creative Link Data for AdCreativeObjectStorySpec.

Create an Offer

Create offers that are online, offline or both: users redeem online offers on websites, offline offers at local stores, or both online and at local stores. And add four types of offers: percentage_off, cash_discount, bogo, and free_stuff. For all offers options and parameters, see Page Native Offers.

Note: You cannot update or delete offers; instead, create a new offer for use.

Online Offer

Provide the URL where people can redeem the offer. If an offer needs a discount code, add one generic code for all people to use or upload a file with unique codes. See Unique Codes.

use FacebookAds\Http\RequestInterface;

$params = array(
  'location_type' => 'online',
  'discounts' => array(
      'type' => 'percentage_off',
      'text' => 'the text description for this offer',
      'value1' => 20,
      'type' => 'free_stuff',
      'text' => 'the text description for this offer',
  'redemption_link' => '<OFFER_URL>',
  'redemption_code' => 'happysummer2016',
  'details' => 'the details for this specific offer',
  'expiration_time' => (new \DateTime("+10 day"))->getTimestamp(),

$data = Api::instance()->call(

// You need to note down this Offer ID to Create Offer Ads
$offer_id = $data['id'];
curl \
  -F 'location_type=online' \
  -F 'discounts=[ 
      "type": "percentage_off", 
      "text": "the text description for this offer", 
      "value1": 20 
    {"type":"free_stuff","text":"the text description for this offer"} 
  ]' \
  -F 'redemption_link=<OFFER_URL>' \
  -F 'redemption_code=happysummer2016' \
  -F 'details=the details for this specific offer' \
  -F 'expiration_time=1482413140' \
  -F 'access_token=<ACCESS_TOKEN>' \<PAGE_ID>/nativeoffers

Create a Mobile App Offer

For Mobile App Offers, set redemption_link to an app store URL such as A mobile app offer's location_type must be online.

Upload Unique Offer Codes

To upload a file of unique offer codes, post the file through Native Offers edge. Once you upload the file, the ad associated with the offer will automatically change each time a person claims it to show one of your unique codes.

Make sure your file has:

  1. One unique code per line with no line breaks
  2. 20 or fewer characters per code with no space
  3. Only letters, numbers, dashes or underscores allowed
  4. 500,000 or fewer unique codes
curl \
  -F 'filename=my_uniquie_codes.csv' \
  -F 'access_token=<ACCESS_TOKEN>' \

In-store Offer

To create an in-store offer, choose the type of code you want: discount code, barcode or no code. You can choose from 7 different barcodes, including QR codes. People can get this barcode scanned from their mobile device at your local store. (Note that not all scanner technologies can read mobile device screens. If you aren’t sure, please check the documentation for your point of sale hardware.)

use FacebookAds\Http\RequestInterface;

$params = array(
  'location_type' => 'offline',
  'barcode_type' => 'QR',
  'barcode_value' => 'happysummer2016',
  'discounts' => array(
      'type' => 'cash_discount',
      'text' => '10 dollars off',
      'value1' => 10,
  'details' => 'the details for this specific offer',
  'expiration_time' =>  (new \DateTime("+10 day"))->getTimestamp(),

$data = Api::instance()->call(

$offer_id = $data['id'];
curl \
  -F 'location_type=offline' \
  -F 'barcode_type=QR' \
  -F 'barcode_value=happysummer2016' \
  -F 'discounts=[ 
      "type": "cash_discount", 
      "text": "10 dollars off", 
      "value1": 10 
  ]' \
  -F 'details=the details for this specific offer' \
  -F 'expiration_time=1482413139' \
  -F 'access_token=<ACCESS_TOKEN>' \<PAGE_ID>/nativeoffers

Create an Offer Ad

After an offer is created, you can promote the offer by injecting the offer ID to Ad object, which had been returned in the previous step. You can retrieve all Offer IDs via Page Nativeoffers.

Create an Ad Campaign

To create a campaign for Offer Ad, use OFFER_CLAIMS as the campaign objective.

use FacebookAds\Object\Campaign;
use FacebookAds\Object\Fields\CampaignFields;
use FacebookAds\Object\Values\CampaignObjectiveValues;

$campaign = new Campaign(null, 'act_<AD_ACCOUNT_ID>');
  CampaignFields::NAME => 'My Offer Claims Campaign',
  CampaignFields::OBJECTIVE => CampaignObjectiveValues::OFFER_CLAIMS,

curl \
  -F 'name=My Offer Claims Campaign' \
  -F 'objective=OFFER_CLAIMS' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \<AD_ACCOUNT_ID>/campaigns

Create an Mobile App Offer Ad Campaign

To create a Mobile App Offer Ad, use corresponding campaign objectives that advertise on app install and engagement. See App Ads.

Create an Ad Set

To create an ad set for a general offer, specify page_id and offer_id in PROMOTED_OBJECT when creating an Ad Set.

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Fields\AdSetFields;
use FacebookAds\Object\Fields\TargetingFields;
use FacebookAds\Object\Values\AdSetBillingEventValues;
use FacebookAds\Object\Targeting;
use FacebookAds\Object\Values\AdSetOptimizationGoalValues;

$adset = new AdSet(null, 'act_<AD_ACCOUNT_ID>');
  AdSetFields::NAME => 'My First Offer Claim Adset',
  AdSetFields::LIFETIME_BUDGET => 56000,
  AdSetFields::START_TIME => (new \DateTime("now"))->getTimestamp(),
  AdSetFields::END_TIME => (new \DateTime("+7 day"))->getTimestamp(),
  AdSetFields::IS_AUTOBID => 1,
  AdSetFields::BILLING_EVENT => AdSetBillingEventValues::LINK_CLICKS,
  AdSetFields::PROMOTED_OBJECT=> array(
    'page_id' => <PAGE_ID>,
    'offer_id' => <OFFER_ID>,
  AdSetFields::TARGETING => (new Targeting())->setData(array(
    TargetingFields::GEO_LOCATIONS => array(
      'countries' => array('US'),
    TargetingFields::GENDERS => array(0),
    TargetingFields::AGE_MIN => 25,
    TargetingFields::AGE_MAX => 55,
    TargetingFields::INTERESTS => array(
        'id' => 6003107902433,
        'name' => 'Association football (Soccer)',
curl \
  -F 'name=My First Offer Claim Adset' \
  -F 'lifetime_budget=56000' \
  -F 'start_time=1485390784' \
  -F 'end_time=1485995584' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'is_autobid=1' \
  -F 'billing_event=LINK_CLICKS' \
  -F 'optimization_goal=LINK_CLICKS' \
  -F 'promoted_object={"page_id":"<PAGE_ID>","offer_id":"<OFFER_ID>"}' \
  -F 'targeting={ 
    "age_max": 55, 
    "age_min": 25, 
    "genders": [0], 
    "geo_locations": {"countries":["US"]}, 
    "interests": [{"id":6003107902433,"name":"Association football (Soccer)"}] 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \<AD_ACCOUNT_ID>/adsets

Create an Mobile App Offer Ad Set

In the PROMOTED_OBJECT of the ad set, instead of page_id, simply provide application_id and object_store_url for the app. You have to specify the offer_id to be the Mobile App Offer you created. Learn more about App Ads.

Create an Ad

To create an Ad, provide ad creative with the right object story specs.

Include link_data in the AdCreativeObjectStorySpec. The link you provide in link_data must be exactly the same as redemption_link.

use FacebookAds\Object\Ad;
use FacebookAds\Object\AdCreative;
use FacebookAds\Object\AdCreativeLinkData;
use FacebookAds\Object\AdCreativeObjectStorySpec;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Fields\AdCreativeLinkDataFields;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\Fields\AdFields;

$link_data = new AdCreativeLinkData();
  AdCreativeLinkDataFields::IMAGE_HASH => '<IMAGE_HASH>',
  AdCreativeLinkDataFields::OFFER_ID => <OFFER_ID>,
  AdCreativeLinkDataFields::MESSAGE => 'Great Deal!',
  AdCreativeLinkDataFields::LINK => '<OFFER_URL>',

$object_story_spec = new AdCreativeObjectStorySpec();
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::LINK_DATA => $link_data,

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');
  AdCreativeFields::NAME => 'My Offer Ad Creative',
  AdCreativeFields::OBJECT_STORY_SPEC => $object_story_spec,

$ad = new Ad(null, 'act_<AD_ACCOUNT_ID>');
  AdFields::NAME => 'My Offer Ad',
  AdFields::ADSET_ID => <AD_SET_ID>,
  AdFields::CREATIVE => $creative,
curl \
  -F 'name=My Offer Ad' \
  -F 'adset_id=<AD_SET_ID>' \
  -F 'creative={ 
    "name": "My Offer Ad Creative", 
    "object_story_spec": { 
      "link_data": { 
        "image_hash": "<IMAGE_HASH>", 
        "link": "<OFFER_URL>", 
        "message": "Great Deal!", 
        "offer_id": "<OFFER_ID>" 
      "page_id": "<PAGE_ID>" 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \<AD_ACCOUNT_ID>/ads

Use Video or Carousel Ad Creative