Cardly v2 API

The version 2 Cardly API is organised around REST, with predictable resource-oriented URLs. It accepts JSON-encoded request bodies, returns JSON-encoded responses and uses standard HTTP response codes and verbs to make understanding and integrating the API as quick and painless as possible.

When you're set up on the Cardly API, you'll be provided with two API keys - one for test mode, the other for live calls. Your test mode key will allow you to make all the calls available in the API, however won't mutate any data. So, you can test your integration and make sure everything works, get back (generally!) the same response as you would for a live call, then switch out your keys when you're ready to move to live ordering.

Currently the API accepts only JSON-encoded bodies for POST requests. As such, please ensure you provide the appropriate Content-type: text/json header when forming your requests. Other content types will likely fail as the request body will not be interpreted correctly.

As we release new products and features, the Cardly API will evolve to include access to these where possible. This documentation will also evolve to cover these new features as they're released.

While we do our best to avoid it, in the event we release a breaking change, we'll let you know well in advance so you have time to plan, test and release any updates necessary to accommodate the change.

Base URL
https://api-2.card.ly/v2
Accepted Content-Types
Content-type: text/json

Authentication

The Cardly API uses API keys to authenticate requests. Your API keys can be obtained and managed from your organisation portal.

Each set of API keys provides both test and live mode keys. Test mode keys are prefixed with test_ and can perform all the functions that live keys can, however they will not perform any mutations. That is, if a test mode key calls the Place Order endpoint, the request will be validated and provide a mostly-identical response as though you'd used a live key, however no actual order will be placed. Test mode responses will always contain a testMode: true element as part of the main return body.

Live mode keys are prefixed with live_ and have none of the restrictions of test mode keys.

Authentication to the API is performed via the API-Key header, as per the provided example.

API keys permit many functions to be performed against your organisation, including billable requests. You must keep your keys secure and if you believe them to be compromised, invalidate and re-issue your keys via your organisation portal.

All API requests must be performed over HTTPS. Calls made over plain HTTP will be rejected, as will requests without authentication.

API-Key Header
API-Key: test_QRJfLM9cGJyjdaINUPJu3XVT1QltYMJLtoncY73X

Return Structure

All returns from the Cardly API will present as a JSON-encoded body with the same overall structure: an element to denote the overall call success, along with any relevant messages, a data element to pass back data relevant to the call performed, and optionally a flag to indicate the request was performed in test mode.

Additionally, HTTP status codes can also help inform your request's success. Typically, you can rely on 200 - OK and 201 - Created response codes to indicate success.

We highly recommend checking for the presence of testMode: true to ensure you are not accidentally processing live requests with a testing key.

Attributes
state.status
string

A code to indicate the overall success of the call. One of OK, WARN or ERROR.

state.messages
array

A list of feedback messages to provide more information on a failure, or optionally warnings for successful calls.

data
object

If this call results in any data to be passed back to the caller, the structure will be located here.

Data structures differ per call and are detailed in the relevant API functions below.

Common Return Structure
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        ...
    },
    "testMode": true
}

Errors

The API uses standard HTTP response codes to indicate the success or failure of your API requests. Generally, codes in the 2xx range indicate success. Codes in the 4xx range indicate issues due to the data provided - authentication failures, required fields missing, insufficient funds etc. Codes in the 5xx range indicate an error on Cardly's end - these should be rare!

Where possible, we'll provide you with information on why your call failed to help you quickly diagnose and remedy the issue.

Utilised HTTP Status Code List
200 - OK

The request processed as expected.

201 - Created

The request processed, creating a relevant resource as expected.

400 - Bad Request

The request failed, likely due to missing data.

401 - Unauthorized

No valid API key was supplied.

402 - Request Failed

The request passed validation, but failed for another reason.

403 - Forbidden

The passed API key does not have privileges to perform the requested operation.

404 - Not Found

The requested resource does not exist.

422 - Unprocessable Entity

The request failed, likely due to one or more fields not passing validation.

429 - Too Many Requests

You have performed too many requests to the API in a short period of time. We recommend slowing down your request rate and implementing exponential backoff of your requests.

500 - Internal Server Error
Something went wrong on Cardly's end. We're likely already looking into it!

Idempotent Requests

The Cardly API supports idempotent requests, allowing you to safely retry requests without accentially performing the same operation twice. This is extremely useful when your API call is distrupted and you do not receive a response, or fail to complete processing of this response on your applications end (due to loss of connectivity etc).

For example, if a request to the Place Order endpoint does not result in a response, or the response times out, you can retry the exact same request again and receive the response you would have otherwise missed. This helps guarantee the original request you wanted to make is processed once, and once only.

To perform a request utilising Idempotency, supply an additional Idempotency-Key: <key> header in your request.

The API's idempotency works by saving the resulting status code and body of the original request for any given idempotency key, regardless of success. Subsequent requests with the same key return the same result, without hitting the processing layer.

Your idempotency keys are unique values generated by your client which the API uses to identify subsequent retries of the same request. Generation and format of idempotency keys is up to you, however Cardly recommends v4 UUIDs or another random string of sufficent length to guarantee uniqueness. Your idempotency keys may be up to 64 characters in length.

In addition, to ensure you do not accidentally reuse or change your original request when utilising idempotency keys, we analyse the incoming request to ensure it is consistent with any previously logged request. In the event an idempotency result is found with a different request signature, you'll receive an error indicating the request was changed, but an idempotency key was being reused.

Idempotent results will only be saved if the request started started processing - if the request failed due to invalid credentials, missing parameters etc, the idempotency key will not be consumed by the request. You can therefore safely re-use idempotency keys until a successful operation is processed.

Please note that only POST requests accept idempotency keys. All other HTTP verbs currently in use by the Cardly API will ignore idempotency keys, as these requests are idempotent by definition.

Idempotency-Key Header
Idempotency-Key: f47b838a-304d-f88c-4d2c-a8709cacfdc8

Request IDs

Every API request performed will return an associated request identifier in the response headers. You can find this in your response under the Request-Id header. You will also be able to find request identifiers within your organisation portal API logs.

If you need to contact us for support, particularly with regard to a specific request, providing the relevant Request-Id will help us to resolve your query as quickly as possible.

Request-Id Response Header
Request-Id: c64695af-eaf4-1d4e-c2fa-c89417a3fd7c

Pagination

Most top-level endpoints in the API provide support for bulk fetches for list-style data. The request and response formats for these calls share a common structure to simplify understanding these calls. They all at minimum accept the following parameters: limit and offset.

To navigate lists of paginated data, simply increase the offset parameter by the limit value you are utilising (or the default of 25 if you aren't specifying a limit). Ensure that you don't navigate past the end of a resource list by checking to ensure your offset is below the meta.totalRecords value in the previous response.

Request Parameters
limit
integer

The maximum number of records to return. Minimum: 1, maxium: 100, default: 25.

offset
integer

How many results to offset the next set of results by. To get page 2 of a result set, this should be equal to the limit parameter.

Result Structure
meta.startRecord
integer

The row number (1-based) of the first record in the result set.

meta.lastRecord
integer

The row number (1-based) of the last record in the result set.

meta.limit
integer

The maximum number of records in this result set.

meta.offset
integer

The number of rows offset from the start of this result set.

meta.totalRecords
integer

The total number of results in the entire result set, ignoring pagination limits.

results
array

The list of result records for a given endpoint call.

Request: GET /v2/art?limit=10&offset=20
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "meta": {
            "startRecord": 21,
            "lastRecord": 30,
            "limit": 10,
            "offset": 20,
            "totalRecords": 134
        },
        "results": [
            ...
        ]
    }
}

Testing & Development Helpers

Echo provides a simple, low impact means of testing API features. We'll simply take your request, headers and body parameters and return these back to you in a standard structure.

This way you can quickly test your authentication, idempotency behaviour and get a feel for the API features before diving in to real requests.

Endpoints

/v2/echo

Echo Request

The echo endpoint will take any parameters, body structure and headers and return them to you in a JSON structure. You can use this endpoint to quickly debug other requests, validate your authentication, idempotency and other API features without any impact on your account or any risk of credit usage.

This endpoint is special in that it will accept any HTTP verb and still provide an output to the caller.

Please note: you must still authenticate to this endpoint and you'll receive appropriate error responses if your API key is invalid or not supplied.

/v2/echo?test=foo
{
    "foo": "bar",
    "array": ["A", "B", "C"]
}
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "method": "POST",
        "url": "https://api.card.ly/v2/echo",
        "headers": {
            "api-key": "test_QRJ***73X",
            "content-type": "application/json",
            "accept": "*/*",
            "cache-control": "no-cache",
            "host": "api.card.ly",
            "accept-encoding": "gzip, deflate",
            "content-length": "60",
            "connection": "keep-alive"
        },
        "params": {
            "test": "foo"
        },
        "body": {
            "foo": "bar",
            "array": [
                "A",
                "B",
                "C"
            ]
        }
    },
    "testMode": true
}

Account

Account functions aid with checking your organistaion's current balance, reviewing previous transactions, adding more credit and performing updates to organisation details.

Endpoints

/v2/account/balance

/v2/account/credit-history

Credit History Object

The credit history object models an entry - positive or negative - for the organisation's credit purchase and spends.

Attributes
id
UUID

Unique identifier for this credit history entry.

orderId
UUID

Identifier for an order that triggered this credit history entry. Generally used whenever paid transactions take place.

transactionId
UUID

Identifier for a transaction that triggered this credit history entry, typically related to the purchase of credits.

type
string

A human-readable, brief description of what this entry is for, ie; Credit Purchase, Order Placement.

change
float

Value that was either credited or debited from the organisation in this action.

effectiveTime
datetime

Timestamp of when this credit history entry occurred.

Balance History Example
{
    "id": "ef974e61-8496-0de9-446c-ffc21bf7e2e2",
    "orderId": null,
    "transactionId": null,
    "type": "Credit",
    "change": 120,
    "effectiveTime": "2019-11-23 12:10:54"
}

Account Balance

This endpoint allows you to quickly query the current balance for your organisation.

Where relevant, API calls which consume or have the potential to consume balance will return your organisation's balance in the return structure for convenience. This will allow you to easily determine if additional balance should be added to your account if not utilising the automatic account topup feature.

Return
balance
float

Your organisation's current credit balance. Note that this may not be a whole number.

/v2/account/balance
(No body required)
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "balance": 123
    },
    "testMode": true
}

Credit History

Retrieve a section of balance history records pertaning to your organistaion. This will list both credits and debits, along with links / reasons for each, where applicable.

This request accepts standard pagination options limit, offset along with the following additional filters:

Request Parameters
effectiveTime.lt
datetime

YYYY-MM-DD HH:ii:ss formatted string to retrieve only results before this time.

effectiveTime.lte
datetime

YYYY-MM-DD HH:ii:ss formatted string to retrieve only results before or equal to this time.

effectiveTime.gt
datetime

YYYY-MM-DD HH:ii:ss formatted string to retrieve only results after this time.

effectiveTime.gte
datetime

YYYY-MM-DD HH:ii:ss formatted string to retrieve only results after or equal to this time.

Return
results
array

A paginated array of zero or more Credit History objects.

/v2/account/credit-history
(No body required)
Response

    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "meta": {
            "startRecord": 1,
            "lastRecord": 5,
            "limit": 25,
            "offset": 0,
            "totalRecords": 5
        },
        "results": [
            {
                "id": "484ed6af-416e-1f76-7807-c88104734f09",
                "orderId": null,
                "transactionId": null,
                "type": "Signup Bonus",
                "change": 3,
                "effectiveTime": "2019-11-23 12:10:54"
            },
            ...
        ]
    }
}

Media

The media endpoints provide data about the types and dimensions of available products within Cardly. This information can be used to validate specifications on new artwork, or see which products are currently on offer in various regions.

Please note: Media sizes are not all available in all regions Cardly covers. Where you attempt to order media from an unsupported region, the relevant endpoint will return an error.

Endpoints

/v2/media

Media Object

The media object models a product available on Cardly and denotes the regions it is available for purchase in. It also provides information on the dimensions of the product, both physical and pixel dimensions for artwork supply.

Attributes
id
integer

Unique identifier for this media option.

name
string

A localised, human-readable name for this product.

description
string

A longer description of the product, along with any restrictions or important information.

creditCost
float

The number of credits that would be consumed when ordering this media type.

pages
integer

The total number of pages to this product. A standard greeting card is four pages (front, inner left, inner right, back), while a postcard-style product is two pages (front & back).

dimensions.mm.height
dimensions.mm.width
integer

Dimensions of this product in millimeters, exclusive of bleed.

bleed.mm.x
bleed.mm.y
integer

Bleed zone of this product in millimeters, added to the dimensions measurements for the overall page size.

Using the provided example, this would be a 115x158mm product for the purposes of artwork dimensions.

art.px.width
art.px.height
integer

Size of the artwork required for this product, in pixels, inclusive of bleed zones.

Please ensure when providing artwork these bleed zones are accounted for in your supplied imagery.

Media Example
{
    "id": 3,
    "name": "Standard Postcard",
    "description": null,
    "creditCost": 0.5,
    "pages": 2,
    "dimensions": {
        "mm": {
            "height": 105,
            "width": 148
        }
    },
    "bleed": {
        "mm": {
            "x": 5,
            "y": 5
        }
    },
    "art": {
        "px": {
            "width": 2488,
            "height": 1811
        }
}

Media Listing

Retrieve the currently available media sizes for product artwork.

Return
results
array

A paginated array of zero or more Media objects.

/v2/media
(No body required)
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "meta": {
            "startRecord": 1,
            "lastRecord": 5,
            "limit": 25,
            "offset": 0,
            "totalRecords": 5
        },
        "results": [
            {
                "id": 4,
                "name": "148 x 202mm Card",
                "description": null,
                "creditCost": 1,
                "pages": 4,
                "dimensions": {
                    "mm": {
                        "height": 148,
                        "width": 111
                    }
                },
                "bleed": {
                    "mm": {
                        "x": 5,
                        "y": 5
                    }
                },
                "art": {
                    "px": {
                        "width": 1905,
                        "height": 2488
                    }
                }
            },
            ...
        ]
    }
}

Templates

The template endpoints allow you to retrieve and manipulate templates available to your organisation.

Endpoints

/v2/templates

Template Object

The template object denotes styling and structure to be applied to a given media size card.

Attributes
id
UUID

Unique identifier for this template option.

name
string

The human-readable description for this template.

slug
string

A human-readable identifier for this template unique within your organisation.

media
Media Object

The media object that represents the media size associated with this template.

definition.version
integer

The version of the Cardly editor this template was created by.

definition.style
object

The default styles to filter through to pages in this template, if no styles are defined at the page level.

definition.pages[]
array

A list of page objects to define page-level objects (doodles, text areas, gift cards etc) and text data, along with individual page style overrides if applicable.

definition.variables
object

A list of variables associated with this template, where the property name is the variable key and additional description / example data is provided for each variable.

Template Example
{
    "id": "18ecf6e6-d2e2-49cb-bae0-fa980241db73",
    "name": "Happy Birthday",
    "slug": "happy-birthday",
    "media": (Media Object),
    "definition": {
        "version": 2,
        "style": {
            "color": "1144a7",
            "size": 25,
            "writing": "987d50c7-25e1-3b1c-aa78-6f60b1411fe5",
            "font": "0d372503-c81b-987d-7636-bd6321290528"
        },
        "pages": [
            {
                "style": {
                    "align": "left",
                    "color": "1144a7",
                    "size": 25,
                    "writing": "987d50c7-25e1-3b1c-aa78-6f60b1411fe5",
                    "font": "0d372503-c81b-987d-7636-bd6321290528"
                },
                "objects": [],
                "text": {
                    "lines": []
                }
            },
            {
                "style": {
                    "align": "left",
                    "color": "1144a7",
                    "size": 25,
                    "writing": "987d50c7-25e1-3b1c-aa78-6f60b1411fe5",
                    "font": "0d372503-c81b-987d-7636-bd6321290528"
                },
                "objects": [],
                "text": {
                    "lines": []
                }
            }
        ],
        "variables": {
            "firstName": {
                "description": "Customer's first name to display in card front and salutation.",
                "example": "John"
            },
			...
        }
    }
}

Template Listing

Retrieve the currently available templates for this organisation.

Return
results
array

A paginated array of zero or more Template objects.

/v2/templates
(No body required)
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "meta": {
            "startRecord": 1,
            "lastRecord": 5,
            "limit": 25,
            "offset": 0,
            "totalRecords": 5
        },
        "results": [
            {
                "id": "18ecf6e6-d2e2-49cb-bae0-fa980241db73",
                "name": "Happy Birthday",
                "slug": "happy-birthday",
                "media": (Media Object),
                "definition": {
                    "version": 2,
                    "style": {
                        "color": "1144a7",
                        "size": 25,
                        "writing": "987d50c7-25e1-3b1c-aa78-6f60b1411fe5",
                        "font": "1d372503-c81b-987d-7636-b16321290528"
                    },
                    "pages": [
                        {
                            "style": {
                                "align": "left",
                                "color": "1144a7",
                                "size": 25,
                                "writing": "987d50c7-25e1-3b1c-aa78-6f60b1411fe5",
                                "font": "1d372503-c81b-987d-7636-b16321290528"
                            },
                            "objects": [],
                            "text": {
                                "lines": []
                            }
                        },
                        {
                            "style": {
                                "align": "left",
                                "color": "1144a7",
                                "size": 25,
                                "writing": "987d50c7-25e1-3b1c-aa78-6f60b1411fe5",
                                "font": "1d372503-c81b-987d-7636-b16321290528"
                            },
                            "objects": [],
                            "text": {
                                "lines": []
                            }
                        }
                    ],
                    "variables": {
                        "firstName": {
                            "description": "Customer's first name to display in card front and salutation.",
                            "example": "John"
                        },
						...
                    }
                }
            },
            ...
        ]
    }
}

Orders

The orders endpoints provide the ability to generate on-the-fly previews with supplied card data, lodge live orders and query your organisation's order history.

Please note: Once lodged with a live API key, orders are typically difficult to cancel reliably due to our printer partner's schedules. If you have lodged an order in error, please immediately contact the Cardly support team so we can attempt to intervene on your behalf. However, Cardly is unable to make any guarantee on how successful cancelling an order that has gone to print will be.

Endpoints

/v2/orders/preview

/v2/orders/place

Order Object

The order object provides detail on a given order on your account, along with individual line item recipient, sender, cost and timing details.

Attributes
id
UUID

Unique identifier for this order.

status
string

The current status of this order.

origin
string

Where the order originate - via the API, your organisation portal, etc.

customer
object

Details about the organisation or user that placed this order. For API-originating orders, this will be your organisation details.

costs.credits
float

The total credits this order consumed, if paid by credits.

costs.gross
float

The gross cost of this order, exclusive of tax.

costs.discount
float

The discount amount for this order overall.

costs.tax
float

The total amount of tax on this order, exclusive of shipping.

costs.shipping
float

The total tax-exclusive cost of shipping for this order.

costs.shippingTax
float

The total amount of tax applied to shipping.

costs.total
float

The total cost of this order.

costs.currency
string

The currency this order was priced in.

timings.paid
datetime

When this order was paid - if it is paid.

timings.created
datetime

When this order was first raised.

timings.updated
datetime

When this order was last updated.

items
array

List of Order Item objects that comprise this order.

Order Example
{
    "id": "c988c0c0-f6a3-4e90-bbd5-759497a82607",
    "status": "paid",
    "origin": "api",
    "description": null,
    "customer": {
        "firstName": "Cardly Pty Ltd",
        "lastName": null,
        "address": "10 Another Lane",
        "address2": null,
        "city": "Brisbane",
        "region": "QLD",
        "postcode": "4000",
        "country": "AU"
    },
    "costs": {
        "credits": 0.53
    },
    "timings": {
        "paid": "2019-12-04 12:06:46",
        "created": "2019-12-04 12:06:46",
        "updated": "2019-12-04 12:06:46"
    },
    "items": [
        {
            "id": "60051a2c-86af-45bb-a34f-febf37d9070c",
            "type": "card",
            "label": "Cardly - Happy Birthday",
            "quantity": 1,
            "costs": {
                "credits": 0.5
            },
            "shipTo": "S",
            "shipMethod": "standard",
            "scheduledDate": "2019-12-25 00:00:00",
            "recipient": {
                "address": "10 Somewhere Place",
                "address2": "",
                "city": "Fairyland",
                "region": "QLD",
                "postcode": "4110",
                "country": "AU"
            },
            "sender": {
                "name": "Cardly",
                "address": "10 Another Lane",
                "address2": null,
                "city": "Brisbane",
                "region": "QLD",
                "postcode": "4000",
                "country": "AU"
            },
            "timings": {
                "lodgeAfter": "2019-12-04 12:06:46",
                "shipped": null,
                "lodged": null,
                "held": null
            },
            "delivery": {
                "requested": "2019-12-25",
                "dispatch": "2019-12-12",
                "estimatedMinArrival": "2019-12-17",
                "estimatedMaxArrival": "2019-12-20"
            },
            "media": 3,
            "artwork": "5c40d96b-b7c3-4980-9bdc-14306104ebd4",
            "template": "73bf3d63-5bca-45dc-86f6-d5c01946d78b",
            "related": [
                {
                    "id": "3ae265f0-0f63-4018-a0a1-c26d31a3179f",
                    "type": "envelope",
                    "label": "Additional envelope",
                    "quantity": 1,
                    "costs": {
                        "credits": 0.03
                    },
                    "related": []
                }
            ]
        }
    ]
}

Order Item Object

The order item object provides detail on a component of a larger order, along with detail related to add-on components to this item (ie, gift cards, additional envelopes).

Attributes
id
UUID

Unique identifier for this order item.

type
string

The type of item this is - typically card.

label
string

A description of this item, typically the card artwork title.

quantity
integer

The number of units of this item that were ordered.

costs.credits
float

The total credits this order consumed, if paid by credits.

costs.gross
float

The gross unit cost of this item, exclusive of tax.

costs.discount
float

The discount amount per unit for this item.

costs.tax
float

The amount of tax per unit on this item, exclusive of shipping.

costs.shipping
float

The per-unit tax-exclusive cost of shipping for this item.

costs.shippingTax
float

The amount per unit of tax applied to shipping.

costs.total
float

The total line cost for the entire quantity requested of this item.

costs.currency
string

The currency this item was priced in.

shipTo
string

Either S for shipping back to the sender, or D for shipping direct to the customer.

shipMethod
string

The shipping method used, either standard, priority or express.

scheduledDate
date

If requested at order time, the date this item was requested to arrive by.

recipient
object

The address details for the recipient of this item.

sender
object

The address details for the sender of this item.

timings.lodgeAfter
datetime

The scheduled time for sending this item to print. Lodgement will always occur after this time.

timings.lodged
datetime

When this item was sent to print.

timings.shipped
datetime

When this item was shipped. Please note: we rely on external data to populate this and it may not always be immediately available.

timings.held
datetime

If this item is being held, the time the item was marked for holding.

delivery.requested
date

The arrival date requested, if applicable. This will be null where you did not specify a requested delivery date.

delivery.dispatch
date

The date an order will be sent to print, either today if no requested delivery date is specified, or a date calculated from the maximum delivery window time for your selected shipping method.

delivery.estimatedMinArrival
date

The estimated earliest date an order should be received. Note that this is subject to end postal carriers and beyond the control of Cardly directly.

delivery.estimatedMaxArrival
date

The estimated latest date an order should be received. Note that this is subject to end postal carriers and beyond the control of Cardly directly.

media
integer

Identifier for the media type used for this item.

artwork
UUID

Identifier for the artwork used for this item.

template
UUID

Identifier for the template used to populate this item, if applicable.

related
array

Zero or more Order Item objects directly related to this one - additional envelopes, gift cards, etc.

Order Item Example
{
    "id": "60051a2c-86af-45bb-a34f-febf37d9070c",
    "type": "card",
    "label": "Cardly - Happy Birthday",
    "quantity": 1,
    "costs": {
        "credits": 0.5
    },
    "shipTo": "S",
    "shipMethod": "standard",
    "scheduledDate": "2019-12-25",
    "recipient": {
        "address": "10 Somewhere Place",
        "address2": "",
        "city": "Fairyland",
        "region": "QLD",
        "postcode": "4110",
        "country": "AU"
    },
    "sender": {
        "name": "Cardly",
        "address": "10 Another Lane",
        "address2": null,
        "city": "Brisbane",
        "region": "QLD",
        "postcode": "4000",
        "country": "AU"
    },
    "timings": {
        "lodgeAfter": "2019-12-04 12:06:46",
        "shipped": null,
        "lodged": null,
        "held": null
    },
    "delivery": {
        "requested": "2019-12-25",
        "dispatch": "2019-12-12",
        "estimatedMinArrival": "2019-12-17",
        "estimatedMaxArrival": "2019-12-20"
    },
    "media": 3,
    "artwork": "5c40d96b-b7c3-4980-9bdc-14306104ebd4",
    "template": "73bf3d63-5bca-45dc-86f6-d5c01946d78b",
    "related": [
        {
            "id": "3ae265f0-0f63-4018-a0a1-c26d31a3179f",
            "type": "envelope",
            "label": "Additional envelope",
            "quantity": 1,
            "costs": {
                "credits": 0.03
            },
            "related": []
        }
    ]
}

Generate Preview

The preview endpoint allows you to generate a quick, low-quality, watermarked preview document for a given piece of card art and template, along with passed user data. You will also be provided with delivery window estimates and a projected credit cost for the order based on your passed data.

This call is intentionally nearly identical to the Place Order function to facilitate testing and a quick migration to ordering. The main difference between these calls is a Place Order request permits multiple line items with differing data and settings, while the Generate Preview deals with only a single card at a time.

Request Parameters
artwork
string

The unique artwork ID to use for this card. This may be the UUID or slug for a given piece of artwork under your organisation.

template
string

The template ID to use top populate this card. If no template is specified, only the main text panels on the card will be utilised and no variable substitutions will occur.

messages.pages[].page
integer

Numeric identifier for the page the rest of this element's settings apply to. This is a one-based numbering of card pages - front cover is 1, inside left is 2, etc.

messages.pages[].text
string

The main panel text to use for a given page. Note that this will only be utilised if the media supports placing text on this page. Most four page cards will restrict front/back panels to artwork only, while postcards typically accept only content for the back panel.

Please note: If you have specified a template, the messages element will be ignored entirely in favor of the template's text.

variables[].(property)
string

Zero or more variables to inject into a template, based on the variables supported by that template. This is a key => value mapped object based on the variables to use in the template.

recipient.firstName
string

The recipient's first name, as it should appear on the envelope.

recipient.lastName
string

The recipient's last name, as it should appear on the envelope.

recipient.address
string

The recipient's street number, name and type, ie. 10 Somewhere Lane

recipient.address2
string

Unit, floor, apartment etc. additional information for the recipient's address.

recipient.city
string

Suburb or city for the recipient.

recipient.region
string

State / province / region for the recipient, if required. UK and NZ currently do not require a region specified.

recipient.postcode
string

Postcode for the recipient.

recipient.country
string

2-character ISO code for the country to ship to.

sender.firstName
string

The sender's first name, as it should appear on the envelope.

Please note: the entire sender section is optional and will default to your organisation's return details if not completed. If any sender element is specified, all must be specified.

sender.lastName
string

The sender's last name, as it should appear on the envelope.

sender.address
string

The sender's street number, name and type, ie. 10 Somewhere Lane

sender.address2
string

Unit, floor, apartment etc. additional information for the sender's address.

sender.city
string

Suburb or city for the sender.

sender.region
string

State / province / region for the sender, if required. UK and NZ currently do not require a region specified.

sender.postcode
string

Postcode for the sender.

sender.country
string

2-character ISO code for the country to use for the return address..

shippingMethod
string

The shipping method to use. Note that shipping method support is on a per-region basis, but all regions will at minimum support the standard shipping method.

Currently, only Australia supports the additional priority shipping method.

shipToMe
boolean

If set to true, denotes that the recipient of this card is also the sender and to include an additional, blank envelope. Note that this incurs a small additional credit cost.

requestedArrival
date

A future requested arrival date for this card. In a preview request, this will provide a basis for shipping window estimates to be returned. If not specified, immediate dispatch is assumed and dates will be calculated based on the current date.

purchaseOrderNumber
string

A purchase order or other identifier to store against the order. Note that this has no bearing on a preview, unless there is an template variable that accepts this value.

Return
balance
float

Your organisation's current credit balance. Note that this may not be a whole number.

order.creditCost
float

The number of credits this order costs based on the selected media size, post option and any additional options such as 'send to me' requiring additional envelopes.

order.delivery.requested
date

The arrival date requested, if applicable. This will be null where you did not specify a requested delivery date.

order.delivery.dispatch
date

The date an order will be sent to print, either today if no requested delivery date is specified, or a date calculated from the maximum delivery window time for your selected shipping method.

order.delivery.estimatedMinArrival
date

The estimated earliest date an order should be received. Note that this is subject to end postal carriers and beyond the control of Cardly directly.

order.delivery.estimatedMaxArrival
date

The estimated latest date an order should be received. Note that this is subject to end postal carriers and beyond the control of Cardly directly.

preview.expires
datetime

Timestamp of when this preview will be removed from Cardly's systems. Ensure the preview URLs are accessed prior to this time.

preview.format
string

The file format for the preview. Currently only PDF previews are generated.

preview.urls.format
string

URL to the card artwork preview document. This URL does not require authentication and can be retrieved with a standard GET request.

preview.urls.envelope
string

URL to the envelope artwork preview, if applicable. Some products such as postcards do not require envelopes, so this value will be null in those cases. This URL does not require authentication and can be retrieved with a standard GET request.

/v2/orders/preview
{
    "artwork": "happy-birthday",
    "template": "happy-birthday-promo",
    "messages": {
        "pages": [
            {
                "page": 1,
                "text": ""
            },
            {
                "page": 2,
                "text": ""
            }
        ]
    },
    "variables": {
        "firstName": "John",
        "message": "Happy birthday from the Cardly team, we hope you have a great one!",
    },
    "recipient": {
        "firstName": "John",
        "lastName": "Doe",
        "address": "10 Somewhere Place",
        "address2": "",
        "city": "Fairyland",
        "region": "QLD",
        "postcode": "4110",
        "country": "AU"
    },
    "sender": {
        "firstName": "Cardly Pty Ltd",
        "lastName": "",
        "address": "10 Another Lane",
        "city": "Brisbane",
        "region": "QLD",
        "postcode": "4000",
        "country": "AU"
    },
    "shippingMethod": "standard",
    "shipToMe": false,
    "requestedArrival": "2019-12-25",
    "purchaseOrderNumber": "123ABC"
}
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "balance": 123,
        "order": {
            "creditCost": 0.5,
            "delivery": [
                {
                    "requested": "2019-12-25",
                    "dispatch": "2019-12-12",
                    "estimatedMinArrival": "2019-12-17",
                    "estimatedMaxArrival": "2019-12-20"
                }
            ]
        },
        "preview": {
            "expires": "2019-12-10 23:11:38",
            "format": "pdf",
            "urls": {
                "card": "http://api.card.ly/v2/preview/4e898074-6a2e-e3fb-9778-518596c36c2a/card/pdf",
                "envelope": null
            }
        }
    }
}

Place Order

The place endpoint allows you to place an order for one or more items, being delivered to one or more distinct recipients. Generally, we recommend that individual orders are created for individual recipients to minimise potential validation and other rejection issues.

Note that you must have sufficient credit on your account to place your order. If you have insufficient credit, a 402 response will be returned with detail on the required credit cost and your current balance.

Request Parameters
purchaseOrderNumber
string

A reference number to place against this order - useful to tie back to your existing systems for auditing.

lines
array

A list of one or more of the below Order Item structures to include into the overall order.

Order Item Structure
artwork
string

The unique artwork ID to use for this card. This may be the UUID or slug for a given piece of artwork under your organisation.

template
string

The template ID to use top populate this card. If no template is specified, only the main text panels on the card will be utilised and no variable substitutions will occur.

messages.pages[].page
integer

Numeric identifier for the page the rest of this element's settings apply to. This is a one-based numbering of card pages - front cover is 1, inside left is 2, etc.

messages.pages[].text
string

The main panel text to use for a given page. Note that this will only be utilised if the media supports placing text on this page. Most four page cards will restrict front/back panels to artwork only, while postcards typically accept only content for the back panel.

Please note: If you have specified a template, the messages element will be ignored entirely in favor of the template's text.

variables[].(property)
string

Zero or more variables to inject into a template, based on the variables supported by that template. This is a key => value mapped object based on the variables to use in the template.

recipient.firstName
string

The recipient's first name, as it should appear on the envelope.

recipient.lastName
string

The recipient's last name, as it should appear on the envelope.

recipient.address
string

The recipient's street number, name and type, ie. 10 Somewhere Lane

recipient.address2
string

Unit, floor, apartment etc. additional information for the recipient's address.

recipient.city
string

Suburb or city for the recipient.

recipient.region
string

State / province / region for the recipient, if required. UK and NZ currently do not require a region specified.

recipient.postcode
string

Postcode for the recipient.

recipient.country
string

2-character ISO code for the country to ship to.

sender.firstName
string

The sender's first name, as it should appear on the envelope.

Please note: the entire sender section is optional and will default to your organisation's return details if not completed. If any sender element is specified, all must be specified.

sender.lastName
string

The sender's last name, as it should appear on the envelope.

sender.address
string

The sender's street number, name and type, ie. 10 Somewhere Lane

sender.address2
string

Unit, floor, apartment etc. additional information for the sender's address.

sender.city
string

Suburb or city for the sender.

sender.region
string

State / province / region for the sender, if required. UK and NZ currently do not require a region specified.

sender.postcode
string

Postcode for the sender.

sender.country
string

2-character ISO code for the country to use for the return address..

shippingMethod
string

The shipping method to use. Note that shipping method support is on a per-region basis, but all regions will at minimum support the standard shipping method.

Currently, only Australia supports the additional priority shipping method.

shipToMe
boolean

If set to true, denotes that the recipient of this card is also the sender and to include an additional, blank envelope. Note that this incurs a small additional credit cost.

requestedArrival
date

A future requested arrival date for this card. In a preview request, this will provide a basis for shipping window estimates to be returned. If not specified, immediate dispatch is assumed and dates will be calculated based on the current date.

Return
balance
float

Your organisation's current credit balance after this order has been charged.

order
Order Object

An Order object representing the order you just placed.

/v2/orders/place
{
    "lines": [
        {
            "artwork": "happy-birthday",
            "template": "happy-birthday-promo",
            "quantity": 1,
            "messages": {
                "pages": [
                    {
                        "page":    1,
                        "text": ""
                    },
                    {
                        "page":    2,
                        "text": ""
                    }
                ]
            },
            "variables": {
                "firstName": "John",
                "message": "Happy birthday, we hope you have a great day!"
            },
            "recipient": {
                "firstName": "John",
                "lastName": "Doe",
                "address": "10 Somewhere Place",
                "address2": "",
                "city": "Fairyland",
                "region": "QLD",
                "postcode": "4110",
                "country": "AU"
            },
            "sender": {
                "firstName": "Cardly Pty Ltd",
                "lastName": null,
                "address": "10 Another Lane",
				"address2": null,
                "city": "Brisbane",
                "region": "QLD",
                "postcode": "4000",
                "country": "AU"
            },
            "shippingMethod": "standard",
            "shipToMe": false,
            "requestedArrival": "2019-12-25"
        }
    ],
    "purchaseOrderNumber": "12345a"
}
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "balance": 99.73,
        "order": {
            "id": "c988c0c0-f6a3-4e90-bbd5-759497a82607",
            "status": "paid",
            "origin": "api",
            "description": null,
            "customer": {
                "firstName": "Cardly Pty Ltd",
                "lastName": null,
                "address": "10 Another Lane",
                "address2": null,
                "city": "Brisbane",
                "region": "QLD",
                "postcode": "4000",
                "country": "AU"
            },
            "costs": {
                "credits": 0.53
            },
            "timings": {
                "paid": "2019-12-04 12:06:46",
                "created": "2019-12-04 12:06:46",
                "updated": "2019-12-04 12:06:46"
            },
            "items": [
                {
                    "id": "60051a2c-86af-45bb-a34f-febf37d9070c",
                    "type": "card",
                    "label": "Cardly - Happy Birthday",
                    "quantity": 1,
                    "costs": {
                        "credits": 0.5
                    },
                    "shipTo": "S",
                    "shipMethod": "standard",
                    "scheduledDate": "2019-12-25 00:00:00",
                    "recipient": {
                        "address": "10 Somewhere Place",
                        "address2": "",
                        "city": "Fairyland",
                        "region": "QLD",
                        "postcode": "4110",
                        "country": "AU"
                    },
                    "sender": {
                        "name": "Cardly",
                        "address": "10 Another Lane",
                        "address2": null,
                        "city": "Brisbane",
                        "region": "QLD",
                        "postcode": "4000",
                        "country": "AU"
                    },
                    "timings": {
                        "lodgeAfter": "2019-12-04 12:06:46",
                        "shipped": null,
                        "lodged": null,
                        "held": null
                    },
                    "delivery": {
                        "requested": "2019-12-25",
                        "dispatch": "2019-12-12",
                        "estimatedMinArrival": "2019-12-17",
                        "estimatedMaxArrival": "2019-12-20"
                    },
                    "media": 3,
                    "artwork": "5c40d96b-b7c3-4980-9bdc-14306104ebd4",
                    "template": "73bf3d63-5bca-45dc-86f6-d5c01946d78b",
                    "related": [
                        {
                            "id": "3ae265f0-0f63-4018-a0a1-c26d31a3179f",
                            "type": "envelope",
                            "label": "Additional envelope",
                            "quantity": 1,
                            "costs": {
                                "credits": 0.03
                            },
                            "related": []
                        }
                    ]
                }
            ]
        }
    },
    "testMode": true
}