Find Promo Code
Uri: https://test-api.finerworks.com/v3/find_promo_code
Method: POST

Used to get both gift cards balances and promo details. Only authorized accounts may use this endpoint.


Body

NameDescriptionTypeAdditional information
code

Promo code or gift card code

text

Required

email_address

Optional - Should include if it the coupon is assigned to a specific email account.

text

None.

account_key

Optional - User account associated with the request. Note, this will only be accepted for accounts with permission to utilize this parameter, otherwise it will be ignored and the request will based upon the user's api credentials. Leave as null if not authorized to use this parameter.

text

None.

Example JSON Body

application/json, text/json

{
  "code": "sample string 1",
  "email_address": "sample string 2",
  "account_key": "sample string 3"
}

Sample Code Library


                        
curl --location --request sample_method 'https://test-api.finerworks.comsample_endpoint' \
--header 'Content-Type: application/json' \
--header 'web_api_key: my-web-api-key-goes-here' \
--header 'app_key: my-app-key-goes-here' \
--data-raw '{
  "code": "sample string 1",
  "email_address": "sample string 2",
  "account_key": "sample string 3"
}'
                            
                        


require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://test-api.finerworks.comsample_endpoint');
$request->setMethod(HTTP_Request2::METHOD_sample_method);
$request->setConfig(array(
'follow_redirects' => TRUE
));
$request->setHeader(array(
'Content-Type' => 'application/json',
'web_api_key' => 'my-web-api-key-goes-here',
'app_key' => 'my-app-key-goes-here'
));
$request->setBody('{
  'code': 'sample string 1',
  'email_address': 'sample string 2',
  'account_key': 'sample string 3'
}');
try {
$response = $request->send();
if ($response->getStatus() == 200) {
echo $response->getBody();
}
else {
echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
$response->getReasonPhrase();
}
}
catch(HTTP_Request2_Exception $e) {
echo 'Error: ' . $e->getMessage();
}

                        


var client = new RestClient("https://test-api.finerworks.comsample_endpoint");
client.Timeout = -1;
var request = new RestRequest(Method.sample_method);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("web_api_key", "my-web-api-key-goes-here");
request.AddHeader("app_key", "my-app-key-goes-here");
request.AddParameter("application/json", "{
  'code': 'sample string 1',
  'email_address': 'sample string 2',
  'account_key': 'sample string 3'
},  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

                        


var settings = {
"url": "https://test-api.finerworks.comsample_endpoint",
"method": "sample_method",
"timeout": 0,
"headers": {
"Content-Type": "application/json",
"web_api_key": "my-web-api-key-goes-here",
"app_key": "my-app-key-goes-here"
},
"data": JSON.stringify({
  'code': 'sample string 1',
  'email_address': 'sample string 2',
  'account_key': 'sample string 3'
}),
};

$.ajax(settings).done(function (response) {
console.log(response);
});

                        

                        
var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
'method': 'sample_method',
'hostname': 'v2.api.finerworks.com',
'path': 'sample_endpoint',
'headers': {
'Content-Type': 'application/json',
'web_api_key': 'my-web-api-key-goes-here',
'app_key': 'my-app-key-goes-here'
},
'maxRedirects': 20
};

var req = https.request(options, function (res) {
var chunks = [];

res.on("data", function (chunk) {
chunks.push(chunk);
});

res.on("end", function (chunk) {
var body = Buffer.concat(chunks);
console.log(body.toString());
});

res.on("error", function (error) {
console.error(error);
});
});

var postData = JSON.stringify({
  "code": "sample string 1",
  "email_address": "sample string 2",
  "account_key": "sample string 3"
});

req.write(postData);

req.end();
                            
                        

                        
    require "uri"
    require "net/http"

    url = URI("https://test-api.finerworks.comsample_endpoint")

    https = Net::HTTP.new(url.host, url.port)
    https.use_ssl = true

    request = Net::HTTP::sample_method.new(url)
    request["Content-Type"] = "application/json"
    request["web_api_key"] = "my-web-api-key-goes-here"
    request["app_key"] = "my-app-key-goes-here"
    request.body = "{
  'code': 'sample string 1',
  'email_address': 'sample string 2',
  'account_key': 'sample string 3'
}"

    response = https.request(request)
    puts response.read_body


                        

NameDescriptionTypeAdditional information
promo

promo

None.

status

response_status

None.

Example JSON Response

application/json, text/json

{
  "promo": {
    "id": 1,
    "status": 0,
    "key": "sample string 2",
    "expires": "2026-03-23T04:26:00.4121495-05:00",
    "title": "sample string 3",
    "comments": "sample string 4",
    "balance": 5.0,
    "email_assigned": "sample string 6",
    "message": "sample string 7"
  },
  "status": {
    "success": true,
    "status_code": 100,
    "message": "sample string 2",
    "debug": {},
    "reference_id": "sample string 4",
    "domain": "sample string 5"
  }
}