Overview

Introduction

Welcome to the Gooten API Documentation.

The Gooten API is organized around REST and allows you to manage orders for printing, manufacturing, and related resources within the Gooten cloud. The endpoints are intuitive and powerful, allowing you to easily make calls to retrieve information or to execute actions.

Our API is designed to have predictable, resource-oriented URLs. We use built-in HTTP features which can be understood by off-the-shelf HTTP clients. Further, we support cross-origin resource sharing (CORS) to allow you to interact securely with our API from a client-side web application (though you should remember that you should never expose your PartnerBillingKey in any public website’s client-side code).

JSON will be returned in all responses from the API, including those that are error responses.

To make the Gooten API as explorable as possible, accounts have test-mode (staging environment API keys) as well as live-mode or (production API keys). These keys are active at the same time. Data created with test-mode credentials for the staging environment will never hit our fulfillment network and will never cost anyone money.

The API documentation will start with a general overview about the design that has been implemented, followed by reference information about specific endpoints.

Authentication

You authenticate to the Gooten API by providing your recipe ID. For the Orders Method you will also need to provide a secret API key (PartnerBillingKey). You can manage and view your API Keys from your account settings page in our Admin Partner Panel.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Errors

Anytime an error occurs from an API request, the JSON response returns with HadError=true as well as the reason why. For example, lets say that you tried to submit an order without an postal/zip code. The server’s response would look as follows:

{
    "ErrorReferenceCode": "72f3c717-f204-4b4a-9b14-7c169f346235",
    "Errors": [
        {
            "AttemptedValue": "",
            "CustomState": null,
            "ErrorMessage": "'Postal Code' should not be empty.",
            "PropertyName": "Order.ShipToAddress.PostalCode"
        }
    ],
    "HadError": true
}

Therefore, we recommend checking each response to see if includes a HadError=true value in order to ascertain if an error occurred.

Since all errors are assigned IDs, anytime a user is having an issue that they can’t figure out its possible for us to look up exactly what happened during the request.

In general, 5xx indicates an error on Gooten’s end, 4xx means there was a response validation issue, and 2xx indicates success. Not all errors map cleanly onto HTTP response codes, however.

Please utilize the human-readable message if available and additional response values with more details about the error to assist in solving.

Versioning

When we make backwards-incompatible changes to the API, we up our API version so that users aren’t impacted.

The current version is 3, which can be passed in to each of our methods’ URLs. Read our API upgrades guide to see our API changelog and to learn more about backwards compatibility.

Requests

When we make backwards-incompatible changes to the API, we up our API version so that users aren’t impacted.

The current version is 3, which can be passed in to each of our methods’ URLs. Read our API upgrades guide to see our API changelog and to learn more about backwards compatibility.

Metadata

Some of the updateable Gooten objects (such as Orders) support a user-specified metedata parameter. You can use the metadata parameter to attach key-value data.

This is useful for storing additional structured information about an object. As an example, you could store your user’s account name, favorite color, or other specific value from your system on a Gooten Order object. This data can then be used for custom queries, data analytics, and many other purposes.

Examples include using metadata to store information like metadata[customer_accountID] = "12993029" or metadata[campaign] = "schoolyear2015". This is especially useful for filtering and matching to your internal systems.

Some of the objects also support a customer defined description parameter. You can use the description parameter to add annotations to items with a human-readable description.

The description and metadata information you specify will be visible with that object in the Gooten Dashboard. It will also be returned in API responses.

There are two different ways to pass parameters in a request with the API.

When passing parameters to create or update an object, parameters should be passed as a JSON object containing the appropriate attribute names and values as key-value pairs. When you use this format, you should specify that you are sending a JSON object in the header. This is done by setting the Content-Type header to application/json. This ensures that your request is interpreted correctly.

Parameters

There are two different ways to pass parameters in a request with the API.

When passing parameters to create or update an object, parameters should be passed as a JSON object containing the appropriate attribute names and values as key-value pairs. When you use this format, you should specify that you are sending a JSON object in the header. This is done by setting the Content-Type header to application/json. This ensures that your request is interpreted correctly.

When passing parameters to filter a response on GET requests, parameters can be passed using standard query attributes. In this case, the parameters would be embedded into the URI itself by appending a ? to the end of the URI and then setting each attribute with an equal sign. Attributes can be separated with a &. Tools like curl can create the appropriate URI when given parameters and values; this can also be done using the -d flag and then passing the key and value as an argument. The argument should take the form of a quoted string with the attribute being set to a value with an equal sign.

Guides

At the link below you’ll find tutorials that will teach you how to use Gooten, and reference documentation for all the moving parts. There are many different ways to implement and utilize Gooten’s platform and services. We do our best to cover the specifics needed that allow you to quickly develop with us.

Libraries

Please visit our Github for a list of our supported wrappers.

3rd Party Services

Gooten has third-party integrations which require no programming, hosting or complicated setup on your behalf, such as Shopify. Please check this page for updates and to request additional integrated services.

Addresses

Validation

The Address Object

Address Objects represent physical mailing addresses. They must be verified to guarantee successful order placement, ship price calculation, and product delivery.

Verify an address

The address verification takes a physical address as an input and it returns a validated address or suggested address if one exists and passes back a score representing the quality of the address. A reference to scores can be found here.

Arguments

line1 StringStreet Address First Line Required
line2 StringStreet Address Line 2. Example: Apt 2  
city StringAddress’s City Name Required
state StringAddress’s Two Char State Code for the USA & Canada and the State Full Name for other countries. State codes must be in full caps for a Valid Score. Required
postal code StringThe postal or zip code. Required for the countries on this list. Required
country code StringThe Country Code. Must be a 2 letter country short-name code (ISO 3166). Country Codes must be in full caps. Country codes can be found here. Required

Response Attributes

IsValid StringReturns TRUE if address has nothing needed to be changed. Returns FALSE if there is anything to improve or modify in the original input address. It is recommended to use the returned address whenever this is FALSE.  
Reason StringThis field is returned if the API is able to determine a specific problem with the input address. Examples include: Score: 95. Apartment number required.  
Score StringScore is ranked from 1 to 100. If the address has a score higher than 70% than you can use the proposed address to replace your input address. If the score is below 50 than our system was unable to verify the address nor suggest a valid address.  
ProposedAddress    
City StringThe City of the Proposed Address.  
CountryCode StringThe Country Code of the Proposed Address. Will be a 2 letter country short -name code (ISO 3166).  
PostalCode StringThe Postal Code of the Suggested Address. For US Addresses this is typically in the XxxxX-XxxX format.  
StateOrProvinceCode StringFor United States addresses this will return the two character state code.  
StreetLines StringThe Street line address of the Suggested Address.  

Products

Get products

The Product Object

product objects represent physical products. These physical products each belong to a category of products. Each product may have multiple variants or SKUs. (An example of this would be a product called t-shirt is part of the category of Apparel and has specific skus/variants that would represent the brand, size, color, of a specific t-shirt.)

Retrieve Products

Retrieving products returns a list of all products that are currently set to active in your admin store settings. It will return all products based on a variety of variables including the ship to country, the tech source, and the version of the API. Images that are returned from the service are dynamically resizable by adding width and height querystrings.

Arguments

Country Code StringThe Ship To Country. Must be a 2 letter country shortname code (ISO 3166). Country codes can be found here. Required
API Version IntegerThe version of the API you are using. By default Use version 1. Required
Source StringDescription of the source. Use API unless directed otherwise by our team. Required
All BooleanSet this to TRUE if you want to receive all Products that we have made public - not only those that are turned on in your store’s recipe.  
Language Code StringThe Two Character language code, defaults to “en” (english language) if left blank.  
Currency Code StringThree character currency code defaults to “USD” (United States Dollar) if field is left empty.  

Response Attributes

Id IntThis is a number that represents the Product Id. It is unique to each product. This id number is different between staging and live environments. Can later be passed into the productvariant service to get available product variations or SKUs.  
UId String(Deprecated) An Id that syncs between our staging and live environments.  
Name StringThe written name of the product.  
ShortDescription StringA mini summary of the product. It can be used as a brief blurb to describe the pruduct that is shorter than the full description.  
PreSelectedImageUrl String(Deprecated)  
HasAvailableProductVariants Boolean(Deprecated) Returns true if the product has product variants under it, and is not just a placeholder for future product variants.  
HasProductTemplates BooleanReturns true if the product has any variants with a template available. A template is a layout, collage, or design that is available for customization.  
FeaturedIndex IntegerThis is a value that can be used to sort products that are featured. If a product is not featured than it will return null. This value can be controlled from our Admin Panel.  
IsFeatured BooleanReturns true if the product has been set to be featured in our admin panel.  
IsComingSoon BooleanReturns true if the product is currently being worked on by our team and will be available soon. If True this product is not available for order.  
MaxZoom IntegerThe recommended minimum image size to submit for the product. As an example, if the final print ready file needs to be 100x100, a max zoom returned of 2 would mean that you shouldn’t use an image that has a size less than 50x50.  
RetailPrice    
Price DecimalThe average price for this product in the market. If this product has multiple variants it uses the average price of the lowest priced variant.  
CurrencyCode StringThe three character currency code of the order. (Example USD)  
FormattedPrice StringA price that includes the appropriate currency sign/formatting. Useful for display purposes.. (Example $74.00)  
CurrencyFormat StringThis field explains the currency formatting used in the Formatted Price attribute. ( Example ${1} ) . This is useful for if you wish to perform calculations and then display them as the currency should be displayed; one would only need to replace the {1} with the numeric-money value.  
CurrencyDigits IntThis is the number of digits after the decimal point that is included in the formatted price.  
Info StringContent describing the product.  
ContentType StringCan be either “Text” or “List”. A “Text” content type signifies that the content is in paragraph form. A “List” content type means that it is contains a list of product qualities/features.  
Content [ ] StringThe actual content. Note that for “Text” types there is always only one item in the array. For “List” types there are multiple types.  
Key StringFor “List” content type items, “Key” is a summary of what will be in the content array.  
Index IntAn integer used for sorting the content found in the “Info” array.  
ProductImage StringProduct images. Note that this contains large and small images for web, mobile, etc  
Url StringThe url of the product’s image.  
Description StringDescription of product’s image  
Id StringA unique identifier for the image  
ImageTypes    
PriceInfo    
Price DecimalThe decimal format of the item’s normal price. (Example 74)  
CurrencyCode StringThe three character currency code of the order. (Example USD)  
FormattedPrice StringA price that includes the appropriate currency sign/formatting. Useful for display purposes.. (Example $74.00)  
CurrencyFormat StringThis field explains the currency formatting used in the Formatted Price attribute. ( Example ${1} ) . This is useful for if you wish to perform calculations and then display them as the currency should be displayed; one would only need to replace the {1} with the numeric-money value.  
CurrencyDigits StringThis is the number of digits after the decimal point that is included in the formatted price.  
Categories    
Id IntThe Id Number of the category that the product belongs to. A product can belong to one or more categories. Click here to see our categories.  
Name StringThe Name of the Category that the product belongs to.  

Product Variants

The Variant Object

The productvariant object is a SKU underneath a product. Understanding the difference between a product and a productvariant is important. An example product would be “Canvas Wraps.” An example productvariant would be a “12x12 white wrapped canvas.” So productvariants are hierarchically underneath products.

Get a list of all available product variations (SKUs), or if one passes in a specific product type id (productId), gets a list of available variations of a specific product.

Arguments

Country Code StringThe Ship To Country. Must be a 2 letter country shortname code (ISO 3166). Country codes can be found here. Required
Product ID IntThe ID of the Product you are interested in. This value is returned by the Products service. Required
API Version IntegerThe version of the API you are using. Use Version 1 by default. Required
Source StringDescription of the source. Use API unless directed otherwise by our team. Required
All BooleanSet this to TRUE if you want to receive all Products that we have made public - not only those that are turned on in your store’s recipe.  
Language Code StringThe Two Character language code, defaults to “en” (english language) if left blank.  
Currency Code StringThree character currency code defaults to “USD” (United States Dollar) if field is left empty.  

Response Attributes

Product Variants  
Sku StringThe Gooten SKU for the product variant
MaxImages Integer(Deprecated) The number of images that need submitted for this item.
Has Templates BooleanReturns true if the product variant has any product templates for it.
Options The options array is the collection of all option types and values that collectively make up the attributes of the SKU or product variant.
OptionId StringA Unique ID for the option type.
ValueId StringA Unique ID for the value of the option.
Name StringThe name of the option type. Example “Shirt Size”.
Value StringThe name of the value of the option. Example “Medium”.
ImageUrl StringThis is a URL to an image that graphically demonstates the specific product option value.
ImageType String(Deprecated) Always returns WebImg.
RgbaColor String(Deprecated) Used to return color information.
CmValue StringReturns a value if the option value is a measurement of size. We store measurement values with the emperial model as standard, but include the corresponding metric values in this field.
SortValue StringThe order that the option should be sorted relative to other options of this type. As an background it would return a Small Size T-shirt with a Smaller Sort Order Number than a Large Size T-Shirt. This value allows you to easily arrange them in order.
PriceInfo  
Price DecimalThis is the item price in decimal format (Example 74)
CurrencyCode StringThe three character currency code of the order. (Example USD)
FormattedPrice StringThe currency formatted price of the item. (Example $74.00)
CurrencyFormat StringThis field explains the currency formatting used in the Formatted Price attribute. ( Example ${1} )
CurrencyDigits IntegerThis is the number of digits after the decimal point that is included in the formatted price.
Options This options array is the collection of all of the potential option types and option values that are available and are sorted by option type.
Name StringThe name of the option type or option category. Example is “Shirt Size”. Each of these option types has multiple potential option values. An example of the option value is “Medium” for the option type “Shirt Size”.
Values  
OptionId StringA Unique ID for the option type.
ValueId StringA Unique ID for the value of the option.
*Name * StringThe name of the option type. Example “Shirt Size”.
Value StringThe name of the value of the option. Example “Medium”.
ImageUrl StringThis is a URL to an image that graphically demonstates the specific product option value.
ImageType String(Deprecated) Always returns WebImg.
RgbaColor String(Deprecated) Used to return color information.
CmValue StringReturns a value if the option value is a measurement of size. We store measurement values with the emperial model as standard, but include the corresponding metric values in this field.
SortValue StringThe order that the option should be sorted relative to other options of this type. As an background it would return a Small Size T-shirt with a Smaller Sort Order Number than a Large Size T-Shirt. This value allows you to easily arrange them in order.

Product Templates

The Template Object

Product templates are a graphical design layout that represents the image file size or sizes needed to create a product of this SKU. It can represent either a single or default image size requirement or it can represent a more complex layout.

Retrieve Templates

Get a list of product templates for a specific product variant (product SKU).

Arguments

SKU StringThe Gooten SKU of the Product Variant that you would like to retrieve templates for. Required
Language Code StringThe Two Character language code, defaults to “en” (english language) if left blank.  

Response Attributes

Options  
Name StringThe name of the template.
ImageUrl StringThe preview URL of the template. This is the url of an image that can be used to demonstrate the look of the template.
IsDefault BooleanThis returns true for all templates other than those that you have added to your Gooten Store/recipe.
Category StringA field that can describe the category or type of template. It is optionally returned for templates if they contain a category value. Please contact Gooten if you would like to use this field.
IsPartnerSpecific BooleanThis returns true if the template is specific to your store’s Recipe ID and is not available to any other API users.
Spaces  
Id StringA unique identifier for a space
Index IntegerThis index is used to enforce a specific order to the spaces that make up a Product Template. With this Order or Index Value you can determine where a space fits appropriately for the template.
FinalX1 IntegerOnly returned if only part of the space should be used in the final image file that should be sent to print. (Advanced pleased discuss with the Gooten team if you plan to use.)
FinalX2 IntegerOnly returned if only part of the space should be used in the final image file that should be sent to print. (Advanced pleased discuss with the Gooten team if you plan to use.)
FinalY1 IntegerOnly returned if only part of the space should be used in the final image file that should be sent to print. (Advanced pleased discuss with the Gooten team if you plan to use.)
FinalY2 IntegerOnly returned if only part of the space should be used in the final image file that should be sent to print. (Advanced pleased discuss with the Gooten team if you plan to use.)
DefaultRotation IntegerWill return zero by default. (Advanced please discuss with the Gooten team if you plan to use.)
Description StringA description of the space within the template. A space is a specific part of an overall product design. An example of a space would be an individual page within a photobook or the Front or Back side of a shirt. Each space is then made up of vertical layers.
Layers  
Id StringA unique identifier for the layer within a space.
Description StringReturns if the layer has a specific description to help identify it. It is not typically returned.
Type StringThis is the type of layer. The type can be Design, Image, or Text. Each layer can only be of one type.
ZIndex IntegerThis index is the vertical order of each layer. Starting at zero, each layer increments by a unit of 1 as it stacks on top of the previous layer. A zindex of 2 is on top of a zindex of 1 (as if they were pieces of paper on a table).
X1 IntegerThe starting horizontal coordinate of the layer. Starting from the upper left corner of the axis.
X2 IntegerThis is the ending horizontal coordinate of the layer. It will always be an integer equal to or greater than X1.
Y1 IntegerThe starting vertical coordinate of the layer. Starting from the upper left corner of the axis.
Y2 IntegerThis is the ending vertical coordinate of the layer. It will always be an integer equal to or greater than X1.
Color StringOnly returned if the layer is a text layer. This color value is in hex format.
BackgroundImageUrl StringThis is returned for design layers with the lowest Zindex value (Typically when ZIndex is 0). This is used for previewing the other layers on the final product.
OverlayImageUrl StringThis is returned for design layers with the highest Zindex value. It is typically a partially transparent file that, when overlayed on top of all other zlayers, is used to demonstrate the final product. (Example would be showing the image on a t-shirt)
FontName StringFor text layers only. This is the name of the font that is used in the template.
FontSize StringFor text layers only. This is the point size of the font.
FontHAlingment StringThis is optionally returned only for text layers. It is the horizontal alignment of the text within the layer’s X & Y coordinates. The values will be Top, Middle, or Bottom.
FontVAlignment StringThis is optionally returned only for text layers. It is the vertical alignment of the text within the layer’s X & Y coordinates. The values will be Left, Center, or Right.
DefaultText StringThis is optionally returned only for text layers. It is the “phrase” recommended to be placed into the text space. When placing the order - it is not required to use this same text.

Shipping

Shipping Prices

Retrieve Shipping Options

Get a list of shipping options and prices for specific product variant[s].

Arguments

ShipToPostalCode StringThe shipping zipcode or postal code of the address. Required  
ShipToCountry StringThe Country Code. Must be a 2 letter country short-name code (ISO 3166). Country Codes must be in full caps. Country codes can be found here. Required  
ShipToState StringIf shipping to the US or Canada than please use the two character state code. If shipping internationally please include the full name of the state. Required  
CurrencyCode StringThree character currency code defaults to “USD” (United States Dollar) if field is left empty.    
LanguageCode StringThe Two Character language code, defaults to “en” (english language) if left blank. Required  
Items      
SKU StringThe Gooten SKU of the Product that you would like to retrieve shipping prices and options for. Required  
Quantity IntegerThe quantity of the same product ordered. If someone orders two of the sample product, sku, & product image content within the same order than this will be an integer greater than 1. Required  

Response Attributes

SKUs StringThe Gooten SKU of the Product that will be shipped.
ShipOptions  
Id IntegerThe ID that can be passed into the /orders POST endpoint as ShipCarrierMethodId to specify an item’s shipping method. This is a unique Id that is used to represent the specific product box or box grouping.
MethodType StringCan be Standard, Expedited, or Overnight. This describes the speed of the shipment offering.
MethodId IntegerAn Id that explains the method or type of shipment that this box uses. Standard MethodId is 3, Expedited MethodId is 5, Overnight MethodId is 7.
Name StringName is based on type of shipping services, therefore: Standard, Expedited or Overnight. This is a future field to contain additional details on the method.
CarrierName StringName of carrier that is responsible for delivering products to the destination.
CarrierLogoUrl StringThe logo of the carrier used for transportation and delivery of the product.
Price  
Price DecimalThe shipping price for the corresponding shipping method.
CurrencyCode StringThe three character currency code of the order. (Example USD)
FormatedPrice StringThis field explains the currency formatting used in the Formatted Price attribute. ( Example ${1} )
EstBusinessDaysTilDelivery IntegerThis is the amount of days to receive the product. It a rough approximation. This time includes production, tendering to logistics provider, shipping, and weekends when shipment & production are not occuring.

Orders

The Order Object

The order object represents a specific and unique transaction in our system. It contains all data on the transaction including the product information, content and image information, delivery information, and billing information.

Retrieve Orders

This method allows you to get basic information about an order.

Arguments

Order ID StringThe idenfitication number of the order. There are two optional IDs that can be used. One is the Safe Id that is provided by Gooten for each order and is unique. The other is the Partner Order Id (Your reference ID that you submit when placing the order). Please make sure you use unique order identifiers if you use your own Ids. Required
API Version IntegerThe version of the API you are using. Use version 1 by default unless told otherwise by the Gooten team. Required
Source StringDescription of the source. Use API unless directed otherwise by our team. Required
Language Code StringThe Two Character language code, defaults to “en” (english language) if left blank.  

Response Attributes

Id StringThe unique identifier for the order that Gooten uses within our system. This is identified as the Safe Id within the Gooten admin panel.
NiceId StringA shorter idenfier that can be optionally used for customer service purposes. This is not a guaranteed unique value, and is made up of the last name on the order combined with part of the order ID.
SourceId StringA reference order identier from your internal system. This should be the unique order number that is contained within your system. It is used for reference purposes against your data.
Items  
Sku StringThe Gooten SKU that represents the specific product variant purchased. (Example CanvsWrp-BlkWrp-12x12)
ProductId IntegerThe Gooten identifier of the type or category of product purchased. The SKU belongs to this product type id.
Product StringThe name of the product type that was purchased. (Example: Canvas Wrap)
Quantity IntegerThe quantity of the same product ordered. If someone orders two of the sample product, sku, & product image content within the same order than this will be an integer greater than 1.
Status StringThis is the current production status of the item in the order. Multi-item orders can each be a different status in an order. Please refer to this status link reference to see the possible values and the corresponding meaning.
TrackingNumber String(Deprecated) Use the Shipments array as this will be removed in a future release
TrackingUrl String(Deprecated) Use the Shipments array as this will be removed in a future release
ShipCarrierName String(Deprecated) Use the Shipments array as this will be removed in a future release
Price  
Price DecimalThe decimal format of the item’s normal price. (Example 74)
CurrencyCode StringThe three character currency code of the order. (Example USD)
FormattedPrice StringThe currency formatted price of the item. (Example $74.00)
CurrencyFormat StringThis field explains the currency formatting used in the Formatted Price attribute. ( Example ${1} )
CurrencyDigits IntegerThis is the number of digits after the decimal point that is included in the formatted price.
DiscountAmount  
Price DecimalThis is returned if the order was placed with a discount or coupon code. It is returned as the decimal format of the item’s price after the discount. (Example 37)
CurrencyCode StringThe three character currency code of the order. (Example USD)
FormattedPrice StringThe currency formatted price of the item. (Example $37.00)
CurrencyFormat StringThis field explains the currency formatting used in the Formatted Price attribute. ( Example ${1} )
CurrencyDigits IntegerThis is the number of digits after the decimal point that is included in the formatted price.
SourceId StringThis is a reference idenfier that represents the “Order Item” in your internal system. This field is optionally returned if it is provided at the time of order.
Meta This is an OPTIONAL Map of miscellaneous properties that were included in the order. See Metadata.
Key StringThe name of the meta entry. Keys should be unique within the meta map.
Value StringThe corresponding value.
Total  
Price DecimalThis is the order total. It is the decimal format of the sum of all of the prices of each item in the order. (Example 74)
CurrencyCode StringThe three character currency code of the order. (Example USD)
FormattedPrice StringThe currency formatted price of the item. (Example $74.00)
CurrencyFormat StringThis field explains the currency formatting used in the Formatted Price attribute. ( Example ${1} )
CurrencyDigits IntegerThis is the number of digits after the decimal point that is included in the formatted price.
ShippingTotal  
Price DecimalThis is the shipping total price. It is the decimal format of the sum of all of the shipping prices of each shipment in the order. (Example 12)
CurrencyCode StringThe three character currency code of the order. (Example USD)
FormattedPrice StringThe currency formatted price of the item. (Example $12.00)
CurrencyFormat StringThis field explains the currency formatting used in the Formatted Price attribute. ( Example ${1} )
CurrencyDigits IntegerThis is the number of digits after the decimal point that is included in the formatted price.
DiscountAmount  
Price DecimalThis is optionally returned if the order contains a discount on the order. It is the decimal amount of the discount. (Example 37). Please see this additional document which outlines Discounts and Coupons.
CurrencyCode StringThe three character currency code of the order. (Example USD)
FormattedPrice StringThe currency formatted price of the item. (Example $12.00)
CurrencyFormat StringThis field explains the currency formatting used in the Formatted Price attribute. ( Example ${1} )
CurrencyDigits IntegerThis is the number of digits after the decimal point that is included in the formatted price.
DiscountCode StringThis is the name or code used when the order was placed that matches to the discount that was applied. (Example 50OFF)
BillingAddress  
FirstName StringThe given name at the billing address. Example for John Doe would be “John”.
LastName StringThe surname or family name at the billing address. Example for John Doe would be “Doe”.
Line1 StringThe street address for the billing address.
Line2 StringThe apartment, suite #, or other additional street level information for the billing address.
City StringAddress’s City Name
State StringAddress’s Two Character State Code for the USA & Canada and the Full Name for other countries.
CountryCode StringThe Country Code. Must be a 2 letter country short-name code (ISO 3166). Country codes can be found here.
PostalCode StringThe postal or zip code. Provided for the countries on this list.
IsBusinessAddress BooleanReturns true if the address is a business address.
Phone StringThe billing phone number on the order.
Emai StringThe billing email address on the order.
ShippingAddress  
FirstName StringThe given name at the address. Example for John Doe would be “John”.
LastName StringThe surname or family name at the address. Example for John Doe would be “Doe”.
Line1 StringThe street address of the shipping destination.
Line2 StringThe apartment, suite #, or other additional street level information of the destination.
City StringAddress’s City Name
State StringAddress’s Two Character State Code for the USA & Canada and the Full Name for other countries. State codes must be in full caps.
CountryCode StringThe postal or zip code. Required for the countries on this list.
PostalCode StringThe Country Code. Must be a 2 letter country short-name code (ISO 3166). Country codes can be found here.
IsBusinessAddress BooleanReturns true if the address is a business address.
Phone StringThe shipping phone number on the order.
Email StringThe shipping email address on the order.
Meta StringThis is an OPTIONAL Map of miscellaneous properties that were included in the order. See Metadata.
Key StringThe name of the meta entry. Keys should be unique within the meta map.
Value StringThe corresponding value for the key.

Create an Order

This method submits an order into the Gooten platform. An order can be placed for immediate fulfillment or can be placed prior to payment with the status PrePayment. If an order is submitted as IsPreSubmit=true, it will allow you to temporarily place an order to then approve it later with an transaction conformation ID for Paypal.

Arguments

ShipToAddress The shipping information of the recipient at the destination.    
FirstName StringThe given name at the address. Example for John Doe would be “John”. Required  
LastName StringThe surname or family name at the address. Example for John Doe would be “Doe”. Required  
Line1 StringThe street address of the shipping destination. Required  
Line2 StringThe apartment, suite #, or other additional street level information of the destination.    
City StringAddress’s City Name Required  
State StringAddress’s Two Character State Code for the USA & Canada and the Full Name for other countries. State codes must be in full caps. Required  
CountryCode StringThe Country Code. Must be a 2 letter country short-name code (ISO 3166). Country Codes must be in full caps. Country codes can be found here. Required  
PostalCode StringThe postal or zip code. Required for the countries on this list. Required  
IsBusinessAddress StringSubmit TRUE if the address is a business address or FALSE if it is residential. If it is business it may not be delivered on weekends. Required  
Phone StringThe shipping phone number on the order. It should be available for the logistics provider to coordinate delivery. Required  
Email StringThe shipping email address on the order. It can be your email or your customers email. Required  
BillingAddress      
FirstName StringThe given name at the billing address. Example for John Doe would be “John”. Required  
LastName StringThe surname or family name at the billing address. Example for John Doe would be “Doe”. Required  
Line1 StringThe street address for the billing address. Required  
Line2 StringThe apartment, suite #, or other additional street level information for the billing address.    
City StringAddress’s City Name Required  
State StringAddress’s Two Character State Code for the USA & Canada and the Full Name for other countries. State codes must be in full caps. Required  
CountryCode String The Country Code. Must be a 2 letter country short -name code (ISO 3166). Country Codes must be in full caps. Country codes can be found here. Required  
PostalCode StringThe postal or zip code. Required for the countries on this list. Required  
IsBusinessAddress BooleanSubmit TRUE if the address is a business address or FALSE if it is residential. boolean Required
Phone StringThe billing phone number on the order. Required  
Email StringThe billing email address on the order. Required  
Items      
Quantity StringThis is the quantity of a specific item in an order. If there are multiple identical items in the order than use this field to indicate the quantity. An identical order item is when both the SKU and the image content are the same. Required  
SKU StringThe Gooten SKU of the order item. Required  
ShipCarrierMethodId StringPlease enter the Id you received from the Shipping Estimates method. integer Required
ShipType StringIf you do not have the methodID above, you can instead pass the shipping method here. The available methods are ‘Standard’, ‘‘Expedited’ or “Overnight’. (Standard shipping typically arrives in 3-6 days. Expedited shipping typically arrives in 2-3 days. Overnight typically arrives the next business day after shipment.)    
Images      
Url StringA public url of an image that should be printed on the order item. Please see this article on the type of images accepted per product. Required  
Index IntegerThis index is used to maintain the order of the images to be printed on the item. Read here on using the image index. integer Required
ThumbnailUrl StringThis is a public url of a preview image of the final item. It is used to compare with the final produced product. This is recommended but not mandatory for all products. (Example. It would display the image on top of the shirt overlay image.)    
ManipCommand StringThis field is Advanced and Optional. Please submit images in their final print ready format if this field is left empty. Please contact Gooten if you plan to not submit orders in their final format.    
SpaceId StringDeprecated. Please ignore this field.    
SourceId StringAn optional place to apply an internal order item id from your system. This can be used for matching order items between systems. This is not the order id but should be an ID that your system uses to identify a specific item within a multi item order. Required  
Meta This is an OPTIONAL Map of miscellaneous properties that were included in the order. See Metadata. Required  
Key StringThe name of the meta entry. Keys should be unique within the meta map. Required  
Value StringThe corresponding value Required  
Payment Contains properties that need set if you are submitting an order on credit or if you are submitting an order via Braintree.    
BraintreeEncryptedCCNumber StringFor braintree payments orders only. If you are not submitting from braintree than skip this field. If you are submitting from Braintree payments connected to the Gooten system than please see this article.    
BraintreeEncryptedCCExpDate StringFor braintree payments orders only. If you are not submitting from braintree than skip this field. If you are submitting from Braintree payments connected to the Gooten system than please see this article.    
BraintreeEncryptedCCV StringFor braintree payments orders only. If you are not submitting from braintree than skip this field. If you are submitting from Braintree payments connected to the Gooten system than please see this article.    
BraintreeEncryptedNonce StringFor braintree payments orders only. If you are not submitting from braintree than skip this field. If you are submitting from Braintree payments connected to the Gooten system than please see this article.    
PartnerBillingKey StringThis code, when passed, allows the order to be submitted on credit. It is a private key. If you are submitting an order via Braintree or Paypal this field is not required.    
Total StringThe total amount of the order.    
CurrencyCode StringThe three character currency code of the order. (Example USD). This is only required if you are passing in a value in the Total field above.    
SourceId StringAn optional place to apply an internal order id from your system for this order. This can be used for matching order items between systems.    
IsPreSubmit StringSubmit the order into PrePayment status. This is used if you are building your own client with the Gooten Paypal solution.    
CouponCode StringUse this optional field to include a Gooten coupon code for the order. This allows an order to be billed at a discounted rate. Please see this link on CouponCodes if you plan to use.    
Meta This is an OPTIONAL Map of miscellaneous properties that were included in the order. See Metadata.    
Key StringThe name of the meta entry. Keys should be unique within the meta map.    
Value StringThe corresponding value    
API Version StringThe version of the API you are using. Use 1 by default.    
Source StringDescription of the source platform. Use API unless directed otherwise by our team.    

Response Attributes

ID StringThe Gooten ID of the successfully submitted order. This ID is Unique. This is identified as the SafeID in the Admin Panel.

Print Ready Products

Retrieve

Get a list of your print ready products (pre-configured) products. The products returned are entirely specific to your recipe.

Arguments

Country Code StringThe Ship To Country. Must be a 2 letter country short-name code (ISO 3166). Country codes can be found here. Required
API Version IntegerThe version of the API you are using. Use 1 by default. Required
Source StringDescription of the source platform. Use “api” unless directed otherwise by our team. Required
Language Code StringThe Two Character language code, defaults to “en” (english language) if left empty.  
Currency Code StringA Three character currency code. This defaults to “USD” (United States Dollar) if left empty.  

Response Attributes

PreConfiguredProducts  
Sku StringA SKU that uniquely identifies the Print Ready (Preconfigured) product.
Name StringThe name of the Print Ready (Preconfigured) product.
Description StringThe Description of the Print Ready (Preconfigured) product.
Price  
Price DecimalThis is the price of the Print Ready (Preconfigured) product. (Example 12.00)
CurrencyCode StringThe three character currency code of the Print Ready product. (Example USD)
FormattedPrice StringThe currency formatted price of the Print Ready product. (Example $12.00)
CurrencyFormat StringThis field explains the currency formatting used in the Formatted Price attribute. ( Example ${1} )
CurrencyDigits IntegerThis is the number of digits after the decimal point that is included in the formatted price.
Items The item[s] that constitue the Print Ready product. A print ready product can be one SKU or a group of SKUs that together represent the print ready product.
ProductId IntegerThe ID of the product this item is a variant of.
ProductVariantSku StringThe SKU of the product that this item is a Print Ready version of.
Preconfigurations  
SpaceId StringThe ID of the space where an image is placed.
Url StringThe Url of the image in the referenced space or layer. This is the Print Ready file that is ready for Print.
Images Product Preview images. Can contain large and small images for web, mobile, etc
Url StringA Url for the Print Ready Product’s preview images.
Description StringA text description that is connected to this preview image of the Print Ready product.
Index IntegerA value to represent the order of the preview images
Id StringAn Id of the Product Preview image.

Create

Insert a print ready (pre-configured) product into your recipe.

Arguments

SKU StringSet a SKU that uniquely identifies the Print Ready product. This must be unique for each Print Ready Product. Required
Name StringSet the name of the Print Ready Product. Required
Description StringSet the description for the Print Ready Product. You can use line breaks to format the text into paragraphs. Required
Price DecimalSet the price for the Print Ready Product.  
Items The item[s] that will constitue the Print Ready product. You can make a print ready product of one SKU or a group of SKUs that together will represent the print ready product.  
ProductId IntegerThe ID of the product this item is a variant of. Required
ProductVariantSKU StringThe SKU of the product this item is a Print Ready version of. Required
Preconfigurations    
SpaceId StringRequired only for multi-image items. The ID of the space where an image is placed. One can attain the SpaceId via inspecting the template data for the product variant. For single image items our system will auto populate this field and it is not mandatory.  
Url StringThe url of the image in the referenced space/layer. This image should be formatted to the correct Print Ready Image size. Required
Images Product Preview images. Can contain large and small images for web, mobile, etc.  
Url StringA Url for preview images of the Print Ready Product.  
Description StringA text description that should be connected to this preview image of the Print Ready product.  
Index IntegerGive the images a value to represent their order. If left blank the system will assign the image a value of zero.  
Id StringGive an Id for the product preview image.  

Response Attributes

HadError BooleanReturns True if there was an error along with an explaination. If the creation was successful it will return false.

Update

Update a print ready (pre-configured) product in your recipe.

Arguments

SKU StringThe SKU that uniquely identifies the Print Ready product. This must be unique for each Print Ready Product. Required
Name StringUpdate the name of the Print Ready Product. Required
Description StringUpdate the description for the Print Ready Product. Required
Price StringUpdate the price for the Print Ready Product.  
Items The item[s] that will constitue the Print Ready product. You can make a print ready product of one SKU or a group of SKUs that together will represent the print ready product.  
ProductId IntegerThe ID of the product this item is a variant of. Required
ProductVariantSKU StringThe SKU of the product this item is a Print Ready version of. Required
Preconfigurations    
SpaceId StringRequired only for multi-image items. The ID of the space where an image is placed. One can attain the SpaceId via inspecting the template data for the product variant.  
Url StringChange the url of the image in the referenced space/layer. This image should be formatted to the correct Print Ready Image size. Required
Images Product Preview images. Can contain large and small images for web, mobile, etc.  
Url String Update the Urls for preview images of the Print Ready Product.  
Description StringA text description that should be connected to this preview image of the Print Ready product.  
Index StringUpdate the images index values. If left blank the system will assign the image a value of zero.  
Id StringGive an Id for the product preview image.  

Response Attributes

HadError BooleanReturns True if there was an error along with an explaination. If the Update was successful it will return false.

Delete

Delete a print ready product from your recipe. This command cannot be undone. This method is Coming Soon.

Arguments

SKU StringThe Print Ready Product’s SKU. Required

Response Attributes

HadError BooleanReturns True if there was an error along with an explaination. If the DELETE was successful it will return false.

Preview Generator

The Preview Object

Product previews are images that can be used to demonstrate a product to a viewer that combines a product overlay and template with specific content or imagery. The combined image is then viewed to give the user a better visual understanding of the product.

Retreive Preview

Submit an image (or images) to be rendered into a product preview.

Arguments

Sku String The Gooten SKU you want to make a preview of. Required
Template String The name of the Product Template to be used for the rendering, which can be found in the response from in the ProductTemplates method. By default use the “Single” Template for any basic single image preview. Required
Images    
SpaceId StringThe Id of the space with the type attribute set to “Image” contained in the response by the ProductTemplates (link to ProductTemplates Layer response attribute) method. Required
LayerId StringThe Id of the layer with the type attribute set to “Image” contained in the response by the ProductTemplates (link to ProductTemplates Layer response attribute) method. Required
Image    
Url StringA url of a user-provided image that you want to render into the product preview. Required
MaxFit StringSet MaxFit = true and do not specify X1..Y2 values if you wish to have your image auto-centered inside the layer you specified. Required
X1 DecimalThe X-axis (horizontal) coordinate of the top left corner to place the image at. Use the value returned for this Image layer from the Product Templates method as a default.  
X2 DecimalThe X-axis (horizontal) coordinate of the bottom right corner to place the image at. Use the value returned for this Image layer from the Product Templates method as a default.  
Y1 DecimalThe Y-axis (vertical) coordinate of the top left corner to place the image at. Use the value returned for this Image layer from the Product Templates method as a default.  
Y2 DecimalThe Y-axis (vertical) coordinate of the bottom right corner to place the image at. Use the value returned for this Image layer from the Product Templates method as a default.  
MaxHeight IntegerUse this optional method to set a max-height of the resolution of the product preview image. Defaults to 500px  
MaxWidth IntegerUse this optional method to set a max-width of the resolution of the product preview image. Defaults to 500px  

Response Attributes

Images  
Url StringA Url of the image that will be generated for the Product Preview. The image will be loaded asynchronously.
SpaceId StringThe SpaceId in order to indicate the specific space that was rendered here.
HadError BooleanWill return TRUE if there was an error and FALSE if the post was successful.
ErrorMessage StringAn text description of the error if HadError is TRUE.

Price Estimate

Retrieve

Get an estimated price of a potential order, including discounts from a coupon.

Arguments

Version IntegerThe version of the API you are using. Use “1” as default. Required
Source StringDescription of the source. Use “api” unless directed otherwise by our team. Required
ShipToAddress The shipping information of the recipient at the destination. Required
First Name StringThe given name at the address. Example for John Doe would be “John”. Required
Last Name StringThe surname or family name at the address. Example for John Doe would be “Doe”. Required
Line1 StringThe street address of the shipping destination. Required
Line2 StringThe apartment, suite #, or other additional street level information of the destination.  
City StringAddress’s City Name Required
State StringAddress’s Two Character State Code for the USA & Canada and the Full Name for other countries. State codes must be in full caps. Required
CountryCode StringThe Country Code. Must be a 2 letter country short-name code (ISO 3166). Country Codes must be in full caps. Country codes can be found here. Required
PostalCode StringThe postal or zip code. Required for the countries on this list. Required
IsBusinessAddress StringSubmit TRUE if the address is a business address or FALSE if it is residential. If it is business it may not be delivered on weekends. Required
Phone StringThe shipping phone number on the order. It should be available for the logistics provider to coordinate delivery. Required
Email StringThe shipping email address on the order. It can be your email or your customers email. Required
Items    
Quantity StringThis is the quantity of a specific item in an order. If there are multiple identical items in the order than use this field to indicate the quantity. An identical order item is when both the SKU and the image content are the same. Required
SKU StringThe Gooten SKU of the order item. Required
ShipCarrierMethodId StringPlease enter the ShipMethod Id you received from the Shipping Estimates method. Required
Images    
Url StringA public url of an image that should be printed on the order item. Please see this article on the type of images accepted per product.  
Index IntegerThis index is used to maintain the order of the images to be printed on the item. Read here on using the image index.  
ThumbnailUrl Stringhis is a public url of a preview image of the final item. It is used to compare with the final produced product. This is recommended but not mandatory for all products. (Example. It would display the image on top of the shirt overlay image.)  
ManipCommand StringThis field is Advanced and Optional. Please submit images in their final print ready format if this field is left empty. Please contact Gooten if you plan to not submit orders in their final format.  
SpaceId String(Deprecated)  
Payment    
CurrencyCode StringThe three character currency code of the order. (Example USD) Required
CouponCode StringAn optional coupon code to be applied to the order.  

Response Attributes

Items    
Price DecimalThe decimal format of the item’s normal or non-discounted price. (Example 74)  
CurrencyCode StringThe three character currency code of the order. (Example USD)  
FormattedPrice StringThe currency formatted price of the item. (Example $74.00)  
CurrencyFormat StringThis field explains the currency formatting used in the Formatted Price attribute. ( Example ${1} )  
CurrencyDigits IntegerThis is the number of digits after the decimal point that is included in the formatted price.  
Shipping    
Price DecimalThe decimal format of the item’s normal or non-discounted shipping price. (Example 12)  
CurrencyCode StringThe three character currency code of the order. (Example USD)  
FormattedPrice StringThe currency formatted price of the item. (Example $12.00)  
CurrencyFormat StringThis field explains the currency formatting used in the Formatted Price attribute. ( Example ${1} )  
CurrencyDigits IntegerThis is the number of digits after the decimal point that is included in the formatted price.  
Tax    
Price DecimalThe decimal format of the item’s tax. (Example 6)  
CurrencyCode StringThe three character currency code of the order. (Example USD)  
FormattedPrice StringThe currency formatted price of the item. (Example $6.00)  
CurrencyFormat StringThis field explains the currency formatting used in the Formatted Price attribute. ( Example ${1} )  
CurrencyDigits IntegerThis is the number of digits after the decimal point that is included in the formatted price.  
CouponSavings    
Price DecimalThis is optionally returned if the order contains a discount on the order. It is the decimal amount of the discount. (Example if the order is 50 dollars and the discount is 50% off than this field will have the value of “25”)  
CurrencyCode StringThe three character currency code of the order. (Example USD)  
FormattedPrice StringThe currency formatted price of the item. (Example $12.00)  
CurrencyFormat String This field explains the currency formatting used in the Formatted Price attribute. ( Example ${1} )  
CurrencyDigits IntegerThis is the number of digits after the decimal point that is included in the formatted price.  
CouponType StringThis field represents the type of coupon that was applied. Please see this article for more information on Coupon Types.  
CouponUsed StringThis is the name or code used when the order was placed that matches to the discount that was applied. (Example 50OFF)  
HadCouponApply BooleanReturns TRUE if a coupon was applied to the price estimate and FALSE if a coupon was NOT applied.  
DollarsOff DecimalDecimal number of the amount that is taken off the regular price if a coupon was applied.  
PercentOff DecimalPercentage discount for which regular price was decreased if a coupon was applied.  
HadError BooleanWill return TRUE if there was an error and FALSE if the post was successful.  

Optional Services

Images

Image File Store Object

Accepts files POSTed via form/multipart. Returns their temporary location.

Arguments

Create a image file store

Images FileForm/multipart file post Required

Response Attributes

Images Image

Countries

Retrieve Supported Countries

Get a list of supported countries. Output is in specified language.

Arguments

LanguageCode StringThe Two Character language code, defaults to “en” (english language) if left blank.  
Key StringA string used to query the language dictionary for specific values within a category.  

Response Attributes

Countries  
Name StringName of the country
Code StringThe 2 letter country short-name code (ISO 3166).
IsSupported BooleanWill return TRUE if we support shipments to this country. Will return FALSE if we do not currenly ship to this country.
MeasurementCode StringWill return “INCH” if the country uses the Imperial system of measurement or “CM” if the country uses the Metric system of measurement.
FlagUrl StringA URL of an image of the country flag
DefaultCurrency  
Name StringThe name of the currency in which price will be expressed from our system.
Code StringThe three character currency code for the Currency. Example is “USD” for the United States Dollar
Format StringThis field explains the currency formatting used in the Formatted Price attribute. ( Example ${1} )

Currencies

Retrieve Supported Currencies

Get a list of supported currencies. Output is in specified language.

Arguments

LanguageCode StringThe Two Character language code, defaults to “en” (english language) if left blank.  
Key StringA string used to query the language dictionary for specific values within a category.  

Response Attributes

Currencies  
Name StringThe name of the currency in which price will be expressed from our system.
Code StringThe three character currency code for the Currency. Example is “USD” for the United States Dollar
Format StringThis field explains the currency formatting used in the Formatted Price attribute. ( Example ${1} )

Languages

Retrieve Supported Languages

Returns application/item text in a specified language. Currently this method is not available for public use.

Arguments

LanguageCode StringThe Two Character language code of the language you want to return the string in.  
Key StringA string used to query the language dictionary for specific values within a category.  

Response Attributes

Category String
Values String

User Info

Retrieve User Info

This method will utilize the user’s IP-based information to return information about their identity.

Arguments

LanguageCode StringThe Two Character language code, defaults to “en” (english language) if left blank.  

Response Attributes

LanguageCode StringThe users likely two-character language code, such as “en” (english)
CountryCode StringThe users likely Ship To Country based on their IP. Will be the countries short-name code (ISO 3166).
CountryName StringThe name of the users likely Ship to Country based on their IP.
CurrencyName StringThe name of the currency in which price should likely be expressed based on their IP.
CurrencyCode StringThe three character currency code of the likely currency.
CurrencyFormat StringThis field explains the currency formatting used in the Formatted Price attribute. ( Example ${1} )

Payment Validation

Retrieve payment validation

This method allows you to submit payment validation for Paypal orders. It will validate a specific orderID if a paypal validation Key is provided.

Arguments

OrderID StringIdentification number of an order. This is the Safe Id of the order that is returned from the Orders POST method. Required
PaypalKey StringThe PayPal key returned for the order from Paypals SDK. Required

Response Attributes

IsValid BooleanReturns TRUE if the payment validation is successful and returns FALSE if the payment validation is unsuccessful.