Offer API Calls

If you are a premium WingCash member, you can create offers that distribute brand cash to customers. Use this API to list, find, and accept WingCash offers.

List Offers

GET /o/list

List the WingCash offers you have the permission to preview or edit.

Note

If you want to find offers you can purchase or accept, you probably want to Find Published Offers instead.

Permission Required:
 

preview_offer. See Permissions.

Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
Status Codes:
  • 200 OK

    Successful. The response body is a JSON object with these attributes:

    offers
    A list of OfferDetail objects.
    loop_links
    A mapping of loop_id to an object with title, thumbnail, and manage_url attributes. Contains information about all cash loops listed in offers.
  • 400 Bad Request – The parameters are not valid. The response body contains an InvalidRequest object.
  • 401 Unauthorized – The access token is missing, not valid, or the hard expiration has passed. See Unauthorized Response.
  • 403 Forbidden – The access token is valid but the app is not authorized to access this function.

Get Offer Info

GET /o/(string: offer_id)/info

Get info about a visible offer.

Permission Required:
 

None.

Status Codes:
  • 200 OK

    Successful. The response body is a JSON object with these attributes:

    offer
    An Offer object.
    loop_links
    A mapping of loop_id to an object with title and thumbnail attributes. Contains information about all cash loops provided by the offer.
  • 404 Not Found – No such offer exists.

Find Published Offers

GET /o/find

Find businesses providing published offers and list the offers they provide. You can limit by profile, chain, location, search text, and certain offer attributes.

Note

If the user interface you are building supports paging, the best way to use this API call depends on whether the UI shows businesses first or offers first. If the interface shows businesses first, use the limit and offset parameters. If the interface shows offers first, use the exclude_offer_ids parameter instead: for the second page, specify all the offers you showed on the first page; for the third page, specify all the offers you showed on the first and second pages; and so on.

Note

If you want to list offers you can preview or edit, you probably want to List Offers instead.

Permission Required:
 

None.

Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
  • text – Optional. Filter the results to offers that include the given text.
  • profile_ids – Optional. Limit the results to offers provided by any of the given businesses. Separate IDs using spaces.
  • chain_ids – Optional. Limit the results to offers provided by businesses in the specified chain(s). Separate IDs using spaces.
  • exclude_offer_ids – Optional. Exclude the specified offer IDs from the results. Separate IDs using spaces.
  • latitude – Optional. Find offers provided by businesses near the location specified by latitude and longitude. Both latitude and longitude must be specified together, or not at all. Optional.
  • longitude – Optional. See latitude.
  • max_distance – Optional. Limit results to businesses within a radius (in meters) of the latitude and longitude. Default: no limit.
  • if_require_confirmation – Optional. The value must be include, exclude, default, or an empty string. If the value is include, the results include offers that can be accepted only by WingCash members with confirmed contact information (such as a confirmed email address or SMS number.) If the value is exclude, the results only include offers with no confirmation requirement. The default is include for WingCash members with confirmed contact information and exclude otherwise.
  • limit – Optional. The maximum number of businesses to return. Default 10. Range 1 to 100.
  • offset – Optional. Skip the specified number of businesses. Default 0.
Status Codes:
  • 200 OK

    Successful. The response body is a JSON object with these attributes:

    profiles
    A list of OfferProfileResult objects. The profiles are ordered by distance (if a location is given), by search text relevance (if text was given but no location), or by profile title.
    offers
    A list of OfferSearchResult objects. The offers are in the same order as profiles, except that each offer is listed only once.
    loop_links
    A mapping of loop_id to an object with title and thumbnail attributes. Contains information about all cash loops listed in offers.
    more
    Boolean: true if the business profile result list was truncated by the limit or offset parameters.
  • 400 Bad Request – The parameters are not valid. The response body contains an InvalidRequest object.
  • 401 Unauthorized – The access token is missing, not valid, or the hard expiration has passed. See Unauthorized Response.
  • 403 Forbidden – The access token is valid but the app is not authorized to access this function.

Accept an Offer When Authenticated

POST /o/(string: offer_id)/accept

Accept an offer as an authenticated user.

Permission Required:
 

accept_offer. See Permissions.

Request Headers:
 
Form Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
  • option_id – Required. The ID of the payment option to accept. See the options attribute of Offer. The payment_type of the selected payment option must be wingcash, free, or funded; this call will currently return an error if the payment_type is paycard.
  • quantity – Optional. The number of purchases to accept. The default is 1. Limited by the offer’s show_limit attribute.
  • referrer_id – Optional. The ID of the profile who referred the purchaser.
  • private – Optional, either true or false. The default is true. If private is false, WingCash will create a public post about the offer purchase.
  • email – Required for offers that require confirmed contact information. If the member doesn’t already have confirmed email address, provide the member’s email address. If this is provided, WingCash will send a confirmation email to the specified address. (The email makes it possible for the user to access WingCash on other devices.)
  • appdata.* – Optional app-specific transfer data, one value per field. Replace the * with field names appropriate for your app. WingCash recommends you use an app-specific field name prefix, so if you choose myapp as a prefix and you want to store a transaction_id field, you should name your field appdata.myapp.transaction_id. All appdata values will be stored in the transfer and reflected in transfer lists and details. You may add a total of up to 10,000 characters (the total number of characters in keys and values) of appdata to a transfer.
  • dedup_id – Optional string (up to 128 characters) that helps prevent transfer duplication. Set it to a random string or some hash computed from the transfer parameters and current time. If WingCash receives multiple transfer requests from the same sender, with the same dedup_id, within 24 hours, WingCash will create only one transfer and respond with details about the same transfer to all affected requests. Once dedup_id is set appropriately, you can safely re-transmit the transfer request as needed.
Status Codes:
  • 200 OK

    Successful. The response body is a JSON object with these attributes:

    transfer
    A TransferDetail object.
    confirming
    Boolean: True only if WingCash sent a confirmation email and the user needs to finish accepting the offer by clicking the link in the email.
    profile
    The purchaser’s ProfileDetail object, updated to reflect the new amounts in the wallet. Provided only when confirming is false.
  • 400 Bad Request – The parameters are not valid, the quantity is too high, or the offer is not available. The response body contains an InvalidRequest object.
  • 401 Unauthorized – The access token is missing, not valid, or expiration has passed. See Unauthorized Response.
  • 503 Service Unavailable – The transfer could not be completed. The JSON response body contains error, error_description, and transfer, where transfer is a TransferDetail object detailing the transfer state.

Sign Up and Accept an Offer

POST /o/(string: offer_id)/signup_accept

Sign up and accept an offer.

WingCash will create a new individual member profile, add the accepted cash to the new profile, and return a new access token. The access token will have the following permissions:
  • accept_offer
  • manage_sent
  • mobile_device
  • send_cash
  • view_history
  • view_wallet
Permission Required:
 

None.

Request Headers:
 
Form Parameters:
 
  • version – Optional. If provided, must be 1.
  • option_id – Required. The ID of the payment option to accept. See the options attribute of Offer. The payment_type of the selected payment option must be wingcash, free, or funded; this call will currently return an error if the payment_type is paycard.
  • quantity – Optional. The number of purchases to accept. The default is 1. Limited by the offer’s show_limit attribute.
  • referrer_id – Optional. The ID of the profile who referred the purchaser.
  • private – Optional, either true or false. The default is true. If private is false, WingCash will create a public post about the offer purchase.
  • first_name – Required. The new member’s first name. The first name must be no longer than 50 characters and must start with a letter. Certain Unicode symbols (such as 0x2000 through 0x2fff) are disallowed. Do not use the name of a business as the first or last name.
  • last_name – Required. The new member’s last name. The last name must be no longer than 50 characters and must start with a letter. Certain Unicode symbols (such as 0x2000 through 0x2fff) are disallowed. Do not use the name of a business as the first or last name.
  • business_name – Optional. The name of a business owned by the new member. This field exists to help new members avoid making the mistake of entering a business name in the first and last name fields. If a new member wants to add a business, the member must first create an individual profile with the member’s personal name; WingCash will later prompt the member to add a business. The business name must be no longer than 100 characters. The name may contain most Unicode symbols.
  • app_id – Required. The ID of the app that is creating the profile. The app ID is also known as the client ID. The app must be public in order to use this API call.
  • pin – Required 4 digit string. New members must set their own PIN. The user interface that inputs the PIN should require the user to enter the PIN twice for confirmation. (The PIN is needed for access token renewal. Do not store the PIN.)
  • device_name – Required. The human readable name of the device and/or app the member is using.
  • device_uuid – Required. A unique identifier of the device or app the member is using. A standard 36 character random UUID is best, but other kinds of alphanumeric identifiers are also accepted. Maximum 36 characters.
  • email – Required for offers that require confirmed contact information. Provide the new member’s email address. If this is provided, WingCash will send a confirmation email to the specified address. (The email makes it possible for the user to access WingCash on other devices.)
  • agreed_terms_and_privacy – Required, must be true. This indicates the new member has agreed to the WingCash member agreement and privacy policy. All user interfaces must ask new members to review the member agreement and privacy policy and indicate their acceptance. Additionally, user interfaces must ask new members to confirm they are at least 18 years of age and that they live in the United States.
  • weekly_offers – Optional, either true or false. The default is true. Indicates whether the new member would like to receive weekly WingCash offers by email.
Status Codes:
  • 200 OK

    Successful. The response body is a JSON object with these attributes:

    transfer
    A TransferDetail object.
    confirming
    Boolean: True only if WingCash sent a confirmation email and the user needs to finish accepting the offer by clicking the link in the email.
    profile
    The purchaser’s ProfileDetail object, updated to reflect the new amounts in the wallet. Provided only when confirming is false.
    token
    An AccessTokenInfo object. Provided only when confirming is false.
  • 400 Bad Request – The parameters are not valid, the quantity is too high, or the offer is not available. The response body contains an InvalidRequest object.
  • 401 Unauthorized – The access token is missing, not valid, or expiration has passed. See Unauthorized Response.
  • 503 Service Unavailable – The transfer could not be completed. The JSON response body contains error, error_description, and transfer, where transfer is a TransferDetail object detailing the transfer state.