Estimate Giftcard

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    front_image_url: 'https://cdn.thanks.io/notecard-inspirations/note1.png',
    message: 'Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!',
    handwriting_style_id: 4,
    giftcard_brand: 'amazonus',
    giftcard_amount_in_cents: 10000,
    recipients: [
      {
        name: 'Current Resident',
        address: '123 Main Street',
        city: 'Fake City',
        province: 'NY',
        postal_code: '55555',
        country: 'US',
        custom1: 'Example Custom 1',
        custom2: 'Example Custom 2',
        custom3: 'Example Custom 3',
        custom4: 'Example Custom 4'
      },
      {
        name: 'Jane Doe',
        address: '456 Another St',
        city: 'Fake City',
        province: 'NY',
        postal_code: '55555',
        country: 'US'
      }
    ]
  })
};

fetch('https://api.thanks.io/api/v2/estimate/giftcard', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://api.thanks.io/api/v2/estimate/giftcard \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "front_image_url": "https://cdn.thanks.io/notecard-inspirations/note1.png",
  "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!",
  "handwriting_style_id": 4,
  "giftcard_brand": "amazonus",
  "giftcard_amount_in_cents": 10000,
  "recipients": [
    {
      "name": "Current Resident",
      "address": "123 Main Street",
      "city": "Fake City",
      "province": "NY",
      "postal_code": "55555",
      "country": "US",
      "custom1": "Example Custom 1",
      "custom2": "Example Custom 2",
      "custom3": "Example Custom 3",
      "custom4": "Example Custom 4"
    },
    {
      "name": "Jane Doe",
      "address": "456 Another St",
      "city": "Fake City",
      "province": "NY",
      "postal_code": "55555",
      "country": "US"
    }
  ]
}
'

import requests

url = "https://api.thanks.io/api/v2/estimate/giftcard"

payload = {
    "front_image_url": "https://cdn.thanks.io/notecard-inspirations/note1.png",
    "message": "Hey %FIRST_NAME%!,

THANK YOU for allowing us the opportunity to HELP you with your plan!",
    "handwriting_style_id": 4,
    "giftcard_brand": "amazonus",
    "giftcard_amount_in_cents": 10000,
    "recipients": [
        {
            "name": "Current Resident",
            "address": "123 Main Street",
            "city": "Fake City",
            "province": "NY",
            "postal_code": "55555",
            "country": "US",
            "custom1": "Example Custom 1",
            "custom2": "Example Custom 2",
            "custom3": "Example Custom 3",
            "custom4": "Example Custom 4"
        },
        {
            "name": "Jane Doe",
            "address": "456 Another St",
            "city": "Fake City",
            "province": "NY",
            "postal_code": "55555",
            "country": "US"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "message": "OK",
  "data": {
    "type": "giftcard",
    "size": null,
    "total_recipients": 2,
    "recipients": {
      "united_states": 2,
      "international": 0
    },
    "pending_email_lookups": 0,
    "costs_in_cents": {
      "united_states": 236,
      "international": 0,
      "additional_pages": 0,
      "giftcard_face_value": 20000,
      "grand_total": 236
    },
    "total_cost_in_cents": 20236,
    "total_cost": "$202.36",
    "current_balance_in_cents": 5000,
    "covered_by_balance": false,
    "test_mode": false,
    "notes": []
  }
}

{
  "message": "Sub Account ID does not exist"
}

{
  "message": "Unauthorized"
}

{
  "status": "Gift card sends require a paid plan. This account is on the free plan — upgrade in the thanks.io dashboard, or send a postcard, letter, notecard or magnacard instead.",
  "message": "Gift card sends require a paid plan. This account is on the free plan — upgrade in the thanks.io dashboard, or send a postcard, letter, notecard or magnacard instead.",
  "error": "Gift card sends require a paid plan. This account is on the free plan — upgrade in the thanks.io dashboard, or send a postcard, letter, notecard or magnacard instead.",
  "errors": [
    "Gift card sends require a paid plan. This account is on the free plan — upgrade in the thanks.io dashboard, or send a postcard, letter, notecard or magnacard instead."
  ],
  "failure": true,
  "code": "giftcards_require_paid_plan"
}

Order Estimates

Estimate Giftcard

Price a giftcard order without placing it. Send the same request body you would send to Send Giftcard: nothing is charged, nothing is printed or mailed, and no order is created.

The request is validated exactly as the send is, so a payload the send would reject is rejected here too. Recipients with only an email address are priced as if the email-to-address lookup finds them, and counted in pending_email_lookups. A radius_search is counted and priced, but no records are purchased.

Gift card face value is included in costs_in_cents.giftcard_face_value and in total_cost_in_cents. On paid plans, a card’s face value is charged only when the recipient redeems it, so for a gift card order total_cost_in_cents is the most the order can cost, and costs_in_cents.grand_total is what is charged when you send. Accounts that can’t send gift cards receive a 402 with the code giftcards_require_paid_plan, the same response the send returns.

POST

estimate

giftcard

Estimate Giftcard

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    front_image_url: 'https://cdn.thanks.io/notecard-inspirations/note1.png',
    message: 'Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!',
    handwriting_style_id: 4,
    giftcard_brand: 'amazonus',
    giftcard_amount_in_cents: 10000,
    recipients: [
      {
        name: 'Current Resident',
        address: '123 Main Street',
        city: 'Fake City',
        province: 'NY',
        postal_code: '55555',
        country: 'US',
        custom1: 'Example Custom 1',
        custom2: 'Example Custom 2',
        custom3: 'Example Custom 3',
        custom4: 'Example Custom 4'
      },
      {
        name: 'Jane Doe',
        address: '456 Another St',
        city: 'Fake City',
        province: 'NY',
        postal_code: '55555',
        country: 'US'
      }
    ]
  })
};

fetch('https://api.thanks.io/api/v2/estimate/giftcard', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://api.thanks.io/api/v2/estimate/giftcard \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "front_image_url": "https://cdn.thanks.io/notecard-inspirations/note1.png",
  "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!",
  "handwriting_style_id": 4,
  "giftcard_brand": "amazonus",
  "giftcard_amount_in_cents": 10000,
  "recipients": [
    {
      "name": "Current Resident",
      "address": "123 Main Street",
      "city": "Fake City",
      "province": "NY",
      "postal_code": "55555",
      "country": "US",
      "custom1": "Example Custom 1",
      "custom2": "Example Custom 2",
      "custom3": "Example Custom 3",
      "custom4": "Example Custom 4"
    },
    {
      "name": "Jane Doe",
      "address": "456 Another St",
      "city": "Fake City",
      "province": "NY",
      "postal_code": "55555",
      "country": "US"
    }
  ]
}
'

import requests

url = "https://api.thanks.io/api/v2/estimate/giftcard"

payload = {
    "front_image_url": "https://cdn.thanks.io/notecard-inspirations/note1.png",
    "message": "Hey %FIRST_NAME%!,

THANK YOU for allowing us the opportunity to HELP you with your plan!",
    "handwriting_style_id": 4,
    "giftcard_brand": "amazonus",
    "giftcard_amount_in_cents": 10000,
    "recipients": [
        {
            "name": "Current Resident",
            "address": "123 Main Street",
            "city": "Fake City",
            "province": "NY",
            "postal_code": "55555",
            "country": "US",
            "custom1": "Example Custom 1",
            "custom2": "Example Custom 2",
            "custom3": "Example Custom 3",
            "custom4": "Example Custom 4"
        },
        {
            "name": "Jane Doe",
            "address": "456 Another St",
            "city": "Fake City",
            "province": "NY",
            "postal_code": "55555",
            "country": "US"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "message": "OK",
  "data": {
    "type": "giftcard",
    "size": null,
    "total_recipients": 2,
    "recipients": {
      "united_states": 2,
      "international": 0
    },
    "pending_email_lookups": 0,
    "costs_in_cents": {
      "united_states": 236,
      "international": 0,
      "additional_pages": 0,
      "giftcard_face_value": 20000,
      "grand_total": 236
    },
    "total_cost_in_cents": 20236,
    "total_cost": "$202.36",
    "current_balance_in_cents": 5000,
    "covered_by_balance": false,
    "test_mode": false,
    "notes": []
  }
}

{
  "message": "Sub Account ID does not exist"
}

{
  "message": "Unauthorized"
}

{
  "status": "Gift card sends require a paid plan. This account is on the free plan — upgrade in the thanks.io dashboard, or send a postcard, letter, notecard or magnacard instead.",
  "message": "Gift card sends require a paid plan. This account is on the free plan — upgrade in the thanks.io dashboard, or send a postcard, letter, notecard or magnacard instead.",
  "error": "Gift card sends require a paid plan. This account is on the free plan — upgrade in the thanks.io dashboard, or send a postcard, letter, notecard or magnacard instead.",
  "errors": [
    "Gift card sends require a paid plan. This account is on the free plan — upgrade in the thanks.io dashboard, or send a postcard, letter, notecard or magnacard instead."
  ],
  "failure": true,
  "code": "giftcards_require_paid_plan"
}

Authorizations

Authorization

string

header

required

Bearer token authentication using your thanks.io API key

Body

application/json

preview

boolean

Set to true to return a preview instead of sending the mail piece. You can use this with any send call to inspect the output before submitting the order.

Example:

true

mailing_list_ids

integer[]

Mailing list IDs to send to. Required if recipients and radius_search are not provided.

Example:

[5166, 514]

recipients

(Create Recipient by Address · object | Create Recipient by Email · object)[]

Recipients to send to. Required if mailing_list_ids and radius_search are not provided.

Create a recipient by providing address details

Create Recipient by Address
Create Recipient by Email

Show child attributes

radius_search

object

Use a radius search to find recipients near an address. Required if mailing_list_ids and recipients are not provided. Lookup fees are $0.05 per record.

Show child attributes

handwriting_style_id

integer

ID of handwriting style to use.

Example:

4

handwriting_color

enum<string>

Handwriting color to use. Options are preset named colors or specified as hex format, such as '#4287f5'

Available options:

blue,

black,

green,

purple,

red

Examples:

"blue"

"#4287f5"

handwriting_realism

boolean

Set to true to enable the realism effect for AI fonts.

Example:

true

sub_account

integer

Sub-account ID to use for this order.

Example:

7

notification_emails

string

Optional comma-separated list of email addresses to notify about order events such as QR scan notifications.

Example:

"ops@example.com,sales@example.com"

postage_class

enum<string>

Postage class for this order. first_class mails First Class. standard mails Standard Mail (also known as Marketing Mail): lower cost for US addresses and slower to deliver, with no tracking status and no return-to-sender. Omit it to use your account's default, set with Standard Mail Mode under Settings > Mail Preferences. Standard Mail only changes the price of US addresses. Nonprofit accounts always mail at their nonprofit rate. standard needs a paid plan: free plan accounts always mail First Class, and standard from one is rejected with a 422.

Available options:

first_class,

standard

Example:

"standard"

return_name

string

Custom return name for the order.

Example:

"Custom Return"

return_address

string

Custom return address for the order.

Example:

"1 Main Street"

return_address2

string

Custom return address line 2 for the order.

Example:

"Unit 1"

return_city

string

Custom return city for the order.

Example:

"Woodbridge"

return_state

string

Custom return state/province for the order.

Example:

"NJ"

return_postal_code

string

Custom return postal code for the order.

Example:

"07095"

metadata

object | null

Your own key/value data to store with the order. It is returned unchanged by the order endpoints and included in every webhook event for the order as order.metadata. Must be a JSON object rather than an array, and no larger than 8,192 bytes once encoded as JSON. thanks.io does not print or otherwise act on these values.

Example:

{
  "crm_deal_id": "D-1042",
  "campaign": "spring-winback",
  "source": "hubspot"
}

creative_id

integer

Recommended: send a saved creative instead of assembling image and message parameters per request. ID of a creative from your Creatives library (see List Creatives). The creative is sent exactly as saved: its image template, message template, handwriting and background all come from it. It cannot be combined with any parameter that changes those (image_template_id, message_template_id, front_image_url, message, the handwriting and custom background parameters, pdf_only_url, skip_creative_generation, or for gift cards giftcard_brand and giftcard_amount_in_cents); a request that does is rejected with a 422 naming them. Only qrcode_url and additional_pages_url can be added. The creative must belong to your account, be of the mailer type being sent (for postcards, the size being sent), and be complete (is_complete: true).

Example:

501

image_template_id

integer

ID of image template to use for the exterior of the giftcard. Required if not front_image_url is specified.

Example:

6

front_image_url

string

URL to image to use for the exterior of the giftcard. Required if image_template_id is not specified.

Example:

"https://cdn.thanks.io/notecard-inspirations/note1.png"

message

string

Handwritten message content to use for interior of giftcard.

Example:

"Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!"

message_template_id

integer

ID of message template to use for interior of giftcard.

Example:

12

giftcard_brand

string

Brand of giftcard to use. Must be one of the supported brands. The /giftcard-brands endpoint can be used to retrieve a list of supported brands. Leave this out when sending a creative_id: a gift card creative carries its own brand and amount, and passing this with it is rejected with a 422.

Example:

"amazonus"

giftcard_amount_in_cents

integer

Amount of giftcard in cents. The /giftcard-brands endpoint can be used to retrieve a list of supported amounts by brand. Leave this out when sending a creative_id: a gift card creative carries its own brand and amount, and passing this with it is rejected with a 422.

Example:

10000

Response

The order was priced. Nothing was charged and no order was created.

message

string

Example:

"OK"

data

object

Show child attributes

Get Started

Authentication

API Endpoints

Examples

Estimate Giftcard

Authorizations

Body

Response