API DOCUMENTATION Last Update: Apr 2022

Create New BuyX Campaign Item

Add a new item to an existing "Buy X Get 1 Free" campaign.


The data to be submitted to the API is composed of the following fields:


  field   Example   Note
user_id john1970 Required
user_password 1959caadac9b13dcb3 Required
type campaign_new Required
action item Required
account_id greatwidgets Required
campaign_id 1234567890123456 Required
reward_level 10 Required
item_description Coffee or Tea Required
item_identifier 1DF34S1 Optional
Output Format:
output JSON or XML Optional. If not provided, defaults to XML
callback someFunctionName Optional: JSONP format
condensed yes Optional (No white space)
Applies only to JSON(P) output



  • The ability to create items is based on the permissions of the user_id that is making the call.
  • Only one item can be added at a time. Loop this call in your program to add multiple items at the same time.
  • This call applies only to Buy X Get 1 Free campaigns.
  • The reward_level is the quantity of items that need to be purchased before the next one is free.
  • The item_identifier is an optional field that lets you specify an item ID such as a SKU.


    Example PHP Request:

    If you are using PHP, the $data array would look like this:

    1. $data['user_id'] = 'john1970';
    2. $data['user_password'] = '1959caadac9b13dcb3';
    3. $data['type'] = 'campaign_new';
    4. $data['action'] = 'item';
    5. $data['account_id'] = 'greatwidgets';
    6. $data['campaign_id'] = '1234567890123456';
    7. $data['reward_level'] = '10';
    8. $data['item_description'] = 'Coffee or Tea';
    9. $data['item_identifier'] = '1DF345S1';


    Success XML Response:

    1. <response status="success">
    2. <campaign>
    3. <item>
    4. <id>14</id>
    5. </item>
    6. </campaign>
    7. </response>


    • A successful result will return the item_id of the item. This id can also be retrieved with the Campaign - List BuyX Items API call.


    Error XML Response:

    1. <response status="error">
    2. <error>Error message</error>
    3. </response>