API Docs

By using this API you will have full access to the same range of features found in our apps and website.

1. API ENDPOINTS

The production API can be found at https://api.simplynoted.com/api

The test API can be found at https://testapi.simplynoted.com/api

All endpoints listed in this documentation refer to those base URLs and build off them. For example, the orders endpoint "/orders" can be found at the endpoint: https://api.simplynoted.com/api/orders

2. AUTHENTICATION

2.1. Retrieve Auth Token

Description: Simply Noted uses API keys as bearer tokens to allow access to the API. You can get your API key from
 page under "Account Details". Simply Noted expects for the API key to be included in all API requests to the server in a header that looks like the following: Authorization: Bear

3. USERS

3.1. Create A User

Description: Users are created through the Simply Noted website.
To create an account go tohttps://simplynoted.com/account/register.

4. PRODUCTS

4.1. Get Standard Cards

Description:This endpoint gets all standard cards and returns the id, title, and image URL.

Endpoint: /products

Method: GET

Headers:

NameValueRequired?
Content-Typeapplication/json$Yes
AuthorizationBearer TOKEN_HEREYes

Returns on success:

{
  "result": [
    {
      "id": 4392451768425,
      "title": "Cactus Thank you",
      "image": "https://cdn.shopify.com/s/files/1/0275/6457/2777/products/Cactus-Thank-You.jpg?v=1574659292"
    },
    {
      "id": 4392452522089,
      "title": "Cactus Thanks So Much",
      "image": "https://cdn.shopify.com/s/files/1/0275/6457/2777/products/Cactus-Thanks-So-Much.jpg?v=1574659363"
    },
    {
      "id": 4442013139049,
      "title": "Dark Red Holiday Card",
      "image": "https://cdn.shopify.com/s/files/1/0275/6457/2777/products/Red.HolidayCard.jpg?v=1576524937"
    }
  ],
  "errors": []
}

4.2. Get All Custom Cards

Description: This endpoint will retrieve a list of custom cards, returning up to 200 cards for each call.

Endpoint: /customProducts

Get: https://api.simplynoted.com/api/customProducts?offset=0

MethodURL Parameters
GEThttps://api.simplynoted.com/api/customProducts?offset=0offset – Default/Initial value = 0. You will get the next offset value, if any, in response as nextOffset if moreProducts is true. If moreProducts is false, nextOffset will not be returned.

Response Sample

{
  "result": {
    "products": [
      {
        "id": 7050968727657,
        "title": "double click",
        "image": "https://cdn.shopify.com/s/files/1/0275/6457/2777/products/1696329730810.png?v=1696329732",
        "type": "customisable card",
        "createdAt": "2023-10-03T03:42:12-07:00",
        "updatedAt": "2023-10-03T03:42:13-07:00"
      }
    ],
    "nextOffset": 200,
    "moreProducts": true
  },
  "errors": []
}

4.3. Get Specific Custom Cards

This procedure returns details on one or more custom cards.

Example: /customProducts?productIds=7036997894249,7036977578089,7036976889961

Where the IDs are existing custom card IDs separated by commas.

4.4. Create Custom Card

Note:The old endpoint, /createcustomcard, and its associated endpoint, /uploadPDF, have been replaced with a single new endpoint: /createcard. The old endpoints will remain usable until November 1, 2023, at which point they will be retired. We strongly recommend you switch to the new endpoint, /createcard. As well, we have released a new endpoint /modifycard, which will allow you to call an existing flat custom card,

Description: This endpoint creates a new Custom Card and returns card details.

Endpoint: /createCard

Method: POST

Headers

NameValueRequired?
Content-Typeapplication/json$Yes
AuthorizationBearer TOKEN_HEREYes

Body:

NameValueRequired?Example
Content-Typeapplication/json$Yes
cardNameStringYes "Happy Birthday"
cardTypeStringYes “flat5x7” / “folded5x7”
frontImageFileYes.
isHeaderIncluded BooleanYestrue
isFooterIncluded BooleanYestrue
headerStringYes { isImage": true }
footerStringYes{ "data": "Yours Sincerely","textAlign": "left","justifyContent": "center","flexDirection": "column","fontType": "Courier New","fontSize": 30,"fontColor": "rgb(255, 0, 0)","zoom": "1","isImage": false }
headerImageFileNo
footerImageFileNo
backImageFileNo.

Return on Success:

{
  "result": {
    "product": {
      "id": 7046027575401,
      "title": "Testing Cards",
      "body_html": null,
      "vendor": "SimplyNoted",
      "product_type": "customisable card",
      "created_at": "2023-09-13T06:22:28-07:00",
      "handle": "testing-cards",
      "updated_at": "2023-09-13T06:22:29-07:00",
      "published_at": "2023-09-13T06:22:28-07:00",
      "template_suffix": null,
      "published_scope": "web",
      "tags": "customise_card",
      "status": "active",
      "admin_graphql_api_id": "gid://shopify/Product/7046027575401",
      "images": [
        {
          "id": 30856642232425,
          "product_id": 7046027575401,
          "position": 1,
          "created_at": "2023-09-13T06:22:28-07:00",
          "updated_at": "2023-09-13T06:22:28-07:00",
          "alt": "front_img",
          "width": 495,
          "height": 350,
          "src": "https://cdn.shopify.com/s/files/1/0275/6457/2777/products/1694611344453.jpg?v=1694611348",
          "variant_ids": [],
          "admin_graphql_api_id": "gid://shopify/ProductImage/30856642232425"
        }
      ],
      "image": {
        "id": 30856642232425,
        "product_id": 7046027575401,
        "position": 1,
        "created_at": "2023-09-13T06:22:28-07:00",
        "updated_at": "2023-09-13T06:22:28-07:00",
        "alt": "front_img",
        "width": 495,
        "height": 350,
        "src": "https://cdn.shopify.com/s/files/1/0275/6457/2777/products/1694611344453.jpg?v=1694611348",
        "variant_ids": [],
        "admin_graphql_api_id": "gid://shopify/ProductImage/30856642232425"
      }
    }
  },
  "errors": []
}

Example

{
  "cardName": "Happy Birthday",
  "cardType": "flat5x7",
  "frontImage": "1",
  "isHeaderIncluded": true,
  "isFooterIncluded": true,
  "header": {
    "isImage": true
  },
  "footer": {
    "data": "Yours Sincerely",
    "textAlign": "left",
    "justifyContent": "center",
    "flexDirection": "column",
    "fontType": "Trebuchet MS",
    "fontSize": 20,
    "fontColor": "rgb(0, 0, 255)",
    "zoom": "1",
    "isImage": false
  },
  "headerImage": "",
  "footerImage": "",
  "backImage": ""
}

Error:

StatusErrors
400cardType, cardName & frontImage are required fields
400headerImage is required when header has isImage true
400footerImage is required when footer has isImage true
400For flat cardType, isHeaderIncluded, isFooterIncluded, header, and footer are required fields

4.5. Modify Custom Card

Description: This endpoint creates and saves a new modified Custom Card and returns card details.

Endpoint: /modifyCard

Method: POST

Headers:

NameValueRequired?
Content-Typeapplication/jsonYes
AuthorizationBearer TOKEN_HEREYes

Body:

KeyType/ValuesRequired?Example
originalCustomCardIDString Yes7046020595817
cardNameStringYes "Happy Birthday Modified 1a"
isHeaderIncluded BooleanYes true
isFooterIncludedBooleanYestrue
header StringYes"isImage": true
footer StringYes{ "data": "Yours Sincerely","textAlign": "left","justifyContent": "center","flexDirection": "column","fontType": "Courier New","fontSize": 30,"fontColor": "rgb(255, 0, 0)","zoom": "1","isImage": false }
headerImageFileNo
footerImageFileNo

Returns on success:

{
  "result": {
    "product": {
      "id": 7046027575401,
      "title": "Testing Cards",
      "body_html": null,
      "vendor": "SimplyNoted",
      "product_type": "customisable card",
      "created_at": "2023-09-13T06:22:28-07:00",
      "handle": "testing-cards",
      "updated_at": "2023-09-13T06:22:29-07:00",
      "published_at": "2023-09-13T06:22:28-07:00",
      "template_suffix": null,
      "published_scope": "web",
      "tags": "customise_card",
      "status": "active",
      "admin_graphql_api_id": "gid://shopify/Product/7046027575401",
      "variants": [
        {
          "id": 40730910490729,
          "product_id": 7046027575401,
          "title": "2 - 500"
        },
        {
          "id": 40730910523497,
          "product_id": 7046027575401,
          "created_at": "2023-09-13T06:22:28-07:00",
          "updated_at": "2023-09-13T06:22:28-07:00",
          "inventory_item_id": 42829245415529,
          "admin_graphql_api_id": "gid://shopify/ProductVariant/40730910523497"
        },
        {
          "id": 40730910556265,
          "product_id": 7046027575401
        }
      ]
    }
  },
  "errors": []
}

Example

{
  "cardName": "Happy Birthday Modified 1a",
  "originalCustomCardID": "123123213123",
  "isHeaderIncluded": true,
  "isFooterIncluded": true,
  "header": {
    "isImage": true
  },
  "footer": {
    "data": "Yours Sincerely",
    "textAlign": "left",
    "justifyContent": "center",
    "flexDirection": "column",
    "fontType": "Trebuchet MS",
    "fontSize": 20,
    "fontColor": "rgb(0, 0, 255)",
    "zoom": "1",
    "isImage": false
  },
  "headerImage": "",
  "footerImage": ""
}

4.6. Delete Custom Cards

DELETE - /delete-custom-card?productId=7072904347753,7073022279785,123456789000

This endpoint can be used to delete one or more custom cards belonging to the user.

MethodURLParameters
DELETE/delete-custom-card?productId=7072904347753,7073022279785,123456789000productId - productId contains

Response Sample

{
  "result": {
    "successfulDeletions": [
      "7072904347753",
      "7073022279785"
    ],
    "failedDeletions": [
      123456789000
    ]
  },
  "errors": []
}

5. ORDERS

5.1. Create An Order

Description: This endpoint creates and saves a new modified Custom Card and returns card details.

Endpoint: /orders

Method: POST

Headers:

NameValueRequired?
Content-Typeapplication/json$Yes
AuthorizationBearer TOKEN_HEREYes

Body:

KeyTypeRequired?Example
productIdString$Yes"4392452522089"
giftVariantIdStringNo"39532031672425" (Note: See below for more)
handwritingStyleStringYes"Tarzan"
customMessage StringYes"This is my custom message.Use a hard return for a new line."
signoff StringNo"Yours Sincerely,David"
shippingDateString No"01/01/2020"
returnAddressIdStringNo"ID_OF_RETURN_ADDRESS"
returnAddressObject Return ObjectYesSee Below
recipientDataArray Recipient ObjectYesSee Below

Recipient Object:

KeyTypeRequired?Example
FirstNameString$Yes"John"
LastNameString Yes"Appleseed"
EmailStringNo"john@simplynoted.com"
Phone StringNo "+15555551234"
Address StringYes"123 S Street"
Address 2String No"Suite 100"
City StringYes"Metropolis"
State StringYes"Smallville"
Country StringNo"USA"
ZipStringYes"12345"
CompanyStringNo"ACME, Inc."
Custom 1StringNo"My custom value"
Custom 2 StringNo"Another Ccustom value"
Custom 3StringNo"And A third"

Recipient Object:

KeyTypeRequired?Example
FirstNameString$Yes"John"
LastNameString Yes"Appleseed"
EmailStringNo"john@simplynoted.com"
Phone StringNo "+15555551234"
Address StringYes"123 S Street"
Address 2String No"Suite 100"
City StringYes"Metropolis"
State StringYes"Smallville"
Country StringNo"USA"
ZipStringYes"12345"
CompanyStringNo"ACME, Inc."
Custom 1StringNo"My custom value"
Custom 2 StringNo"Another Ccustom value"
Custom 3StringNo"And A third"

Returns on success:

{
  "result": "Order created.",
  "errors": []
}

Example:

{
  "productId": "ID_OF_PRODUCT_YOU_ARE_ORDERING",
  "handwritingStyle": "Tarzan",
  "customMessage": "This is my custom message",
  "signoff": "Yours Sincerely",
  "shippingDate": "",
  "templateId": "ID_OF_THE_TEMPLATE_YOU_WANT_TO_USE",
  "recipientData": [
    {
      "First Name": "John",
      "Last Name": "Appleseed",
      "Address": "123 S Street",
      "Address 2": "",
      "City": "Metropolis",
      "State": "Smallville",
      "Zip": "12345",
      "Phone": "+15555551234",
      "Email": "john@simplynoted.com",
      "Company": "ACME, Inc.",
      "Custom 1": "",
      "Custom 2": "",
      "Custom 3": ""
    }
  ]
}
Types of Gift Cards:

1. Starbucks Gift Card

VariantID
$5 for $7.95 "39532032786537"
$10 for $12.95"39532032819305"
$25 for $27.95"39532032852073"
$50 for $52.95"39532032884841"

2. Amazon Gift Card

VariantID
$5 for $7.95"39532031672425"
$10 for $12.95"39532031705193"
$25 for $27.95"39532031737961"

3. Visa Gift Card

VariantID
$5 for $7.95"39532033146985"
$10 for $12.95"39532033179753"
$25 for $27.95"39532033212521"

4. Home Depot Gift Card

VariantID
$5 for $7.95"39532029378665"
$10 for $12.95"39532029411433"
$25 for $27.95"39532029444201"
$25 for $27.95"39532029476969"

5. Lowe’s Gift Card

VariantID
$5 for $7.95"39532032262249"
$10 for $12.95"39532032295017"
$25 for $27.95"39532032327785"
$25 for $27.95"39532032360553"

5.2. Get Orders

Description: This endpoint gets all orders in the account.

Endpoint:/orders/customer/?offset=0&status=any&fulfillment_status=shipped

Method: GET

Headers:

NameValueRequired?
Content-Typeapplication/jsonYes
AuthorizationBearer TOKEN_HEREYes

Body:

KeyTypeRequired?Example
offsetNumberYes0 This call will pull up to 200 orders starting with the most recent. The initial call should use 0 as the offset. In the return, you will see: moreOrders: “true/false” If true, then there are more orders to fetch. You will also see: nextOffset “200” (This gives you the correct offset for the following call.)
statusStringNoFilter orders by their status. status = default = open open: Show only open orders. closed: Show only closed orders. cancelled: Show only cancelled orders. any: Show all orders, including archived orders.

In response you will get

{
  "nextOffset": 200,
  "moreOrders": true,
  "comment": [
    "IF moreOrders is true, then call the API again with the nextOffset value",
    "IF moreOrders is false, there are no further orders to fetch."
  ]
}

6. TEMPLATES

6.1. Create A Message Template

Description: This endpoint creates a Template. If any required properties are missing an error will be returned.

Endpoint: /templates

Method:POST

Headers:

NameValueRequired?
Content-Typeapplication/json Yes
AuthorizationBearer TOKEN_HEREYes

Body:

KeyTypeRequired?Example
productIdStringYes"4392452522089"
handwritingStyle StringYes"Tarzan"
customMessage StringYes"This is my custom message"

Returns on success:

{
  "result": {
    "_id": "5e1b61a80d9234514cb1e983a",
    "productId": "4460979552361",
    "handwritingStyle": "Tarzan",
    "customMessage": "This is my custom message",
    "ownerId": "5e1a6f1d63458234017a962a3",
    "updated": "2020-01-01T00:00:00.000Z",
    "created": "2020-01-01T00:00:00.000Z",
    "__v": 0
  },
  "errors": []
}

Example:

{
  "productId": "4460979552361",
  "handwritingStyle": "Tarzan",
  "customMessage": "This is my custom message"
}

6.2. Retrieve All Message Templates

Description: This endpoint gets all Message Templates.

Endpoint: /templates

Method: GET

Headers:

NameValueRequired?
Content-Typeapplication/json Yes
AuthorizationBearer TOKEN_HERE Yes

Returns on success:

{
  "result": [
    {
      "_id": "5e1b5123fe1a7f10021c2b04",
      "productId": "4460979552361",
      "handwritingStyle": "Tarzan",
      "customMessage": "This is my custom message",
      "ownerId": "5e1a6f1d616d871237a962a3",
      "updated": "2020-01-12T18:00:25.020Z",
      "created": "2020-01-12T18:00:25.020Z",
      "__v": 0
    },
    {
      "_id": "5e1b61a80d92f711231e983a",
      "productId": "4460979552361",
      "handwritingStyle": "Tarzan",
      "customMessage": "This is my custom message 2",
      "ownerId": "5e1a6f1d616d871237a962a3",
      "updated": "2020-01-12T18:12:56.945Z",
      "created": "2020-01-12T18:12:56.945Z",
      "__v": 0
    }
  ],
  "errors": []
}

6.3. Retrieve A Single Template

Description: This endpoint gets a single Template.

Endpoint: /templates/:templateId

Method: GET

Headers:

NameValueRequired?
Content-Typeapplication/jsonYes
AuthorizationBearer TOKEN_HEREYes

URL Parameters:

ParameterTypeRequired?Example
templateIdStringYes"5e1b5123fe1a7f10021c2b04"

Returns on success:

{
  "result": {
    "_id": "5e1b5123fe1a7f10021c2b04",
    "productId": "4460979552361",
    "handwritingStyle": "Tarzan",
    "customMessage": "This is my custom message",
    "ownerId": "5e1a6f1d616d871237a962a3",
    "updated": "2020-01-12T18:00:25.020Z",
    "created": "2020-01-12T18:00:25.020Z",
    "__v": 0
  },
  "errors": []
}

6.4. Update A Template

Description: This endpoint updates a Template. If any required properties are missing an error will be returned

Endpoint:/templates/:templateId

Method:PUT

Headers:

NameValueRequired?
Content-Type application/json Yes
AuthorizationBearer TOKEN_HEREYes

URL Parameters:

ParameterTypeRequired?Example
templateIdStringYes"5e1b5123fe1a7f10021c2b04"

Body:

KeyTypeRequired?Example
productIdStringYes"4392452522089"
handwritingStyleStringYes"Stitch"
customMessageStringYes"This is my custom message"

Returns on success:

{
  "result": {
    "productId": "4392452522089",
    "handwritingStyle": "Stitch",
    "customMessage": "This is my custom message"
  },
  "errors": []
}

Returns on success:

{
  "result": {
    "productId": "4392452522089",
    "handwritingStyle": "Stitch",
    "customMessage": "This is my custom message"
  },
  "errors": []
}

7. ADDRESSES

7.1. Create An Address

Description:This endpoint creates an Address. If any required properties are missing an error will be returned.

Endpoint:/addresses

Method:POST

Headers:

NameValueRequired?
Content-Type application/json Yes
AuthorizationBearer TOKEN_HEREYes

Headers:

KeyTypeRequired?Example
firstNameStringYes"Johnny"
lastNameString Yes"Appleseed"
AuthorizationBearer TOKEN_HEREYes"Appleseed"
businessNameStringNo"ACME Inc"
address1StringYes"123 S Maple Street"
address2 StringNo "Unit 123"
cityStringYes"Metropolis"
stateStringYes"Texas"
zipStringYes"12345"
countryStringYes"United States"

Returns on success:

{
  "result": {
    "_id": "5ea1101e9680607558e3ff77",
    "firstName": "Johnny",
    "lastName": "Appleseed",
    "businessName": "ACME Inc",
    "address1": "123 S Maple Street",
    "address2": "Unit 123",
    "city": "Metropolis",
    "state": "Texas",
    "zip": "12345",
    "country": "United States",
    "type": "return"
  },
  "errors": []
}

Example:

{
  "firstName": "Johnny",
  "lastName": "Appleseed",
  "businessName": "ACME Inc",
  "address1": "123 S Maple Street",
  "address2": "Unit 123",
  "city": "Metropolis",
  "state": "Texas",
  "zip": "12345",
  "country": "United States",
  "type": "return"
}

7.2. Retrieve All Addresses

Description: This endpoint gets all Addresses.

Endpoint: /addresses

Method: GET

Headers:

NameValueRequired?
Content-Type application/jsonYes
AuthorizationBearer TOKEN_HEREYes

URL Parameters:

ParameterTypeRequired?Example
typeString"return" OR "recipient"No

Returns on success:

{
  "result": [
    {
      "_id": "5ea1101e9680607558e3ff77",
      "firstName": "Johnny",
      "lastName": "Appleseed",
      "businessName": "ACME Inc",
      "address1": "123 S Maple Street",
      "address2": "Unit 123",
      "city": "Metropolis",
      "state": "Texas",
      "zip": "12345",
      "country": "United States",
      "type": "return"
    }
  ],
  "errors": []
}

7.3. Retrieve A Single Address

Description: This endpoint gets a single Template.

Endpoint: /templates/:templateId

Method: GET

Headers:

NameValueRequired?
Content-Typeapplication/jsonYes
AuthorizationBearer TOKEN_HEREYes

URL Parameters:

ParameterTypeRequired?Example
addressIdStringYes"5ea1101e9680607558e3ff77"

Returns on success:

{
  "result": {
    "_id": "5ea1101e9680607558e3ff77",
    "firstName": "Johnny",
    "lastName": "Appleseed",
    "businessName": "ACME Inc",
    "address1": "123 S Maple Street",
    "address2": "Unit 123",
    "city": "Metropolis",
    "state": "Texas",
    "zip": "12345",
    "country": "United States",
    "type": "return"
  },
  "errors": []
}

7.4. Update An Address

Description: This endpoint updates an address. If any required properties are missing an error will be returned.

Endpoint: /addresses/:addressId

Method: PUT

Headers:

NameValueRequired?
Content-Type application/json Yes
AuthorizationBearer TOKEN_HEREYes

URL Parameters:

ParameterTypeRequired?Example
addressIdStringYes"5ea1101e9680607558e3ff77"

Body:

KeyTypeRequired?Example
firstNameStringYes"Johnny"
lastNameStringYes"Appleseed"
businessName StringNo"ACME Inc"
addressIdStringYes"123 S Maple Street"
addressIdStringYes"Unit 123"
cityStringYes"Metropolis"
stateStringYes"Texas"
zipStringYes"12345"
countryStringYes"United States"
typeStringYes "recipient" OR "return"

Returns on success:

{
  "result": {
    "_id": "5ea1101e9680607558e3ff77",
    "firstName": "Johnny",
    "lastName": "Appleseed",
    "businessName": "ACME Inc",
    "address1": "123 S Maple Street",
    "address2": "Unit 123",
    "city": "Metropolis",
    "state": "Texas",
    "zip": "12345",
    "country": "United States",
    "type": "return"
  },
  "errors": []
}

Example:

{
  "firstName": "Johnny",
  "lastName": "Appleseed",
  "businessName": "ACME Inc",
  "address1": "123 S Maple Street",
  "address2": "Unit 123",
  "city": "Metropolis",
  "state": "Texas",
  "zip": "12345",
  "country": "United States",
  "type": "return"
}

7.5. Delete A Single Address

Description: This endpoint gets a single Template.

Endpoint:/addresses/:addressId

Method:DELETE

Headers:

NameValueRequired?
Content-Typeapplication/jsonYes

URL Parameters:

ParameterTypeRequired?Example
addressIdStringYes"5ea1101e9680607558e3ff77"

Returns on success:

{
  "result": {
    "deletedCount": 1
  },
  "errors": []
}

8. AVAILABLE HANDWRITING STYLES

8.1. Examples

Description: Below you can preview the available handwriting styles that can be leveraged by the API.

Tarzan:

The quick brown fox jumps over the lazy dog

Stitch:

The quick brown fox jumps over the lazy dog

Pinocchio:

The quick brown fox jumps over the lazy dog

Simba:

The quick brown fox jumps over the lazy dog

Roo:

The quick brown fox jumps over the lazy dog

Nemo:

The quick brown fox jumps over the lazy dog

Lumiere:

The quick brown fox jumps over the lazy dog

Kaa:

The quick brown fox jumps over the lazy dog

Dumbo:

The quick brown fox jumps over the lazy dog

Bolt:

The quick brown fox jumps over the lazy dog

Belle:

The quick brown fox jumps over the lazy dog

Cinderella:

The quick brown fox jumps over the lazy dog

Hercules:

The quick brown fox jumps over the lazy dog

Merlin:

The quick brown fox jumps over the lazy dog

Rapunzel:

The quick brown fox jumps over the lazy dog

Scar:

The quick brown fox jumps over the lazy dog