Contact Log in

Standard Model Spec

Thankful’s Standard Model Spec is a framework that enables Thankful to deeply integrate your business, handling returns, missing packages, order tracking and more using custom backends.

The Standard Model delivers value immediately with small engineering asks, then improves over time with additional effort. With this framework you can spec out and plan your engineering requirements alongside the type of experience you’d like to deliver to your customers.

Each action Thankful performs has a set of endpoints that you MUST implement. Each endpoint has fields that you MUST or MAY implement. Optional fields are noted in the documentation with additional comments surrounding blocks of fields: if provided, optional fields unlock better experiences for your customers.

URLs are set and cannot be adjusted. Thankful will send a request to the URL exactly as described. All request URLs are namespaced under /thankful/api/.

URL parameters will always be URL-encoded according to RFC3986.

Versioning
Authorization
Actions
Endpoints
Data Structures

Versioning

This API is versioned on an endpoint-by-endpoint basis, enabling you to upgrade endpoints gradually. For instance, you could use both v1.0 of Get Order and v2.0 of Return Order. It’s up to you to self-report your API version in the X-API-Version response header, for example:

X-API-Version: v1.0

Your server MUST send a version header with every response.

The current version is v1.0. The Standard Model follows semver, so non-breaking changes such as adding fields and endpoints will increment the MINOR number, e.g. v1.1, v1.2. Any breaking changes such as renaming fields or removing fields will be done very rarely, but those will increment the MAJOR number, e.g. v2.0, v3.0.

Authorization

Thankful uses Basic authentication over HTTPS in combination with other security measures.

Your application MUST use HTTPS.
Your application MUST prevent unauthorized parties from obtaining the API key.
Your application MUST validate the API key Thankful sends in the Authorization header.

You can generate and expire API keys on the API Settings page.

That is enough to protect most applications.

Some companies require additional verification, so Thankful supports the following approaches. None are necessary for your security, but they optionally layer protections on top of the Basic auth HTTPS core:

Your application MAY confirm that the X-Request-ID is unique on each request to help prevent replay attacks.
Your application MAY validate that the X-Timestamp is within a specified timeframe, such as within 30 seconds ago. This also limits replay attacks.
Your application MAY whitelist Thankful’s static IP addresses. Contact Thankful if you’d like a list of IP addresses to whitelist.

Actions

To enable any action, all of the associated endpoints MUST be implemented.

Track Order
- Get Orders
- Get Customer
Exchange Status:
- Get Orders
- Get Customer
Return Status
- Get Orders
- Get Customer
Cancel Order
Change Order
Exchange Item
Return Order
Change Discount Code
Invalid Discount Code
Change Shipping Address
Forgot Password
Missing Package
- Get Orders
- Create Order
Package Item Missing
- Get Orders
- Create Order
Pause Subscription
- Get Customers
- Update Subscription
Cancel Subscription
- Get Customers
- Update Subscription
Modify Subscription
- Get Customers
- Update Subscription
Unsubscribe
- Get Customers
- Update Customer

Endpoints

Orders
Returns
- Create Return
Customers
Discounts
- Create Discount
Subscriptions
- Update Subscription

Get Orders

Endpoint: GET /thankful/api/orders

Query parameters:

order_number
email
phone

One of the above query parameters will always be included.

Example:

GET <your_api_url>/thankful/api/orders?email=bob%40example.com

Request:
	Header:
		Authentication: Basic <your_auth_token>
		X-Request-ID: 9bsv0s23l8og00uph220
		X-Timestamp: 2019-12-31T00:00:00Z
		Content-Type: application/json
		Accept: application/json

	Body:
		<empty>

Response:
	Status: 200 OK
	Header:
		X-API-Version: v1.0
		Content-Type: application/json
	Body:
		[]Order

Create Order

Endpoint: POST /thankful/api/orders

Example:

POST <your_api_url>/thankful/api/orders

Request:
	Header:
		Authentication: Basic <your_auth_token>
		X-Request-ID: 9bsv0s23l8og00uph220
		X-Timestamp: 2019-12-31T00:00:00Z
		Content-Type: application/json
		Accept: application/json

	Body:
		Order

Response:
	Status: 200 OK
	Header:
		X-API-Version: v1.0
		Content-Type: application/json
	Body:
		Order

Update Order

Endpoint: PATCH /thankful/api/orders/:id

Example:

PATCH <your_api_url>/thankful/api/orders/123

Request:
	Header:
		Authentication: Basic <your_auth_token>
		X-Request-ID: 9bsv0s23l8og00uph220
		X-Timestamp: 2019-12-31T00:00:00Z
		Content-Type: application/json
		Accept: application/json

	Body:
		Order

Response:
	Status: 200 OK
	Header:
		X-API-Version: v1.0
		Content-Type: application/json
	Body:
		<empty>

Create Return

Endpoint: POST /thankful/api/orders/:id/returns

Example:

POST <your_api_url>/thankful/api/orders/123/returns

Request:
	Header:
		Authentication: Basic <your_auth_token>
		X-Request-ID: 9bsv0s23l8og00uph220
		X-Timestamp: 2019-12-31T00:00:00Z
		Content-Type: application/json
		Accept: application/json

	Body:
		Return

Response:
	Status: 200 OK
	Header:
		X-API-Version: v1.0
		Content-Type: application/json
	Body:
		Return

Get Customers

Endpoint: GET /thankful/api/customers

Query parameters:

email
phone

One of the above query parameters will always be included.

Example:

GET <your_api_url>/thankful/api/customers?email=bob%40example.com

Request:
	Header:
		Authentication: Basic <your_auth_token>
		X-Request-ID: 9bsv0s23l8og00uph220
		X-Timestamp: 2019-12-31T00:00:00Z
		Content-Type: application/json
		Accept: application/json

	Body:
		<empty>

Response:
	Status: 200 OK
	Header:
		X-API-Version: v1.0
		Content-Type: application/json
	Body:
		[]Customer

Get Customer

Endpoint: GET /thankful/api/customers/:id

Example:

GET <your_api_url>/thankful/api/customers/123

Request:
	Header:
		Authentication: Basic <your_auth_token>
		X-Request-ID: 9bsv0s23l8og00uph220
		X-Timestamp: 2019-12-31T00:00:00Z
		Content-Type: application/json
		Accept: application/json

	Body:
		<empty>

Response:
	Status: 200 OK
	Header:
		X-API-Version: v1.0
		Content-Type: application/json
	Body:
		Customer

Update Customer

Endpoint: PATCH /thankful/api/customers/:id

Example:

PATCH <your_api_url>/thankful/api/customers/123

Request:
	Header:
		Authentication: Basic <your_auth_token>
		X-Request-ID: 9bsv0s23l8og00uph220
		X-Timestamp: 2019-12-31T00:00:00Z
		Content-Type: application/json
		Accept: application/json

	Body:
		Customer

Response:
	Status: 200 OK
	Header:
		X-API-Version: v1.0
		Content-Type: application/json
	Body:
		<empty>

Send Password Reset

Endpoint: POST /thankful/api/customers/:id/password_reset

Example:

POST <your_api_url>/thankful/api/customers/123/password_reset

Request:
	Header:
		Authentication: Basic <your_auth_token>
		X-Request-ID: 9bsv0s23l8og00uph220
		X-Timestamp: 2019-12-31T00:00:00Z
		Content-Type: application/json
		Accept: application/json

	Body:
		<empty>

Response:
	Status: 200 OK
	Header:
		X-API-Version: v1.0
		Content-Type: application/json
	Body:
		<empty>

Create Discount

Endpoint: POST /thankful/api/orders/:id/discounts

Example:

POST <your_api_url>/thankful/api/orders/123/discounts

Request:
	Header:
		Authentication: Basic <your_auth_token>
		X-Request-ID: 9bsv0s23l8og00uph220
		X-Timestamp: 2019-12-31T00:00:00Z
		Content-Type: application/json
		Accept: application/json

	Body:
		Discount

Response:
	Status: 200 OK
	Header:
		X-API-Version: v1.0
		Content-Type: application/json
	Body:
		Discount

Update Subscription

Endpoint: PATCH /thankful/api/subscriptions/:id

Example:

PATCH <your_api_url>/thankful/api/subscriptions/123

Request:
	Header:
		Authentication: Basic <your_auth_token>
		X-Request-ID: 9bsv0s23l8og00uph220
		X-Timestamp: 2019-12-31T00:00:00Z
		Content-Type: application/json
		Accept: application/json

	Body:
		Subscription

Response:
	Status: 200 OK
	Header:
		X-API-Version: v1.0
		Content-Type: application/json
	Body:
		<empty>

Data Structures

Data structures are split into several sections to minimize the build-out based on what’s needed for the business. A certain set of fields for each data type are required for core functionality. Required fields MUST all be implemented for any endpoint which requires them. The endpoints needed for your business will depend on your tickets, and Thankful can make helpful recommendations on great places to start. See Actions for more detail on required endpoints and data-structures on an action-by-action basis.

You can opt-into more advanced features by providing additional fields, such as allowing Thankful to process returns for individual items by providing line_items, returns, and refunds information when looking up orders.

Your business can add more fields over time and Thankful will automatically adapt its workflows to use them, instantly offering customers more incredible experiences.

Each field has a name and a data type. There are core data types (int, string, float, bool), specific formats like RFC3339_timestamp which is a string in the form of “2019-12-31T00:00:00Z”, and other data structures like Address or Fulfillment. Each data structure is documented in the same way. An asterisk (*) indicates that the field might be null or not included.

All prices use whole cents (integers). Floating point numbers or strings are never used for prices.

Address
Carrier
Customer
Discount
Fulfillment
FulfillmentStatus
LineItem
Order
OrderStatus
Refund
Return
ShippingSpeed
Subscription
SubscriptionStatus

Address

A street address.

{
	street_1  string
	street_2  string
	city      string
	state     string
	country   string
	zip       string
}

Carrier

Carrier must be one of the following:

fedex
ups
usps
dhl
ontrac
apc
landmark
rr_donnelley
canada_post
la_poste
postnord
royalmail

We have hundreds of carrier integrations. If you use a different carrier, let Thankful know, and we’ll provide you the identifier.

Customer

{
	id         string
	full_name  string
	phones     []string
	emails     []string
	vip        bool
	blacklist  bool
	orders     []Order

	// For subscription companies
	subscriptions []Subscription

	// For one-off data to enable functionality beyond this framework.
	// You'll need to work with Thankful's deployment team to utilize any
	// data provided as properties. Only string key/value pairs are
	// supported.
        properties {
		key   string
		value string
	}
}

vip: indicates whether this customer should be greeted with special language and offered special policy exceptions, such as longer return windows.
blacklist: indicates whether this customer has been flagged as abusive, fraudulent, or is otherwise blacklisted, and Thankful should not interact this person.
orders: contains the history of orders placed by this customer.
subscriptions: contains the complete history of subscriptions placed by this customer, both active and inactive.

Discount

{
	id string

	// If you give pre-generated discount codes to users
	code string

	// If discounts will be applied without pre-generated codes
	amount int
	amount_type string

	created_at RFC3339_timestamp

	// For one-off data to enable functionality beyond this framework.
	// You'll need to work with Thankful's deployment team to utilize any
	// data provided as properties. Only string key/value pairs are
	// supported.
        properties {
		key   string
		value string
	}
}

amount_type: must be “flat” or “percent”

Either code OR (amount AND amount_type) must be defined.

Fulfillment

A fulfillment represents a single package or shipment.

{
	id                string
	line_item_ids     []string
	shipping_address  Address
	shipping_speed    ShippingSpeed
	carrier           Carrier
	status            FulfillmentStatus
	tracking_number   string
	tracking_url      string
	created_at        RFC3339_timestamp

	// For one-off data to enable functionality beyond this framework.
	// You'll need to work with Thankful's deployment team to utilize any
	// data provided as properties. Only string key/value pairs are
	// supported.
        properties {
		key   string
		value string
	}
}

FulfillmentStatus

FulfillmentStatus is a string enum which must have one of the following values:

not_shipped: the fulfillment has not been shipped.
shipped: the fulfillment has been handed to the carrier.

LineItem

Line item in an order represents an individual product that was purchased.

{
	product_id       string
	name             string
	price            int
	category         *string
	quantity         int
	photo_url        string
	return_eligible  bool

	// For one-off data to enable functionality beyond this framework.
	// You'll need to work with Thankful's deployment team to utilize any
	// data provided as properties. Only string key/value pairs are
	// supported.
        properties {
		key   string
		value string
	}
}

Order

{
	// Required for core functionality. If an order does not require
	// delivery (such as for digital products), leave shipping_address
	// null
	id                      string
	order_number            string
	status                  OrderStatus
	shipping_address        *Address
	fulfillments            []Fulfillment
	customer_id             string
	total_price             int
	created_at              RFC3339_timestamp

	// To control whether we allow cancellations beyond time-based SLAs
        cancel_eligible bool

	// For marketplaces with 2-sided buyer+seller transactions
	seller_shipping_address *Address
	seller_fulfillments     []Fulfillment

	// For full returns/exchange experience
	line_items  []LineItem
	returns     []Return
	refunds     []Refund

	// For sending replacement items, packages
	line_items          []LineItem
	reference_order_id  string

	// For one-off data to enable functionality beyond this framework.
	// You'll need to work with Thankful's deployment team to utilize any
	// data provided as properties. Only string key/value pairs are
	// supported.
        properties {
		key   string
		value string
	}
}

OrderStatus

OrderStatus is a string enum which must be one of the following depending on your type of business. It is important you only use the statuses for your business type and do not mix-and-match the ones below.

Traditional ecommerce where a store sells directly to a buyer use these statuses:

pending: The order is currently being processed and is awaiting payment, packaging, or shipment. Partial fulfillment such as in the case of split shipments should be marked pending.
reviewing: The order is undergoing additional fraud checks or is awaiting manual review. It may be slightly delayed or canceled.
complete: The order was completely fulfilled. All packages were shipped.
canceled_by_company: The order was canceled by the company, such as when the order fails to pass fraud review.
canceled_by_buyer: The order was canceled by the buyer at their request.

2-sided marketplaces where the seller ships directly to a buyer (i.e. there’s no review step) will use these statuses:

mp_pending: The buyer is waiting for the seller to accept their offer. This status may be skipped by marketplaces which don’t involve accepting buyer offers, in which case the status would start as accepted.
mp_accepted: The seller has accepted the buyer’s offer and has begun preparing the order for shipment.
mp_complete: The seller has shipped the entire order to the buyer.
mp_canceled_by_company: The order was canceled by the company, such as when the order fails to pass fraud review.
mp_canceled_by_buyer: The order was canceled by the buyer at their request.
mp_canceled_by_seller: The order was canceled by the seller, such as in a 2-sided marketplace.

2-sided marketplaces that connect a buyer and a seller with a middle verification step, such as to check for authenticity, will use these statuses:

vmp_pending: The buyer is waiting for the seller to accept their offer. This status may be skipped by marketplaces which don’t involve accepting buyer offers, in which case the status would start as vmp_reviewing or vmp_accepted.
vmp_reviewing: The package has been received from the seller and is being reviewed or verified.
vmp_accepted: The seller has accepted the buyer’s offer and has begun preparing the order for shipment.
vmp_in_transit_to_verify: The package is in transit from the seller to the verifying party.
vmp_verifying: The package has been received from the seller and is being verified for authenticity/correctness/completeness.
vmp_complete: The verifying party has shipped the complete order to the buyer.
vmp_canceled_by_company: The order was canceled by the company, such as when the order fails to pass fraud review.
vmp_canceled_by_buyer: The order was canceled by the buyer at their request.
vmp_canceled_by_seller: The order was canceled by the seller, such as in a 2-sided marketplace.

Refund

{
	id           string
	amount       int
	return_id    *string
	discount_id  *string
	created_at   RFC3339_timestamp

	// For one-off data to enable functionality beyond this framework.
	// You'll need to work with Thankful's deployment team to utilize any
	// data provided as properties. Only string key/value pairs are
	// supported.
        properties {
		key   string
		value string
	}
}

return_id associated with this refund. May be null.
discount_id associated with this refund. May be null.

Exactly one return_id OR discount_id must be included. Refunds with null return_id AND discount_id are invalid. Refunds that include both return_id AND discount_id are invalid.

Return

{
	id                      string
	total                   int
	adjusted                int
	refund_id               string
	returned_line_item_ids  []string
	started_at              RFC3339_timestamp
	received_at             *RFC3339_timestamp
	return_label_urls       []string
	fulfillments            []*Fulfillment

	// For one-off data to enable functionality beyond this framework.
	// You'll need to work with Thankful's deployment team to utilize any
	// data provided as properties. Only string key/value pairs are
	// supported.
        properties {
		key   string
		value string
	}
}

started_at: the time the return was initiated.
received_at: the time the items were received by the returns department. This should be null before the items are received.
returned_line_item_ids: include line items which have been received by the returns department.
total: how much the return should be worth if fully accepted, i.e. if every item is returned as described.
adjusted: how much the return was worth based on what the customer returned. For instance, if the customer did not include one of the items to be returned, adjusted would be lower than total.
return_label_urls: links to printable return label.
fulfillments: We treat a return shipment as we would any other shipment, and include relevant fulfillment information.

ShippingSpeed

ShippingSpeed is a string enum which must have one of the following values:

standard (ground, etc.)
expedited (typically 3-5 business days)
two_day
overnight
same_day

Subscription

{
	id           string
	status       SubscriptionStatus
	customer_id  CustomerID
	refunds      []*Refund
	per_year     int
	tier         string

	last_order_id            *string
	next_order_scheduled_at  *RFC3339_timestamp

	last_billed_at  *RFC3339_timestamp
	paused_until    *RFC3339_timestamp
	expires_at      *RFC3339_timestamp
	created_at      RFC3339_timestamp

	// For one-off data to enable functionality beyond this framework.
	// You'll need to work with Thankful's deployment team to utilize any
	// data provided as properties. Only string key/value pairs are
	// supported.
        properties {
		key   string
		value string
	}
}

per_year specifies how many shipments occur each year. It can be any integer, however it’s usually one of the following:
- 52 = weekly
- 26 = bi-weekly
- 12 = monthly
- 6 = bi-monthly
- 4 = quarterly
- 1 = annual
tier is your internal name for the customer’s subscription level, such as “Premium”. This may be presented to users as-is, so it should have proper capitalization.

SubscriptionStatus

SubscriptionStatus is a string enum that must be one of the following:

active
paused
trialing
canceled

Ask Support

Standard Model Spec

Table of Contents

Versioning

Authorization

Actions

Endpoints

Get Orders

Create Order

Update Order

Create Return

Get Customers

Get Customer

Update Customer

Send Password Reset

Create Discount

Update Subscription

Data Structures

Address

Carrier

Customer

Discount

Fulfillment

FulfillmentStatus

LineItem

Order

OrderStatus

Refund

Return

ShippingSpeed

Subscription

SubscriptionStatus