8 API Reference‎ > ‎Resources‎ > ‎

Offer

Represents an offer.

Common attributes:
  • id string.
  • title string.
  • price Currency.
  • value Currency.
  • type string. Possible values are deal, coupon, gift_card.
  • discount Discount.
  • fine_print string.
  • start_date date. 
  • end_date date.
  • items list of BundleItem. Applicable to bundle deals.
  • checkins_required integer. Applicable to coupons.
  • vouchers_activation_date date.
  • vouchers_expire Expiration.
  • quantity_in_stock integer.
  • creative Creative.
  • demographics Demographics.
  • restrictions Restrictions.
  • advertiser Advertiser.
  • status string.
Submission API specific attributes:
  • exclusivity Exclusivity.
  • initial_quantity integer.
  • reserved_quantity integer.
  • vouchers list of Voucher.
  • advertiser_rebate Currency
  • custom_attributes list of hash {name, value}.
Distribution API specific attributes:
  • sku string.
  • distributor_revenue Currency.
  • account_revenue Currency.
  • published_at time.
  • updated_at time.
  • closed_at time.

Data Example

JSON

{  
    "id": "powierjg928euwfg2rwsureuew",
    "sku": "D3422343",
    "type": "deal",
    "title": "Flowers",
    "price": Currency,
    "value": Currency,
    "advertiser_rebate": Currency,
    "discount": Discount,
    "fine_print": "",
    "start_date": "YYYY-MM-DD",
    "end_date": "YYYY-MM-DD",
    "quantity_in_stock": "287",
    "vouchers": list of Voucher,
    "published_at": "YYYY-MM-DD",
    "updated_at": "YYYY-MM-DD",
    "closed_at": "",
    "vouchers_expire": Expiration,
    "exclusivity": Exclusivity,
    "creative": Creative,
    "demographics": Demographics,
    "advertiser": Advertiser
    "custom_attributes": [{"name": "SKU", "value": "SU43234/DF"}, {"name": "pos_token", "value": "23487975973491934509213"}]
}

XML

<offer>  
    <id></id>
    <sku></sku>
    <type></type>
    <title></title>
    <price>Currency</price>
    <value>Currency</value>
    <advertiser_rebate>Currency</advertiser_rebate>
    <discount>Discount</discount>
    <fine_print></fine_print>
    <start_date></start_date>
    <end_date></end_date>
    <quantity_in_stock></quantity_in_stock>
    <vouchers>
        <voucher>Voucher</voucher>
        ...
    </vouchers>,
    <published_at></published_at>
    <updated_at></updated_at>
    <closed_at></closed_at>
    <vouchers_expire>Expiration</vouchers_expire>
    <exclusivity>Exclusivity</exclusivity>
    <creative>Creative</creative >
    <demographics>Demographics</demographics>
    <advertiser>Advertiser</advertiser>
    <custom_attributes>
        <custom_attribute><name>SKU</name><value>SU43234/DF</value><custom_attribute>
        <custom_attribute><name>pos_token</name><value>23487975973491934509213</value><custom_attribute>
    </custom_attributes>
</offer>

Actions

Create Offer

POST /offers

Update Offer

PUT /offers/<id>

Query Offers

GET /offers

Get Offer Details

GET /offers/<id>

Delete Offer

DELETE /offers/<id>

Offers queueing workflow

Not described yet.

Offers submission workflow

All examples are shown using command-line Curl and JSON output, but you can use XML and any other HTTP client tool/library as well.

Step 1 (optional): create attachment

Uploading attachment through the API:
curl -X POST -F attachment[media]=@/path/to/your/file.jpg -H "Accept: application/json" -H "X-ADILITY-API-KEY:<YOUR_API_KEY>" "http://testapi.adility.com/submission/beta/attachments"

Allowed file types are JPG/PNG/PDF/ZIP

Step 2: get list of available categories
curl -k -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:YOUR_SUBMISSION_API_KEY" 'http://testapi.adility.com/submission/beta/categories'


Step 3: submit an offer

curl -k -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:YOUR_SUBMISSION_KEY" 'http://testapi.adility.com/submission/beta/offers' -d '{"offer": {"type": "deal","title": "Initial Chiropractic Exam","price":{"currency_code":"USD","amount": 3700},"value": {"currency_code": "USD","amount": 22500}, "advertiser_rebate": {"currency_code": "USD","amount": 1500},"fine_print": "Limit 1 per person per visit.", "start_date": "2011-07-15","end_date": "2012-07-26","quantity_in_stock": 200, "vouchers_expire": {"on": "2013-01-01"},"creative": {"requires_editorial_support": false,"headlines": ["$37 for an Initial Chiropractic Exam, X-Rays, and 10-Minute Mechanical Traction at Cohen Chiropractic Centre (Valued at $225.)","$37 for $225 Worth of Initial Chiropractic Exam, X-Rays, and 10-Minute Mechanical Traction"],"description": "The only thing worse than back pain is having trouble finding a good chiropractor to straighten you out.","original_media": [{ "id": "8e5096a4c4d2cbe5acc6871f1ccb268ae03ef0393c86702169242fb7c04ef258"}]}, "advertiser": {"name": "Cohen Chiropractic Centre","description": "Chiropractic offers natural relief of chronic pain","categories": [{"id": "2126128138"}],"redemption_locations": [{"address_line_1": "2140 Peachtree Rd NW","address_line_2": "Suite 203", "city": "Atlanta","state_code": "GA","postal_code": "30309","country_code": "US"}],"website_url": "http://www.CohenChiropracticCentre.com","public_phone": "(404) 355-5499"}}}'

NOTE: Please send empty array of attachments [] if there are no attachments for your offer available.It should be applied to original_media field.

Step 4: update an offer

If you submitted an offer but want to edit it you should first withdraw it:

curl -k -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:YOUR_SUBMISSION_API_KEY" 'http://testapi.adility.com/submission/beta/offers/OFFER_ID' -d '{"offer": {"status":"withdrawn"}}'

Then you update the offer:

curl -k -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:YOUR_SUBMISSION_API_KEY" 'http://testapi.adility.com/submission/beta/offers/OFFER_ID' -d '{"offer": {"price":{"currency_code":"USD","amount": 3800},"creative": {"requires_editorial_support": false,"headlines": ["$38 for an Initial Chiropractic Exam, X-Rays, and 10-Minute Mechanical Traction at Cohen Chiropractic Centre (Valued at $225.)","$38 for $225 Worth of Initial Chiropractic Exam, X-Rays, and 10-Minute Mechanical Traction"]}}}'

and resubmit it:

curl -k -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:YOUR_SUBMISSION_API_KEY" 'http://testapi.adility.com/submission/beta/offers/OFFER_ID' -d '{"offer": {"status":"pending"}}'

Step 5: add comment on offer

curl -k -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:YOUR_SUBMISSION_API_KEY" 'http://testapi.adility.com/submission/beta/offers/OFFER_ID/comments' -d '{"comment": {"author_name": "test author","content": "test comment"}'

Step 6: suspend offer

curl -k -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:YOUR_SUBMISSION_API_KEY" 'http://testapi.adility.com/submission/beta/offers/OFFER_ID' -d '{"offer": {"status":"suspended"}}'

Step 7: resume offer

curl -k -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:YOUR_SUBMISSION_API_KEY" 'http://testapi.adility.com/submission/beta/offers/OFFER_ID' -d '{"offer": {"status":"resumed"}}'

Step 8: get distribution report

General repor for last 5 dayst:

curl -k -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:YOUR_SUBMISSION_API_KEY" 'http://testapi.adility.com/submission/beta/vouchers?recently_changed=5'

Report by voucher:

curl -k -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:YOUR_SUBMISSION_API_KEY" 'http://testapi.adility.com/submission/beta/offers/OFFER_ID/vouchers'

Step 9: cancel the offer

curl -k -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:YOUR_SUBMISSION_API_KEY" 'http://testapi.adility.com/submission/beta/offers/OFFER_ID' -d '{"offer": {"status":"cancelled"}}'


Redeem voucher

For voucher redemption code samples please visit Voucher page.

Getting callback on offer change


To set your callback urls for sandbox and production you should contact us by skype or email api@adility.com.

NOTE: after you submit an offer our submission team should review it and either approve or reject. On sandbox submission team role is played by me and our engineers. So you need to let us know you want your offer be approved, etc. You can do that in chat or by email to api@adility.com.

Comments